MsiEnumProductsExA function (msi.h)
The MsiEnumProductsEx function enumerates through one or all the instances of products that are currently advertised or installed in the specified contexts. This function supersedes MsiEnumProducts.
Syntax
UINT MsiEnumProductsExA(
[in, optional] LPCSTR szProductCode,
[in] LPCSTR szUserSid,
[in] DWORD dwContext,
[in] DWORD dwIndex,
[out, optional] CHAR [39] szInstalledProductCode,
[out, optional] MSIINSTALLCONTEXT *pdwInstalledContext,
[out, optional] LPSTR szSid,
[in, out, optional] LPDWORD pcchSid
);
Parameters
[in, optional] szProductCode
ProductCode GUID of the product to be enumerated. Only instances of products within the scope of the context specified by the szUserSid and dwContext parameters are enumerated. This parameter can be set to NULL to enumerate all products in the specified context.
[in] szUserSid
Null-terminated string that specifies a security identifier (SID) that restricts the context of enumeration. The special SID string s-1-1-0 (Everyone) specifies enumeration across all users in the system. A SID value other than s-1-1-0 is considered a user-SID and restricts enumeration to the current user or any user in the system. This parameter can be set to NULL to restrict the enumeration scope to the current user.
[in] dwContext
Restricts the enumeration to a context. This parameter can be any one or a combination of the values shown in the following table.
[in] dwIndex
Specifies the index of the product to retrieve. This parameter must be zero for the first call to the MsiEnumProductsEx function and then incremented for subsequent calls. The index should be incremented, only if the previous call has returned ERROR_SUCCESS. Because products are not ordered, any new product has an arbitrary index. This means that the function can return products in any order.
[out, optional] szInstalledProductCode
Null-terminated string of TCHAR that gives the ProductCode GUID of the product instance being enumerated. This parameter can be NULL.
[out, optional] pdwInstalledContext
Returns the context of the product instance being enumerated. The output value can be MSIINSTALLCONTEXT_USERMANAGED, MSIINSTALLCONTEXT_USERUNMANAGED, or MSIINSTALLCONTEXT_MACHINE. This parameter can be NULL.
[out, optional] szSid
An output buffer that receives the string SID of the account under which this product instance exists. This buffer returns an empty string for an instance installed in a per-machine context.
This buffer should be large enough to contain the SID. If the buffer is too small, the function returns ERROR_MORE_DATA and sets *pcchSid to the number of TCHAR in the SID, not including the terminating NULL character.
If szSid is set to NULL and pcchSid is set to a valid pointer, the function returns ERROR_SUCCESS and sets *pcchSid to the number of TCHAR in the value, not including the terminating NULL. The function can then be called again to retrieve the value, with the szSid buffer large enough to contain *pcchSid + 1 characters.
If szSid and pcchSid are both set to NULL, the function returns ERROR_SUCCESS if the value exists, without retrieving the value.
[in, out, optional] pcchSid
When calling the function, this parameter should be a pointer to a variable that specifies the number of TCHAR in the szSid buffer. When the function returns, this parameter is set to the size of the requested value whether or not the function copies the value into the specified buffer. The size is returned as the number of TCHAR in the requested value, not including the terminating null character.
This parameter can be set to NULL only if szSid is also NULL, otherwise the function returns ERROR_INVALID_PARAMETER.
Return value
The MsiEnumProductsEx function returns one of the following values.
| Return code | Description |
|---|---|
|
If the scope includes users other than the current user, you need administrator privileges. |
|
The configuration data is corrupt. |
|
An invalid parameter was passed to the function. |
|
There are no more products to enumerate. |
|
A product is enumerated. |
|
The szSid parameter is too small to get the user SID. |
|
The product is not installed on the computer in the specified context. |
|
An unexpected internal failure. |
Remarks
To enumerate products, an application must initially call the MsiEnumProductsEx function with the iIndex parameter set to zero. The application must then increment the iProductIndex parameter and call MsiEnumProductsEx until it returns ERROR_NO_MORE_ITEMS and there are no more products to enumerate.
When making multiple calls to MsiEnumProductsEx to enumerate all of the products, each call must be made from the same thread.
A user must have administrator privileges to enumerate products across all user accounts or a user account other than the current user account. The enumeration skips products that are advertised only (such as products not installed) in the per-user-unmanaged context when enumerating across all users or a user other than the current user.
Use MsiGetProductInfoEx to get the state or other information about each product instance enumerated by MsiEnumProductsEx.
Note
The msi.h header defines MsiEnumProductsEx as an alias that 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 is 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 3.0 or later 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 |