PropVariantToStringVectorAlloc 函数 (propvarutil.h)

项目
08/25/2023

将 PROPVARIANT 结构中的数据提取到新分配的向量中新分配的字符串中。

语法

PSSTDAPI PropVariantToStringVectorAlloc(
  [in]  REFPROPVARIANT propvar,
  [out] PWSTR          **pprgsz,
  [out] ULONG          *pcElem
);

parameters

[in] propvar

类型： REFPROPVARIANT

对源 PROPVARIANT 结构的引用。

[out] pprgsz

类型： PWSTR**

此函数返回时，包含指向从源 PROPVARIANT 结构中提取的字符串向量的指针。

[out] pcElem

类型： ULONG*

当此函数返回时，包含从源 PROPVARIANT 结构中提取的字符串元素计数。

返回值

类型： HRESULT

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

返回代码	说明
S_OK	如果成功，则返回 S_OK ，否则返回错误值。
E_INVALIDARG	PROPVARIANT 不是适当的类型。

注解

此帮助程序函数用于调用应用程序要求 PROPVARIANT 保存字符串值向量的位置。

此帮助程序函数适用于以下PROPVARIANT 类型：

VT_VECTOR |VT_LPWSTR
VT_VECTOR |VT_BSTR
VT_ARRAY | VT_BSTR

如果源 PROPVARIANT 具有受支持的类型，则此函数会将字符串值的向量提取到新分配的字符串的新分配向量中。调用应用程序负责在不再需要时使用 CoTaskMemFree 释放输出向量中包含的字符串和输出向量本身。

如果源 PROPVARIANT 中的 BSTR 为 NULL，则此函数会将包含“”的新分配的字符串放入输出向量中。

示例

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

// IPropertyStore *ppropstore;
// Assume variable ppropstore is initialized and valid
PROPVARIANT propvar = {0};
HRESULT hr = ppropstore->GetValue(PKEY_Keywords, &propvar);
if (SUCCEEDED(hr))
{
         // PKEY_Keywords is expected to produce a VT_VECTOR | VT_LPWSTR, or VT_EMPTY
         // PropVariantToStringVectorAlloc will return an error for VT_EMPTY
         LPWSTR *prgKeywords;
         ULONG cElem;
         hr = PropVariantToStringVectorAlloc (propvar, &prgKeywords, &cElem);
         if (SUCCEEDED(hr))
         {
                 // prgKeywords contains cElem strings
                 for (ULONG i = 0; i < cElem; i++)
                 {
                          CoTaskMemFree(prgKeywords[i]);
                 }
                 CoTaskMemFree(prgKeywords);
         }
         else
         {
                 // propvar either is VT_EMPTY, or contains something other than a vector of  strings
         }
         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