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 |