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.

Windows Installer 2.0:  Not supported. This function is available beginning with Windows Installer version 3.0.

Syntax

C++UINT MsiEnumPatchesEx(
  __in_opt     LPCTSTR szProductCode,
  __in_opt     LPCTSTR szUserSid,
  __in         DWORD dwContext,
  __in         DWORD dwFilter,
  __in         DWORD dwIndex,
  __out_opt    TCHAR szPatchCode[39],
  __out_opt    TCHAR szTargetProductCode[39],
  __out_opt    MSIINSTALLCONTEXT *pdwTargetProductContext,
  __out_opt    LPTSTR szTargetUserSid,
  __inout_opt  LPDWORD pcchTargetUserSid
);

Parameters

szProductCode [in, optional]

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.

szUserSid [in, optional]

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.

SID type	Meaning
NULL	Specifies the currently logged-on user.
User SID	An enumeration for a specific user in the system. An example of user SID is "S-1-3-64-2415071341-1358098788-3127455600-2561".
s-1-1-0	An enumeration across all users in the system.

 

Note  The special SID string s-1-5-18 (System) cannot be used to enumerate products or patches installed as per-machine. Setting the SID value to s-1-5-18 returns ERROR_INVALID_PARAMETER. When dwContext is set to MSIINSTALLCONTEXT_MACHINE only, szUserSid must be null.

dwContext [in]

Restricts the enumeration to one or a combination of contexts. This parameter can be any one or a combination of the following values.

Context	Meaning
MSIINSTALLCONTEXT_USERMANAGED	The enumeration that is extended to all per-user-managed installations for the users that szUserSid specifies. An invalid SID returns no items.
MSIINSTALLCONTEXT_USERUNMANAGED	In this context, only patches installed with Windows Installer version 3.0 are enumerated for users that are not the current user. For the current user, the function enumerates all installed and new patches. An invalid SID for szUserSid returns no items.
MSIINSTALLCONTEXT_MACHINE	An enumeration that is extended to all per-machine installations. When dwContext is set to MSIINSTALLCONTEXT_MACHINE only, the szUserSid parameter must be null.

 

dwFilter [in]

The filter for enumeration. This parameter can be one or a combination of the following parameters.

Filter	Meaning
MSIPATCHSTATE_APPLIED 1	The enumeration includes patches that have been applied. Enumeration does not include superseded or obsolete patches.
MSIPATCHSTATE_SUPERSEDED 2	The enumeration includes patches that are marked as superseded.
MSIPATCHSTATE_OBSOLETED 4	The enumeration includes patches that are marked as obsolete.
MSIPATCHSTATE_REGISTERED 8	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.
MSIPATCHSTATE_ALL 15	The enumeration includes all applied, obsolete, superseded, and registered patches.

 

dwIndex [in]

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.

szPatchCode [out, optional]

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.

szTargetProductCode [out, optional]

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.

pdwTargetProductContext [out, optional]

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.

szTargetUserSid [out, optional]

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.

pcchTargetUserSid [in, out, optional]

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.

Remarks

Non-administrators can enumerate patches within their visibility only. Administrators can enumerate patches for other user contexts.

Requirements

See Also

MsiSourceListAddSourceEx

ProductCode

Installation Context

Send comments about this topic to Microsoft

Build date: 8/13/2009