PropVariantToUInt16 function (propvarutil.h)
Extracts a unsigned short value from a PROPVARIANT structure. If no value can be extracted, then a default value is assigned.
Syntax
PSSTDAPI PropVariantToUInt16(
[in] REFPROPVARIANT propvarIn,
[out] USHORT *puiRet
);
Parameters
[in] propvarIn
Type: REFPROPVARIANT
Reference to a source PROPVARIANT structure.
[out] puiRet
Type: USHORT*
When this function returns, contains the extracted property value if one exists; otherwise, 0.
Return value
Type: HRESULT
If this function succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.
Remarks
This helper function is used in places where the calling application expects a PROPVARIANT to hold a unsigned short value. For instance, an application obtaining values from a property store can use this to safely extract the unsigned short value for UInt16 properties.
If the source PROPVARIANT has type VT_UI2, this helper function extracts the unsigned short value. Otherwise, it attempts to convert the value in the PROPVARIANT structure into a USHORT. If a conversion is not possible, PropVariantToUInt16 will return a failure code and set puiRet to 0. See PropVariantChangeType for a list of possible conversions. Of note, VT_EMPTY is successfully converted to 0.
Examples
The following example, to be included as part of a larger program, demonstrates how to use PropVariantToUInt16 to access a unsigned short value in a PROPVARIANT.
// IPropertyStore *ppropstore;
// Assume variable ppropstore is initialized and valid
PROPVARIANT propvar = {0};
HRESULT hr = ppropstore->GetValue(PKEY_FlagColor, &propvar);
if (SUCCEEDED(hr))
{
// PKEY_FlagColor is expected to produce a VT_UI2 or VT_EMPTY value.
// PropVariantToUInt16 will convert VT_EMPTY to 0.
USHORT uColor;
hr = PropVariantToUInt16(propvar, & uColor);
if (SUCCEEDED(hr))
{
// uColor is now valid
}
else
{
// uColor is always 0
}
PropVariantClear(&propvar);
}
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows XP with SP2, Windows Vista [desktop apps only] |
| Minimum supported server | Windows Server 2003 with SP1 [desktop apps only] |
| Target Platform | Windows |
| Header | propvarutil.h |
| Library | Propsys.lib |
| DLL | Propsys.dll (version 6.0 or later) |
| Redistributable | Windows Desktop Search (WDS) 3.0 |