PropVariantToStrRet 函数 (propvarutil.h)

项目
03/05/2024

从 PROPVARIANT 结构中提取字符串，并将其放入 STRRET 结构中。

语法

PSSTDAPI PropVariantToStrRet(
  [in]  REFPROPVARIANT propvar,
  [out] STRRET         *pstrret
);

参数

[in] propvar

类型： REFPROPVARIANT

对源 PROPVARIANT 结构的引用。

[out] pstrret

类型： STRRET*

指向 STRRET 结构。当此函数返回时，结构已初始化为包含提取的字符串的副本。

返回值

类型： HRESULT

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

注解

此帮助程序函数用于希望将 PROPVARIANT 结构中的字符串值转换为 STRRET 结构的应用程序。例如，实现 IShellFolder：：GetDisplayNameOf 的应用程序可能会发现此函数很有用。

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

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

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

如果提取成功，函数将使用 STRRET_WSTR 初始化 STRRET 结构的 uType 成员，并将该结构的 pOleStr 成员设置为指向字符串的已分配副本。调用应用程序负责在不再需要时使用 CoTaskMemFree 或 StrRetToStr 释放此字符串。

示例

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

// IPropertyStore *ppropstore;

// Assume variable ppropstore is initialized and valid

PROPVARIANT propvar = {0};

HRESULT hr = ppropstore->GetValue(PKEY_FileName, &propvar);

if (SUCCEEDED(hr))

{

    // PKEY_FileName is expected to produce a VT_LPWSTR or VT_EMPTY value.

    // PropVariantToStrRet will convert VT_EMPTY to "".

    // If this were an implementation of IShellFolder::GetDisplayNameOf, strName would be a parameter and the caller would free the memory associated with the STRRET

    STRRET strName;

    hr = PropVariantToStrRet(propvar, &strName);

    if (SUCCEEDED(hr))

    {

        // strName is now valid

 

        if (strName.uType == STRRET_WSTR)

        {

            CoTaskMemFree(strName.pOleStr);

        }

    }

    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