MsiExtractPatchXMLDataA function (msi.h)

The MsiExtractPatchXMLData function extracts information from a patch that can be used to determine if the patch applies to a target system. The function returns an XML string that can be provided to MsiDeterminePatchSequence and MsiDetermineApplicablePatches instead of the full patch file. The returned information can be used to determine whether the patch is applicable.

Syntax

UINT MsiExtractPatchXMLDataA(
  [in]                LPCSTR  szPatchPath,
  [in]                DWORD   dwReserved,
  [out, optional]     LPSTR   szXMLData,
  [in, out, optional] LPDWORD pcchXMLData
);

Parameters

[in] szPatchPath

The full path to the patch that is being queried. Pass in as a null-terminated string. This parameter cannot be NULL.

[in] dwReserved

A reserved argument that must be 0 (zero).

[out, optional] szXMLData

A pointer to a buffer to hold the XML string that contains the extracted patch information. This buffer should be large enough to contain the received information. If the buffer is too small, the function returns ERROR_MORE_DATA and sets *pcchXMLData to the number of TCHAR in the value, not including the terminating NULL character.

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

[in, out, optional] pcchXMLData

A pointer to a variable that specifies the number of TCHAR in the szXMLData 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.

If this parameter is set to NULL, the function returns ERROR_INVALID_PARAMETER.

Return value

The MsiExtractPatchXMLData function can return the following values.

Return code Description
ERROR_FUNCTION_FAILED
The function failed in a way that is not identified by any of the return values in this table.
ERROR_INVALID_PARAMETER
An invalid parameter was passed to the function.
ERROR_MORE_DATA
The value does not fit in the provided buffer.
ERROR_PATCH_OPEN_FAILED
The patch file could not be opened.
ERROR_SUCCESS
The function was successful.
ERROR_PATCH_PACKAGE_INVALID
The patch file could not be opened.
ERROR_CALL_NOT_IMPLEMENTED
This error can be returned if MSXML 3.0 is not installed.

Remarks

The ExtractPatchXMLData method of the Installer object uses the MsiExtractPatchXMLData function.

Note

The msi.h header defines MsiExtractPatchXMLData 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 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

See also

MsiDetermineApplicablePatches

MsiDeterminePatchSequence

Not Supported in Windows Installer 2.0 and earlier