VariantToBoolean function

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

Syntax

HRESULT VariantToBoolean(
  _In_  REFVARIANT varIn,
  _Out_ BOOL       *pfRet
);

Parameters

varIn [in]

Type: REFVARIANT

Reference to a source VARIANT structure.

pfRet [out]

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

See also

InitVariantFromBoolean

VariantToBooleanArray

PropVariantToBoolean

PropVariantChangeType