PropVariantToStringWithDefault 函数 (propvarutil.h)

项目
03/04/2024

提取 PROPVARIANT 结构的字符串属性值。如果不存在任何值，则返回指定的默认值。

语法

PSSTDAPI_(PCWSTR) PropVariantToStringWithDefault(
  [in] REFPROPVARIANT propvarIn,
  [in] LPCWSTR        pszDefault
);

参数

[in] propvarIn

类型： REFPROPVARIANT

对源 PROPVARIANT 结构的引用。

[in] pszDefault

类型： LPCWSTR

指向默认 Unicode 字符串值的指针，用于当前不存在值的位置。可能为 NULL。

返回值

类型： PCWSTR

返回字符串值、默认值或默认值。

注解

此帮助程序函数用于调用应用程序要求 PROPVARIANT 保存字符串值并且希望使用默认值（如果不是）的位置。例如，从属性存储中获取值的应用程序可以使用此值安全地提取字符串属性的字符串值。

如果源 PROPVARIANT 的类型VT_LPWSTR或VT_BSTR，则此帮助程序函数返回指向源 PROPVARIANT 中的值的指针。如果源 PROPVARIANT 具有类型VT_EMPTY或无法进行转换，则 PropVariantToStringWithDefault 将返回 pszDefault 提供的默认值。

请注意，此函数将返回指向参数中提供的数据的指针。因此，应用程序必须确保提供给参数的数据在结果不再使用之前保持有效。

示例

以下示例将作为较大程序的一部分包含，演示如何使用 PropVariantToStringWithDefault 访问 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.
     // The application developer decided to treat VT_EMPTY or invalid values as ""
     PCWSTR pszTitle = PropVariantToStringWithDefault(propvar, L"");
     // pszTitle is now valid.
     PropVariantClear(&propvar);
}
// ... later in the program ...
hr = ppropstore->GetValue(PKEY_Comment, &propvar);
if (SUCCEEDED(hr))
{
         // PKEY_Comment is expected to produce a VT_LPWSTR or VT_EMPTY value.
         // The application developer decided to treat VT_EMPTY as NULL
         PCWSTR pszComment = PropVariantToStringWithDefault(propvar, NULL);
         if (pszComment)
         {
                 // pszComment is valid
         }
         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