Export (0) Print
Expand All
Expand Minimize

PropVariantToStrRet function

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

Syntax


HRESULT PropVariantToStrRet(
  _In_   REFPROPVARIANT propvar,
  _Out_  STRRET *pstrret
);

Parameters

propvar [in]

Type: REFPROPVARIANT

Reference to a source PROPVARIANT structure.

pstrret [out]

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

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
PropVariantToStringAlloc
PropVariantToStringVector
PropVariantGetStringElem
PropVariantChangeType
StrRetToStr
VariantToStrRet

 

 

Community Additions

ADD
Show:
© 2014 Microsoft