IPerPropertyBrowsing

オブジェクトが提供するプロパティ ページ内の情報を取得します。

指定したプロパティを説明するテキスト文字列を取得します。

このメソッドは、標準の戻り値 E_INVALIDARG、E_OUTOFMEMORY、E_UNEXPECTED に加えて、次の値を返すことがあります。

Return code	Description
S_OK	表示名が正常に返されました。
E_NOTIMPL	オブジェクトは個々のプロパティの表示名を提供しません。この場合、呼び出し元はオブジェクトの型情報を参照してオブジェクトのテキスト名を確認することができます。
E_POINTER	pbstr のアドレスが無効です。たとえば NULL である可能性があります。

指定したプロパティに関連付けられたプロパティ ページの CLSID を取得します。

このメソッドは、標準の戻り値 E_INVALIDARG および E_UNEXPECTED に加えて、次の値を返すことがあります。

Return code	Description
S_OK	メソッドが正常に完了しました。
E_NOTIMPL	オブジェクトがプロパティ ページをまったくサポートしていないか、プロパティをページの CLSID にマッピングすることをサポートしていません。つまり、この特定のプロパティ参照機能はサポートされていません。
E_POINTER	pClsid のアドレスが無効です。たとえば NULL である可能性があります。

このメソッドから返される CLSID を OleCreatePropertyFrameIndirect に渡すことで、プロパティ シートに最初に表示するページを指定できます。

指定したプロパティが受け入れ可能な値に対する説明文字列の配列を取得します。

このメソッドは、標準の戻り値 E_INVALIDARG、E_OUTOFMEMORY、E_UNEXPECTED に加えて、次の値を返すことがあります。

Return code	Description
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->GetPredefinedStrings(dispID, &castr, &cadw); 
 
//...文字列とクッキーを使用する 
 
CoTaskMemFree((void *)cadw.pElems); 
 
for (i=0; i < castr.cElems; i++) 
    CoTaskMemFree((void *)castr.pElems[i]); 
 
CoTaskMemFree((void *)castr.pElems); 

実装者への注意

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

このメソッドは、CADWORD 構造体と CALPOLESTR 構造体の cElems メンバーと pElems メンバーを設定します。これらの構造体が指す配列を CoTaskMemAlloc で割り当て、その配列を設定します。CALPOLESTR の場合、このメソッドは各文字列も CoTaskMemAlloc で割り当て、各文字列ポインターを配列に格納します。

事前定義された文字列名に関連付けられた、指定したプロパティの値を取得します。

このメソッドは、標準の戻り値 E_INVALIDARG、E_OUTOFMEMORY、E_UNEXPECTED に加えて、次の値を返すことがあります。

Return code	Description
S_OK	メソッドが正常に完了しました。
E_NOTIMPL	このオブジェクトは事前定義された文字列や事前定義された値をサポートしていません。
E_POINTER	pVarOut のアドレスが無効です。たとえば NULL である可能性があります。

呼び出し元への注意

呼び出し元は、VARIANT に含まれる割り当てを解放する責任があります。VARIANT の vt メンバーが VT_VARIANT でない限り、呼び出し元は VariantClear の 1 回の呼び出しでメモリを解放できます。それ以外の場合、呼び出し元は外側の VARIANT を解放する前に、内包された VARIANT 値を再帰的に解放する必要があります。

実装者への注意

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

このメソッドは、VARIANT 内で必要なメモリを割り当てます。

#define global IID_IPerPropertyBrowsing "{376BD3AA-3845-101B-84ED-08002B2EC713}"
#usecom global IPerPropertyBrowsing IID_IPerPropertyBrowsing "{}"
#comfunc global IPerPropertyBrowsing_GetDisplayString      3 int,var
#comfunc global IPerPropertyBrowsing_MapPropertyToPage     4 int,var
#comfunc global IPerPropertyBrowsing_GetPredefinedStrings  5 int,var,var
#comfunc global IPerPropertyBrowsing_GetPredefinedValue    6 int,int,var
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。