PropVariantToStringAlloc 函数 (propvarutil.h)
从 PROPVARIANT 结构中提取字符串属性值。
语法
PSSTDAPI PropVariantToStringAlloc(
[in] REFPROPVARIANT propvar,
[out] PWSTR *ppszOut
);
参数
[in] propvar
类型： REFPROPVARIANT
对源 PROPVARIANT 结构的引用。
[out] ppszOut
类型： PWSTR*
当此函数返回时，包含指向提取的属性值（如果存在）的指针。
返回值
类型： HRESULT
如果此函数成功，则返回 S_OK。 否则，将返回 HRESULT 错误代码。
注解
此帮助程序函数用于调用应用程序要求 PROPVARIANT 保存字符串值的位置。
如果源 PROPVARIANT 的类型VT_LPWSTR或VT_BSTR，则此函数会将字符串提取到新分配的缓冲区中。 否则，它会尝试将 PROPVARIANT 结构中的值转换为字符串。 如果无法转换， PropVariantToStringAlloc 将返回失败代码并将 ppszOut 设置为 NULL。 有关可能转换的列表，请参阅 PropVariantChangeType 。 请注意， VT_EMPTY 已成功转换为包含“”的已分配缓冲区。
调用应用程序负责使用 CoTaskMemFree 在不再需要 时释放 ppszOut 指向的字符串。
除了 PropVariantChangeType 提供的转换外，以下特殊情况也适用于 PropVariantToStringAlloc。
- 矢量值 PROPVARIANT 转换为字符串，方法是使用“; ”分隔每个元素。 例如， PropVariantToStringAlloc 将 3 个整数 {3， 1， 4} 的向量转换为字符串“3;1;4". 分号独立于当前区域设置。
- VT_BLOB、VT_STREAM、VT_STREAMED_OBJECT和VT_UNKNOWN值使用不受支持的编码转换为字符串。 无法解码以这种方式创建的字符串，并且格式将来可能会更改。
示例
// IPropertyStore *ppropstore;
// Assume 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.
// PropVariantToStringAlloc will convert VT_EMPTY to "".
LPWSTR pszTitle;
hr = PropVariantToString(propvar, &pszTitle);
if (SUCCEEDED(hr))
{
// pszTitle is now valid
}
else
{
// pszTitle 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 |