MsiGetPropertyA function (msiquery.h)
The MsiGetProperty function gets the value for an installer property.
Syntax
UINT MsiGetPropertyA(
[in] MSIHANDLE hInstall,
[in] LPCSTR szName,
[out] LPSTR szValueBuf,
[in, out] LPDWORD pcchValueBuf
);
Parameters
[in] hInstall
Handle to the installation provided to a DLL custom action or obtained through MsiOpenPackage, MsiOpenPackageEx, or MsiOpenProduct.
[in] szName
A null-terminated string that specifies the name of the property.
[out] szValueBuf
Pointer to the buffer that receives the null terminated string containing the value of the property. Do not attempt to determine the size of the buffer by passing in a null (value=0) for szValueBuf. You can get the size of the buffer by passing in an empty string (for example ""). The function will then return ERROR_MORE_DATA and pchValueBuf will contain the required buffer size in TCHARs, not including the terminating null character. On return of ERROR_SUCCESS, pcchValueBuf contains the number of TCHARs written to the buffer, not including the terminating null character.
[in, out] pcchValueBuf
Pointer to the variable that specifies the size, in TCHARs, of the buffer pointed to by the variable szValueBuf. When the function returns ERROR_SUCCESS, this variable contains the size of the data copied to szValueBuf, not including the terminating null character. If szValueBuf is not large enough, the function returns ERROR_MORE_DATA and stores the required size, not including the terminating null character, in the variable pointed to by pchValueBuf.
Return value
This function returns UINT.
Remarks
If the value for the property retrieved by the MsiGetProperty function is not defined, it is equivalent to a 0-length value. It is not an error.
If ERROR_MORE_DATA is returned, the parameter which is a pointer gives the size of the buffer required to hold the string. If ERROR_SUCCESS is returned, it gives the number of characters written to the string buffer. Therefore you can get the size of the buffer by passing in an empty string (for example "") for the parameter that specifies the buffer. Do not attempt to determine the size of the buffer by passing in a Null (value=0).
The following example shows how a DLL custom action could access the value of a property by dynamically determining the size of the value buffer.
UINT __stdcall MyCustomAction(MSIHANDLE hInstall)
{
TCHAR* szValueBuf = NULL;
DWORD cchValueBuf = 0;
UINT uiStat = MsiGetProperty(hInstall, TEXT("MyProperty"), TEXT(""), &cchValueBuf);
//cchValueBuf now contains the size of the property's string, without null termination
if (ERROR_MORE_DATA == uiStat)
{
++cchValueBuf; // add 1 for null termination
szValueBuf = new TCHAR[cchValueBuf];
if (szValueBuf)
{
uiStat = MsiGetProperty(hInstall, TEXT("MyProperty"), szValueBuf, &cchValueBuf);
}
}
if (ERROR_SUCCESS != uiStat)
{
if (szValueBuf != NULL)
delete[] szValueBuf;
return ERROR_INSTALL_FAILURE;
}
// custom action uses MyProperty
// ...
delete[] szValueBuf;
return ERROR_SUCCESS;
}
Note
The msiquery.h header defines MsiGetProperty 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. Windows Installer on Windows Server 2003 or Windows XP |
| Target Platform | Windows |
| Header | msiquery.h |
| Library | Msi.lib |
| DLL | Msi.dll |