IPerPropertyBrowsing::GetPredefinedStrings メソッド (ocidl.h)

[アーティクル]
02/29/2024

指定したプロパティで受け入れられる許容値の配列記述文字列を取得します。

構文

HRESULT GetPredefinedStrings(
  [in]  DISPID     dispID,
  [out] CALPOLESTR *pCaStringsOut,
  [out] CADWORD    *pCaCookiesOut
);

パラメーター

[in] dispID

プロパティのディスパッチ識別子。

[out] pCaStringsOut

メソッドによって割り当てられた文字列ポインターの配列の要素数とアドレスを含む、呼び出し元によって割り当てられたカウントされた配列構造体へのポインター。また、このメソッドは、定義済みの名前を含む文字列値にメモリを割り当て、配列に文字列ポインターを格納します。メソッドが失敗した場合、メモリは割り当てられず、構造体の内容は未定義になります。

[out] pCaCookiesOut

DWORD 値のメソッドによって割り当てられた配列の要素数とアドレスを含む、呼び出し元によって割り当てられたカウントされた配列構造体へのポインター。配列内の値を IPerPropertyBrowsing::GetPredefinedValue に渡して、 pCaStringsOut 内の同じ配列位置にある名前に関連付けられている値を取得できます。メソッドが失敗した場合、メモリは割り当てられず、構造体の内容は未定義になります。

戻り値

このメソッドは、E_INVALIDARG、E_OUTOFMEMORY、E_UNEXPECTEDの標準戻り値と、次の値を返すことができます。

リターンコード	説明
S_OK	メソッドは正常に完了しました。
E_NOTIMPL	このメソッドは実装されておらず、定義済みの名前はサポートされていません。
E_POINTER	pCaStringsOut または pCaCookiesOut のアドレスが無効です。たとえば、どちらのパラメーターも NULL にすることができます。

注釈

pCaStringsOut が指す配列で返される各文字列は、pCaCookiesOut が指すカウントされた配列に一致するトークンを持ちます。ここで、トークンを IPerPropertyBrowsing::GetPredefinedValue に渡して、文字列に対応する実際の値 (VARIANT) を取得できます。

呼び出し元は、定義済みの文字列を使用して、ドロップダウンリストボックスなどのユーザーインターフェイス要素を設定するための文字列の一覧を取得できます。エンドユーザーがプロパティに割り当てる値としてこれらの文字列のいずれかを選択すると、呼び出し元は IPerPropertyBrowsing::GetPredefinedValue を使用して対応する値を取得できます。

呼び出し元へのメモ

このメソッドに渡される CALPOLESTR 構造体と CADWORD 構造体の両方が呼び出し元によって割り当てられます。呼び出し元は、 CALPOLESTR 配列と CALPOLESTR 構造体から指す各文字列を解放する役割を担います。

すべてのメモリは CoTaskMemAlloc で割り当てられます。呼び出し元は、 CoTaskMemFree を使用して文字列と配列を解放する必要があります。

このメソッドから戻ると、呼び出し元はこのすべてのメモリを担当し、不要になったら解放する必要があります。これを実現するコードは次のようになります。

CALPOLESTR     castr; 
CWDWORD        cadw; 
ULONG          i; 
 
pIPerPropertyBrowsing-&gt;GetPredefinedStrings(dispID, &amp;castr, &amp;cadw); 
 
//...Use the strings and the cookies 
 
CoTaskMemFree((void *)cadw.pElems); 
 
for (i=0; i &lt; castr.cElems; i++) 
    CoTaskMemFree((void *)castr.pElems[i]); 
 
CoTaskMemFree((void *)castr.pElems);

実装者へのメモ

定義済みの名前と値のサポートは必要ありません。オブジェクトでこれらの名前がサポートされていない場合は、このメソッドからE_NOTIMPLを返します。このメソッドが実装されていない場合、 IPerPropertyBrowsing::GetPredefinedValue も実装できません。

このメソッドは、CADWORD および CALPOLESTR 構造体の cElems および pElems メンバーを入力します。これらの構造体が指す配列を CoTaskMemAlloc で割り当て、それらの配列を埋めます。 CALPOLESTR の場合、このメソッドは CoTaskMemAlloc を使用して各文字列を割り当て、各文字列ポインターを配列に格納します。

要件

要件	値
サポートされている最小のクライアント	Windows 2000 Professional [デスクトップアプリのみ]
サポートされている最小のサーバー	Windows 2000 Server [デスクトップアプリのみ]
対象プラットフォーム	Windows
ヘッダー	ocidl.h

こちらもご覧ください

CADWORD

CALPOLESTR

IPerPropertyBrowsing