EN
此内容没有您的语言版本,但有英语版本。

PropVariantToBSTR function

Extracts the BSTR property value of a PROPVARIANT structure.

Syntax


HRESULT PropVariantToBSTR(
  _In_   REFPROPVARIANT propvar,
  _Out_  BSTR *pbstrOut
);

Parameters

propvar [in]

Type: REFPROPVARIANT

Reference to a source PROPVARIANT structure.

pbstrOut [out]

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

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

PropVariantToString
PropVariantToStringWithDefault
PropVariantGetStringElem
InitPropVariantFromString

 

 

社区附加资源

添加
显示:
© 2014 Microsoft