PropVariantToUInt64 function (propvarutil.h)
Extracts a UInt64 value from a PROPVARIANT structure. If no value can be extracted, then a default value is assigned.
Syntax
PSSTDAPI PropVariantToUInt64(
[in] REFPROPVARIANT propvarIn,
[out] ULONGLONG *pullRet
);
Parameters
[in] propvarIn
Type: REFPROPVARIANT
Reference to a source PROPVARIANT structure.
[out] pullRet
Type: ULONGLONG*
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 ULONGLONG value. For instance, an application obtaining values from a property store can use this to safely extract the ULONGLONG value for UInt64 properties.
If the source PROPVARIANT has type VT_UI8, this helper function extracts the ULONGLONG value. Otherwise, it attempts to convert the value in the PROPVARIANT structure into a ULONGLONG. If a conversion is not possible, PropVariantToUInt64 will return a failure code and set pullRet 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 PropVariantToUInt64 to access a ULONGLONG value in a PROPVARIANT.
// IPropertyStore *ppropstore;
// Assume variable ppropstore is initialized and valid
PROPVARIANT propvar = {0};
HRESULT hr = ppropstore->GetValue(PKEY_Size, &propvar);
if (SUCCEEDED(hr))
{
// PKEY_Size is expected to produce a VT_UI8 or VT_EMPTY value.
// PropVariantToUInt64 will convert VT_EMPTY to 0.
ULONGLONG ullSize;
hr = PropVariantToUInt64(propvar, &ullSize);
if (SUCCEEDED(hr))
{
// ullSize is now valid
}
else
{
// ullSize 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 |