The MsiGetPatchInfoEx function queries for information about the application of a patch to a specified instance of a product.

Syntax

C++UINT MsiGetPatchInfoEx(
  __in       LPCTSTR szPatchCode,
  __in       LPCTSTR szProductCode,
  __in       LPCTSTR szUserSid,
  __in       MSIINSTALLCONTEXT dwContext,
  __in       LPCTSTR szProperty,
  __out_opt  LPTSTR lpValue,
  __inout    DWORD *pcchValue
);

Parameters

szPatchCode [in]

A null-terminated string that contains the GUID of the patch. This parameter cannot be null.

szProductCode [in]

A null-terminated string that contains the ProductCode GUID of the product instance. This parameter cannot be null.

szUserSid [in]

A null-terminated string that specifies the security identifier (SID) under which the instance of the patch being queried exists. Using a null value specifies the current user.

SID	Meaning
NULL	Specifies the user that is logged on.
User SID	Specifies the enumeration for a specific user ID in the system. The following example identifies a possible user SID: "S-1-3-64-2415071341-1358098788-3127455600-2561".

 

Note  The special SID string s-1-5-18 (system) cannot be used to enumerate products installed as per-machine. If dwContext is MSIINSTALLCONTEXT_MACHINE, szUserSid must be null.

dwContext [in]

Restricts the enumeration to a per-user-unmanaged, per-user-managed, or per-machine context. This parameter can be any one of the following values.

Context	Meaning
MSIINSTALLCONTEXT_USERMANAGED 1	Query that is extended to all per–user-managed installations for the users that szUserSid specifies.
MSIINSTALLCONTEXT_USERUNMANAGED 2	Query that is extended to all per–user-unmanaged installations for the users that szUserSid specifies.
MSIINSTALLCONTEXT_MACHINE 4	Query that is extended to all per-machine installations.

 

szProperty [in]

A null-terminated string that specifies the property value to retrieve. The szProperty parameter can be one of the following:

Name	Meaning
INSTALLPROPERTY_LOCALPACKAGE "LocalPackage"	Gets the cached patch file that the product uses.
INSTALLPROPERTY_TRANSFORMS "Transforms"	Gets the set of patch transforms that the last patch installation applied to the product. This value may not be available for per-user, non-managed applications if the user is not logged on.
INSTALLPROPERTY_INSTALLDATE "InstallDate"	Get the date and time when the patch is applied to the product.
INSTALLPROPERTY_UNINSTALLABLE "Uninstallable"	Returns "1" if the patch is marked as possible to uninstall from the product. In this case, the installer can still block the uninstallation if this patch is required by another patch that cannot be uninstalled.
INSTALLPROPERTY_PATCHSTATE "State"	Returns "1" if this patch is currently applied to the product. Returns "2" if this patch is superseded by another patch. Returns "4" if this patch is obsolete. These values correspond to the constants the dwFilter parameter of MsiEnumPatchesEx uses.
INSTALLPROPERTY_DISPLAYNAME "DisplayName"	Get the registered display name for the patch. For patches that do not include the DisplayName property in the MsiPatchMetadata table, the returned display name is an empty string ("").
INSTALLPROPERTY_MOREINFOURL "MoreInfoURL"	Get the registered support information URL for the patch. For patches that do not include the MoreInfoURL property in the MsiPatchMetadata table, the returned support information URL is an empty string ("").

 

lpValue [out, optional]

This parameter is a pointer to a buffer that receives the property value. This buffer should be large enough to contain the information. If the buffer is too small, the function returns ERROR_MORE_DATA and sets *pcchValue to the number of TCHAR in the property value, not including the terminating NULL character.

If lpValue is set to NULL and pcchValue is set to a valid pointer, the function returns ERROR_SUCCESS and sets *pcchValue 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 lpValue buffer large enough to contain *pcchValue + 1 characters.

If lpValue and pcchValue are both set to NULL, the function returns ERROR_SUCCESS if the value exists, without retrieving the value.

pcchValue [in, out]

When calling the function, this parameter should be a pointer to a variable that specifies the number of TCHAR in the lpValue 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 lpValue is also NULL. Otherwise, the function returns ERROR_INVALID_PARAMETER.

Return Value

The MsiGetPatchInfoEx function returns the following values.

Return code	Description
ERROR_ACCESS_DENIED	The function fails trying to access a resource with insufficient privileges.
ERROR_BAD_CONFIGURATION	The configuration data is corrupt.
ERROR_FUNCTION_FAILED	The function fails and the error is not identified in other error codes.
ERROR_INVALID_PARAMETER	An invalid parameter is passed to the function.
ERROR_MORE_DATA	The value does not fit in the provided buffer.
ERROR_SUCCESS	The patch is enumerated successfully.
ERROR_UNKNOWN_PRODUCT	The product that szProduct specifies is not installed on the computer.
ERROR_UNKNOWN_PROPERTY	The property is unrecognized.
ERROR_UNKNOWN_PATCH	The patch is unrecognized.

 

Remarks

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

A user may query patch data for any product instance that is visible. The administrator group can query patch data for any product instance and any user on the computer. Not all values are guaranteed to be available for per-user, non-managed applications if the user is not logged on.

Requirements

Version	Windows Installer 5.0 on 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, Windows XP, and Windows 2000. See the Windows Installer Run-Time Requirements for information about the minimum Windows service pack that is required by a Windows Installer version.
Header	Msi.h
Library	Msi.lib
DLL	Msi.dll
Unicode and ANSI names	MsiGetPatchInfoExW (Unicode) and MsiGetPatchInfoExA (ANSI)

See Also

Removing Patches

ProductCode

Send comments about this topic to Microsoft

Build date: 8/13/2009