PropVariantToStringVector 関数 (propvarutil.h)

[アーティクル]
03/05/2024

PROPVARIANT 構造体から文字列のベクターを抽出します。

構文

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

パラメーター

[in] propvar

型: REFPROPVARIANT

ソース PROPVARIANT 構造体への参照。

[out] prgsz

種類: PWSTR*

文字列ポインターのベクターへのポインター。この関数が戻ると、バッファーは、ソース PROPVARIANT から抽出されたデータを含む新しく割り当てられた文字列を指す pcElem 要素で初期化されています。

[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
Library	Propsys.lib
[DLL]	Propsys.dll (バージョン 6.0 以降)
再頒布可能パッケージ	Windows デスクトップ検索 (WDS) 3.0