PropVariantToBSTR function (propvarutil.h)

Article
10/13/2021

Extracts the BSTR property value of a PROPVARIANT structure.

Syntax

PSSTDAPI PropVariantToBSTR(
  [in]  REFPROPVARIANT propvar,
  [out] BSTR           *pbstrOut
);

Parameters

[in] propvar

Type: REFPROPVARIANT

Reference to a source PROPVARIANT structure.

[out] pbstrOut

Type: BSTR*

Pointer to the extracted property value if one exists; otherwise, contains an empty string.

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 string value.

If the source PROPVARIANT has type VT_BSTR or VT_LPWSTR, this function extracts the string as a BSTR value. Otherwise, it attempts to convert the value in the PROPVARIANT structure into a string. If a conversion is not possible, PropVariantToBSTR returns a failure code and sets pbstrOut to NULL. See PropVariantChangeType for a list of possible conversions.

VT_EMPTY is successfully converted to an allocated BSTR containing "".

The calling application is responsible for using SysFreeString to release the BSTR pointed to by pbstrOut when it is no longer needed.

In addition to the conversions provided by PropVariantChangeType, the following special cases apply to PropVariantToBSTR.

Vector-valued PROPVARIANTs are converted to strings by separating each element with using "; ". For example, PropVariantToBSTR converts a vector of 3 integers, {3, 1, 4}, to the string "3; 1; 4". The semicolon is independent of the current locale.
VT_BLOB, VT_STREAM, VT_STREAMED_OBJECT, and VT_UNKNOWN values are converted to strings through an unsupported encoding. It is not possible to decode strings created in this way and the format may change in the future.

Examples

The following example, to be included as part of a larger program, demonstrates how to use PropVariantToBSTR to access a string value in a PROPVARIANT.

// IPropertyStore *ppropstore;
// Assume the variable ppropstore is initialized and valid.
PROPVARIANT propvar = {0};

HRESULT hr = ppropstore->GetValue(PKEY_Title, &propvar);

if (SUCCEEDED(hr))
{
    // PKEY_Title is expected to produce a VT_LPWSTR or VT_EMPTY value.
    // PropVariantToBSTR will convert VT_EMPTY to "".
    BSTR bstrTitle;
    
    hr = PropVariantToBSTR(propvar, &bstrTitle);
    
    if (SUCCEEDED(hr))
    {
        // bstrTitle is now valid.
    }
    else
    {
        // bstrTitle is always NULL.
    }
    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

Share via