Export (0) Print
Expand All
Expand Minimize
This topic has not yet been rated - Rate this topic

MsiProvideComponent function

The MsiProvideComponent function returns the full component path, performing any necessary installation. This function prompts for source if necessary and increments the usage count for the feature.

Syntax


UINT MsiProvideComponent(
  _In_     LPCTSTR szProduct,
  _In_     LPCTSTR szFeature,
  _In_     LPCTSTR szComponent,
  _In_     DWORD dwInstallMode,
  _Out_    LPTSTR lpPathBuf,
  _Inout_  DWORD *pcchPathBuf
);

Parameters

szProduct [in]

Specifies the product code for the product that contains the feature with the necessary component.

szFeature [in]

Specifies the feature ID of the feature with the necessary component.

szComponent [in]

Specifies the component code of the necessary component.

dwInstallMode [in]

Defines the installation mode. This parameter can be one of the following values.

ValueMeaning
INSTALLMODE_DEFAULT

Provide the component and perform any installation necessary to provide the component. If the key file of a component in the requested feature, or a feature parent, is missing, reinstall the feature using MsiReinstallFeature with the following flag bits set: REINSTALLMODE_FILEMISSING, REINSTALLMODE_FILEOLDERVERSION, REINSTALLMODE_FILEVERIFY, REINSTALLMODE_MACHINEDATA, REINSTALLMODE_USERDATA and REINSTALLMODE_SHORTCUT.

INSTALLMODE_EXISTING

Provide the component only if the feature exists. Otherwise return ERROR_FILE_NOT_FOUND.

This mode verifies that the key file of the component exists.

INSTALLMODE_NODETECTION

Provide the component only if the feature exists. Otherwise return ERROR_FILE_NOT_FOUND.

This mode only checks that the component is registered and does not verify that the key file of the component exists.

combination of the REINSTALLMODE flags

Call MsiReinstallFeature to reinstall feature using this parameter for the dwReinstallMode parameter, and then provide the component.

INSTALLMODE_NOSOURCERESOLUTION

Provide the component only if the feature's installation state is INSTALLSTATE_LOCAL. If the feature's installation state is INSTALLSTATE_SOURCE, return ERROR_INSTALL_SOURCE_ABSENT. Otherwise return ERROR_FILE_NOT_FOUND. This mode only checks that the component is registered and does not verify that the key file exists.

 

lpPathBuf [out]

Pointer to a variable that receives the path to the component. This parameter can be null.

pcchPathBuf [in, out]

Pointer to a variable that specifies the size, in characters, of the buffer pointed to by the lpPathBuf parameter. On input, this is the full size of the buffer, including a space for a terminating null character. If the buffer passed in is too small, the count returned does not include the terminating null character.

If lpPathBuf is null, pcchBuf can be null.

Return value

ValueMeaning
ERROR_BAD_CONFIGURATION

The configuration data is corrupt.

ERROR_FILE_NOT_FOUND

The feature is absent or broken. this error is returned for dwInstallMode = INSTALLMODE_EXISTING.

ERROR_INSTALL_FAILURE

The installation failed.

ERROR_INSTALL_NOTUSED

The component being requested is disabled on the computer.

ERROR_INVALID_PARAMETER

An invalid parameter was passed to the function.

ERROR_SUCCESS

The function completed successfully.

ERROR_UNKNOWN_FEATURE

The feature ID does not identify a known feature.

ERROR_UNKNOWN_PRODUCT

The product code does not identify a known product.

INSTALLSTATE_UNKNOWN

An unrecognized product or a feature name was passed to the function.

ERROR_MORE_DATA

The buffer overflow is returned.

ERROR_INSTALL_SOURCE_ABSENT

Unable to detect a source.

 

For more information, see Displayed Error Messages.

Remarks

Upon success of the MsiProvideComponent function, the pcchPathBuf parameter contains the length of the string in lpPathBuf.

The MsiProvideComponent function combines the functionality of MsiUseFeature, MsiConfigureFeature, and MsiGetComponentPath. You can use the MsiProvideComponent function to simplify the calling sequence. However, because this function increments the usage count, use it with caution to prevent inaccurate usage counts. The MsiProvideComponent function also provides less flexibility than the series of individual calls.

If the application is recovering from an unexpected situation, the application has probably already called MsiUseFeature and incremented the usage count. In this case, the application should call MsiConfigureFeature instead of MsiProvideComponent to avoid incrementing the count again.

The INSTALLMODE_EXISTING option cannot be used in combination with the REINSTALLMODE flag.

Features with components containing a corrupted file or the wrong version of a file must be explicitly reinstalled by the user or by having the application call MsiReinstallFeature.

Requirements

Version

Windows Installer 5.0 on Windows Server 2012, Windows 8, Windows Server 2008 R2 or Windows 7. Windows Installer 4.0 or Windows Installer 4.5 on Windows Server 2008 or Windows Vista. Windows Installer on Windows Server 2003 or Windows XP. See the Windows Installer Run-Time Requirements for information about the minimum Windows service pack that is required by a Windows Installer version.

Header

Msi.h

Library

Msi.lib

DLL

Msi.dll

Unicode and ANSI names

MsiProvideComponentW (Unicode) and MsiProvideComponentA (ANSI)

See also

Component-Specific Functions
Multiple-Package Installations

 

 

Did you find this helpful?
(1500 characters remaining)
Thank you for your feedback

Community Additions

ADD
Show:
© 2014 Microsoft. All rights reserved.