MsiProvideQualifiedComponentExA function (msi.h)
The MsiProvideQualifiedComponentEx function returns the full component path for a qualified component that is published by a product and performs any necessary installation. This function prompts for source if necessary and increments the usage count for the feature.
Syntax
UINT MsiProvideQualifiedComponentExA(
[in] LPCSTR szCategory,
[in] LPCSTR szQualifier,
[in] DWORD dwInstallMode,
[in] LPCSTR szProduct,
[in] DWORD dwUnused1,
[in] DWORD dwUnused2,
[out] LPSTR lpPathBuf,
[in, out] LPDWORD pcchPathBuf
);
Parameters
[in] szCategory
Specifies the component ID that for the requested component. This may not be the GUID for the component itself but rather a server that provides the correct functionality, as in the ComponentId column of the PublishComponent table.
[in] szQualifier
Specifies a qualifier into a list of advertising components (from PublishComponent Table).
[in] dwInstallMode
Defines the installation mode. This parameter can be one of the following values.
| Value | Meaning |
|---|---|
|
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. |
|
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. |
|
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. |
|
Provide the component only if the feature exists, else return ERROR_FILE_NOT_FOUND. |
|
Call MsiReinstallFeature to reinstall feature using this parameter for the dwReinstallMode parameter, and then provide the component. |
|
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. |
[in] szProduct
Specifies the product to match that has published the qualified component. If this is null, then this API works the same as MsiProvideQualifiedComponent.
[in] dwUnused1
Reserved. Must be zero.
[in] dwUnused2
Reserved. Must be zero.
[out] lpPathBuf
Pointer to a variable that receives the path to the component. This parameter can be null.
[in, out] pcchPathBuf
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
| Value | Meaning |
|---|---|
|
Component qualifier invalid or not present. |
|
The function completed successfully. |
|
The feature is absent or broken. this error is returned for dwInstallMode = INSTALLMODE_EXISTING. |
|
The specified component is unknown. |
|
See Error Codes. |
| An error relating to initialization occurred. |
Remarks
Upon success of the MsiProvideQualifiedComponentEx function, the pcchPathBuf parameter contains the length of the string in lpPathBuf.
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.
Note
The msi.h header defines MsiProvideQualifiedComponentEx as an alias which automatically selects the ANSI or Unicode version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more information, see Conventions for Function Prototypes.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | 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. |
| Target Platform | Windows |
| Header | msi.h |
| Library | Msi.lib |
| DLL | Msi.dll |