PropVariantToStrRet function (propvarutil.h)

Article
10/13/2021

Extracts a string from a PROPVARIANT structure and places it into a STRRET structure.

Syntax

PSSTDAPI PropVariantToStrRet(
  [in]  REFPROPVARIANT propvar,
  [out] STRRET         *pstrret
);

Parameters

[in] propvar

Type: REFPROPVARIANT

Reference to a source PROPVARIANT structure.

[out] pstrret

Type: STRRET*

Points to the STRRET structure. When this function returns, the structure has been initialized to contain a copy of the extracted 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 applications that wish to convert a string value in a PROPVARIANT structure into a STRRET structure. For instance, an application implementing IShellFolder::GetDisplayNameOf may find this function useful.

If the source PROPVARIANT has type VT_LPWSTR or VT_BSTR, this function extracts the string and places it into the STRRET structure. Otherwise, it attempts to convert the value in the PROPVARIANT structure into a string. If a conversion is not possible, PropVariantToString will return a failure code. See PropVariantChangeType for a list of possible conversions. Of note, VT_EMPTY is successfully converted to "".

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

Vector-valued PROPVARIANTs are converted to strings by separating each element with using "; ". For example, PropVariantToString 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.

If the extraction is successful, the function will initialize uType member of the STRRET structure with STRRET_WSTR and set the pOleStr member of that structure to point to an allocated copy of the string. The calling application is responsible for using CoTaskMemFree or StrRetToStr to free this string when it is no longer needed.

Examples

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

// IPropertyStore *ppropstore;

// Assume variable ppropstore is initialized and valid

PROPVARIANT propvar = {0};

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

if (SUCCEEDED(hr))

{

    // PKEY_FileName is expected to produce a VT_LPWSTR or VT_EMPTY value.

    // PropVariantToStrRet will convert VT_EMPTY to "".

    // If this were an implementation of IShellFolder::GetDisplayNameOf, strName would be a parameter and the caller would free the memory associated with the STRRET

    STRRET strName;

    hr = PropVariantToStrRet(propvar, &strName);

    if (SUCCEEDED(hr))

    {

        // strName is now valid

 

        if (strName.uType == STRRET_WSTR)

        {

            CoTaskMemFree(strName.pOleStr);

        }

    }

    else

    {

        // the extraction failed

    }

    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