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