MsiProvideComponent

[This is preliminary documentation and subject to change.]

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.

UINT MsiProvideComponent(
  LPCTSTR szProduct,    // product code in case install required
  LPCTSTR szFeature,    // feature ID in case install required
  LPCTSTR szComponent,  // component ID
  DWORD dwInstallMode,  // the install mode
  LPTSTR lpPathBuf,     // returned path to component key file
  DWORD *pcchPathBuf    // in/out buffer character count
);
 

Parameters

szProduct
Specifies the product code for the product that contains the feature with the necessary component.
szFeature
Specifies the feature ID of the feature with the necessary component.
szComponent
Specifies the component code of the necessary component.
dwInstallMode
Defines the installation mode. This parameter can be one of the following values.
Value Meaning
INSTALLMODE_DEFAULT Provide the component, performing any installation, if necessary.
INSTALLMODE_EXISTING Provide the component only if the feature exists, else return ERROR_FILE_NOT_FOUND.
combination of the REINSTALLMODE flags Call MsiReinstallFeature to reinstall feature using this parameter for the dwReinstallMode parameter, and then provide the component.

lpPathBuf
Pointer to a variable that receives the path to the component. This parameter can be NULL.
pcchPathBuf
Pointer to a variable that specifies the size, in characters, of the buffer pointed to by the lpPathBuf parameter.

If lpPathBuf is NULL, pcchBuf can be NULL.

Return Values

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_INSTALL_SERVICE_FAILURE
The installation service could not be accessed.
ERROR_INSTALL_SUSPEND
The installation was suspended and is incomplete.
ERROR_INSTALL_USEREXIT
The user canceled the installation.
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.

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

QuickInfo

  Windows NT: Requires version 4.0 or later. Available as a redistributable for Windows NT 4.0.
  Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
  Windows CE: Unsupported.
  Header: Declared in msi.h.
  Import Library: Use msi.lib.
  Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

Component-Specific Functions