PropVariantToStringVectorAlloc 函式 (propvarutil.h)

發行項
08/25/2023

將資料從 PROPVARIANT 結構擷取到新配置的向量中新配置的字串。

語法

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

參數

[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
程式庫	Propsys.lib
Dll	Propsys.dll (6.0 版或更新版本)
可轉散發套件	Windows 桌面搜尋 (WDS) 3.0