PropVariantToStringVector 函式 (propvarutil.h)

發行項
03/01/2024

從 PROPVARIANT 結構擷取字串的向量。

語法

PSSTDAPI PropVariantToStringVector(
  [in]  REFPROPVARIANT propvar,
  [out] PWSTR          *prgsz,
  [in]  ULONG          crgsz,
  [out] ULONG          *pcElem
);

參數

[in] propvar

類型： REFPROPVARIANT

來源 PROPVARIANT 結構的參考。

[out] prgsz

類型： PWSTR*

字串指標向量的指標。當此函式傳回時，緩衝區已使用 PCElem 元素初始化，指向新配置的字串，其中包含從來源 PROPVARIANT擷取的數據。

[in] crgsz

類型： ULONG

prgsz 所指向的緩衝區大小，以元素為單位。

[out] pcElem

類型： ULONG*

當此函式傳回時，包含從來源 PROPVARIANT 結構擷取的字串計數。

傳回值

類型： HRESULT

此函式可以傳回下列其中一個值。

傳回碼	描述
S_OK	如果成功，則傳回 S_OK ，否則傳回錯誤值。
TYPE_E_BUFFERTOOSMALL	來源PROPVARIANT 包含超過 crgsz 值。 prgsz 指向的緩衝區。
E_INVALIDARG	PROPVARIANT 不是適當的類型。

備註

此協助程式函式用於呼叫應用程式預期 PROPVARIANT 以固定數目的專案保存字串值的向量的位置。

此函式適用於下列 PROPVARIANT 型態：

VT_VECTOR |VT_LPWSTR
VT_VECTOR |VT_BSTR
VT_ARRAY |VT_BSTR

如果來源 PROPVARIANT 具有支援的類型，則此協助程式函式最多會擷取 crgsz 字串值，並將配置的每個複本放在 prgsz 所指向的緩衝區中。如果 PROPVARIANT 包含的項目超過將放入 prgsz 緩衝區的專案，此函式會傳回錯誤，並將 pcElem 設定為 0。

由於輸出緩衝區所指向的每個字串都已新配置，因此呼叫的應用程式會負責在不再需要時，使用 CoTaskMemFree 釋放輸出緩衝區中的每個字串。

如果來源 PROPVARIANT中的 BSTR 是 NULL，則會轉換成輸出中包含「之新配置的字串」。

範例

// PROPVARIANT propvar;
// Assume the variable propvar is initialized and valid
LPWSTR rgszStrings; // The application is expecting propvar to hold 4 strings in a vector
ULONG cElems;
HRESULT hr = PropVariantToStringVector(propvar, rgszStrings, ARRAYSIZE(rgszStrings), &cElems);
if (SUCCEEDED(hr))
{
     if (cElems == ARRAYSIZE(rgszStrings))
     {
         // The application got 4 string which are now stored in rgszStrings
     }
     else
     {
         // The application got cElems which are stored in the first cElems elements of rgLongs
     }
 
    // Free the cElems strings that PropVariantToStringVector allocated
    for (ULONG i = 0; i < cElems; i++)
    {
        CoTaskMemFree(rgszStrings[i]);
    }
}

規格需求

需求	值
最低支援的用戶端	Windows XP 搭配 SP2、Windows Vista [僅限傳統型應用程式]
最低支援的伺服器	Windows Server 2003 SP1 [僅限傳統型應用程式]
目標平台	Windows
標頭	propvarutil.h
程式庫	Propsys.lib
Dll	Propsys.dll (6.0 版或更新版本)
可轉散發套件	Windows 桌面搜尋 (WDS) 3.0