MsiEnumPatchesExA function (msi.h)
The MsiEnumPatchesEx function enumerates all patches in a specific context or across all contexts. Patches already applied to products are enumerated. Patches that have been registered but not yet applied to products are also enumerated.
Syntax
UINT MsiEnumPatchesExA(
[in, optional] LPCSTR szProductCode,
[in, optional] LPCSTR szUserSid,
[in] DWORD dwContext,
[in] DWORD dwFilter,
[in] DWORD dwIndex,
[out, optional] CHAR [39] szPatchCode,
[out, optional] CHAR [39] szTargetProductCode,
[out, optional] MSIINSTALLCONTEXT *pdwTargetProductContext,
[out, optional] LPSTR szTargetUserSid,
[in, out, optional] LPDWORD pcchTargetUserSid
);
Parameters
[in, optional] szProductCode
A null-terminated string that specifies the ProductCode GUID of the product whose patches are enumerated. If non-NULL, patch enumeration is restricted to instances of this product under the user and context specified by szUserSid and dwContext. If NULL, the patches for all products under the specified context are enumerated.
[in, optional] szUserSid
A 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 that user. When enumerating for a user other than current user, any patches that were applied in a per-user-unmanaged context using a version less than Windows Installer version 3.0, are not enumerated. This parameter can be set to NULL to specify the current user.
[in] dwContext
Restricts the enumeration to one or a combination of contexts. This parameter can be any one or a combination of the following values.
[in] dwFilter
The filter for enumeration. This parameter can be one or a combination of the following parameters.
| Filter | Meaning |
|---|---|
|
The enumeration includes patches that have been applied. Enumeration does not include superseded or obsolete patches. |
|
The enumeration includes patches that are marked as superseded. |
|
The enumeration includes patches that are marked as obsolete. |
|
The enumeration includes patches that are registered but not yet applied. The MsiSourceListAddSourceEx function can register new patches.
Note Patches registered for users other than current user and applied in the per-user-unmanaged context are not enumerated.
|
|
The enumeration includes all applied, obsolete, superseded, and registered patches. |
[in] dwIndex
The index of the patch to retrieve. This parameter must be zero for the first call to the MsiEnumPatchesEx function and then incremented for subsequent calls. The dwIndex parameter should be incremented only if the previous call returned ERROR_SUCCESS.
[out, optional] szPatchCode
An output buffer to contain the GUID of the patch being enumerated. The buffer should be large enough to hold the GUID. This parameter can be NULL.
[out, optional] szTargetProductCode
An output buffer to contain the ProductCode GUID of the product that receives this patch. The buffer should be large enough to hold the GUID. This parameter can be NULL.
[out, optional] pdwTargetProductContext
Returns the context of the patch being enumerated. The output value can be MSIINSTALLCONTEXT_USERMANAGED, MSIINSTALLCONTEXT_USERUNMANAGED, or MSIINSTALLCONTEXT_MACHINE. This parameter can be NULL.
[out, optional] szTargetUserSid
An output buffer that receives the string SID of the account under which this patch instance exists. This buffer returns an empty string for 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 *pcchTargetUserSid to the number of TCHAR in the value, not including the terminating NULL character.
If the szTargetUserSid is set to NULL and pcchTargetUserSid is set to a valid pointer, the function returns ERROR_SUCCESS and sets *pcchTargetUserSid to the number of TCHAR in the value, not including the terminating NULL character. The function can then be called again to retrieve the value, with szTargetUserSid buffer large enough to contain *pcchTargetUserSid + 1 characters.
If szTargetUserSid and pcchTargetUserSid are both set to NULL, the function returns ERROR_SUCCESS if the value exists, without retrieving the value.
[in, out, optional] pcchTargetUserSid
A pointer to a variable that specifies the number of TCHAR in the szTargetUserSid 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 szTargetUserSid is also NULL, otherwise the function returns ERROR_INVALID_PARAMETER.
Return value
The MsiEnumPatchesEx function returns one of the following values.
| Return code | Description |
|---|---|
|
The function fails trying to access a resource with insufficient privileges. |
|
The configuration data is corrupt. |
|
An invalid parameter is passed to the function. |
|
There are no more patches to enumerate. |
|
The patch is successfully enumerated. |
|
The product that szProduct specifies is not installed on the computer in the specified contexts. |
|
This is returned when pcchTargetUserSid points to a buffer size less than required to copy the SID. In this case, the user can fix the buffer and call MsiEnumPatchesEx again for the same index value. |
Remarks
Non-administrators can enumerate patches within their visibility only. Administrators can enumerate patches for other user contexts.
Note
The msi.h header defines MsiEnumPatchesEx 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. 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 |