MsiEnumPatchesExW 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 MsiEnumPatchesExW(
  [in, optional]      LPCWSTR           szProductCode,
  [in, optional]      LPCWSTR           szUserSid,
  [in]                DWORD             dwContext,
  [in]                DWORD             dwFilter,
  [in]                DWORD             dwIndex,
  [out, optional]     WCHAR [39]        szPatchCode,
  [out, optional]     WCHAR [39]        szTargetProductCode,
  [out, optional]     MSIINSTALLCONTEXT *pdwTargetProductContext,
  [out, optional]     LPWSTR            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.

[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.

Remarks

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

Requirements

See also

Installation Context

MsiSourceListAddSourceEx

Not Supported in Windows Installer 2.0 and earlier

ProductCode