PropVariantToStringAlloc function

Extracts a string property value from a PROPVARIANT structure.

Syntax


HRESULT PropVariantToStringAlloc(
  _In_  REFPROPVARIANT propvar,
  _Out_ PWSTR          *ppszOut
);

Parameters

propvar [in]

Type: REFPROPVARIANT

Reference to a source PROPVARIANT structure.

ppszOut [out]

Type: PWSTR*

When this function returns, contains a pointer to the extracted property value if one exists.

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_LPWSTR or VT_BSTR, this function extracts the string into a newly allocated buffer. Otherwise, it attempts to convert the value in the PROPVARIANT structure into a string. If a conversion is not possible, PropVariantToStringAlloc will return a failure code and set ppszOut to NULL. See PropVariantChangeType for a list of possible conversions. Of note, VT_EMPTY is successfully converted to an allocated buffer containing "".

The calling application is responsible for using CoTaskMemFree to release the string pointed to by ppszOut when it is no longer needed.

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

  • Vector-valued PROPVARIANTs are converted to strings by separating each element with using "; ". For example, PropVariantToStringAlloc 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 using an unsupported encoding. It is not possible to decode strings created in this way and the format may change in the future.

Examples


// IPropertyStore *ppropstore;

// Assume 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.

    // PropVariantToStringAlloc will convert VT_EMPTY to "".

    LPWSTR pszTitle;

    hr = PropVariantToString(propvar, &pszTitle);

    if (SUCCEEDED(hr))

    {

        // pszTitle is now valid

    }

    else

    {

        // pszTitle is always NULL

    }

    PropVariantClear(&propvar);

}

Requirements

Minimum supported client

Windows XP with SP2, Windows Vista [desktop apps only]

Minimum supported server

Windows Server 2003 with SP1 [desktop apps only]

Redistributable

Windows Desktop Search (WDS) 3.0

Header

Propvarutil.h

Library

Propsys.lib

DLL

Propsys.dll (version 6.0 or later)

See also

InitPropVariantFromString
PropVariantToString
PropVariantToStringVector
VariantToString
PropVariantChangeType

 

 

Show: