PropVariantToBSTR 函数 (propvarutil.h)

  • 项目

提取 PROPVARIANT 结构的 BSTR 属性值。

语法

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

参数

[in] propvar

类型： REFPROPVARIANT

对源 PROPVARIANT 结构的引用。

[out] pbstrOut

类型： BSTR*

指向提取的属性值（如果存在）的指针;否则，包含一个空字符串。

返回值

类型： HRESULT

如果此函数成功，则返回 S_OK。 否则，将返回 HRESULT 错误代码。

注解

此帮助程序函数用于调用应用程序要求 PROPVARIANT 保存字符串值的位置。

如果源 PROPVARIANT 的类型 VT_BSTR 或VT_LPWSTR，则此函数会将字符串提取为 BSTR 值。 否则，它会尝试将 PROPVARIANT 结构中的值转换为字符串。 如果无法进行转换， PropVariantToBSTR 将返回失败代码并将 pbstrOut 设置为 NULL。 有关可能转换的列表，请参阅 PropVariantChangeType 。

VT_EMPTY 已成功转换为包含“”的已分配 BSTR。

调用应用程序负责在不再需要时使用 SysFreeString 释放 pbstrOut 指向的 BSTR。

除了 PropVariantChangeType 提供的转换外，以下特殊情况也适用于 PropVariantToBSTR。

  • 矢量值 PROPVARIANT 转换为字符串，方法是使用“;”分隔每个元素。 例如， PropVariantToBSTR 将 3 个整数 {3， 1， 4} 的向量转换为字符串“3;1;4". 分号独立于当前区域设置。
  • VT_BLOB、VT_STREAM、VT_STREAMED_OBJECT和VT_UNKNOWN值通过不支持的编码转换为字符串。 无法解码以这种方式创建的字符串，并且格式将来可能会更改。

示例

以下示例将作为较大程序的一部分包含，演示如何使用 PropVariantToBSTR 访问 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);
}

要求

要求 值
最低受支持的客户端 Windows XP SP2、Windows Vista [仅限桌面应用]
最低受支持的服务器 Windows Server 2003 SP1 [仅限桌面应用]
目标平台 Windows
标头 propvarutil.h
Library Propsys.lib
DLL Propsys.dll (版本 6.0 或更高版本)
可再发行组件 Windows 桌面搜索 (WDS) 3.0

另请参阅

InitPropVariantFromString

PropVariantGetStringElem

PropVariantToString

PropVariantToStringWithDefault