VariantToBoolean function (propvarutil.h)

Article
10/13/2021

Extracts the value of a Boolean property from a VARIANT structure. If no value can be extracted, then a default value is assigned.

Syntax

PSSTDAPI VariantToBoolean(
  [in]  REFVARIANT varIn,
  [out] BOOL       *pfRet
);

Parameters

[in] varIn

Type: REFVARIANT

Reference to a source VARIANT structure.

[out] pfRet

Type: BOOL*

When this function returns, contains the extracted value if one exists; otherwise, FALSE.

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 when the calling application expects a VARIANT to hold a Boolean value. For instance, an application that obtains values from a Shell folder can use this function to safely extract the value from one of the folder's Boolean properties.

If the source VARIANT is of type VT_BOOL, this function extracts the BOOL value.

If the source VARIANT is not of type VT_BOOL, this function attempts to convert the value in the VARIANT structure into a BOOL. If a conversion is not possible, VariantToBoolean returns a failure code and sets pfRet to FALSE. See PropVariantChangeType for a list of possible conversions. Of note, VT_EMPTY is successfully converted to FALSE.

Examples

The following example, to be included as part of a larger program, demonstrates how to use VariantToBoolean to access a BOOL value in a VARIANT.

// VARIANT var;
// Assume variable var is initialize and valid. 
// The application expects it to hold a VT_BOOL value.
BOOL fValue;

HRESULT hr = VariantToBoolean(var, &fValue);

if (SUCCEEDED(hr))
{
    // fValue is now valid.
}
else
{
    // fValue is always FALSE.
}

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