PropVariantToString 函数 (propvarutil.h)

项目
08/25/2023

从 PROPVARIANT 结构中提取字符串值。

语法

PSSTDAPI PropVariantToString(
  [in]  REFPROPVARIANT propvar,
  [out] PWSTR          psz,
  [in]  UINT           cch
);

parameters

[in] propvar

类型： REFPROPVARIANT

对源 PROPVARIANT 结构的引用。

[out] psz

类型： PWSTR

指向字符串缓冲区。当此函数返回时，使用 NULL 终止的 Unicode 字符串值初始化缓冲区。

[in] cch

类型： UINT

psz 指向的缓冲区的大小（以字符为单位）。

返回值

类型： HRESULT

此函数可以返回其中一个值。

返回代码	说明
S_OK	已提取值，结果缓冲区以 NULL 结尾。
STRSAFE_E_INSUFFICIENT_BUFFER	由于缓冲区空间不足，复制操作失败。目标缓冲区包含截断的、以 null 结尾的预期结果版本。在可以接受截断的情况下，这可能不一定被视为故障条件。
其他一些错误值	由于其他原因，提取失败。

注解

此帮助程序函数用于调用应用程序要求 PROPVARIANT 保存字符串值的位置。例如，从属性存储区获取值的应用程序可以使用它安全地提取字符串属性的字符串值。

如果源 PROPVARIANT 具有类型VT_LPWSTR或 VT_BSTR，则此函数将提取字符串并将其放入提供的缓冲区中。否则，它会尝试将 PROPVARIANT 结构中的值转换为字符串。如果无法转换， PropVariantToString 将返回失败代码并将 psz 设置为“\0”。有关可能转换的列表，请参阅 PropVariantChangeType 。请注意， VT_EMPTY 已成功转换为“”。

除了终止 NULL 之外，最多 将 cch-1 字符写入 psz 指向的缓冲区。如果源 PROPVARIANT 中的值长于缓冲区中的长度，则将字符串的截断 NULL 终止副本写入缓冲区，此函数 返回STRSAFE_E_INSUFFICIENT_BUFFER。生成的字符串将始终以 NULL 结尾。

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

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

示例

以下示例将作为更大的程序的一部分包含，演示如何使用 PropVariantToString 访问 PROPVARIANT 中的字符串值。

// 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.

    // PropVariantToString will convert VT_EMPTY to "".

    // The application decided that it only needs the first 127 characters of the title, so the buffer 

    // has size 128 to account for the terminating NULL.

    WCHAR szTitle[128];

    hr = PropVariantToString(propvar, szTitle, ARRAYSIZE(szTitle));

    if (SUCCEEDED(hr) || hr == STRSAFE_E_INSUFFICIENT_BUFFER)

    {

        // szTitle is now valid and contains up to 127 characters from propvar and a terminating NULL

    }

    else

    {

        // the extraction failed

    }

    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