IPropertyBag
COM公式ドキュメント
オブジェクトが自身のプロパティを永続的に保存できるプロパティバッグを、そのオブジェクトに提供します。
メソッド 2
vtbl = vtable インデックス(0始まり)。HSP等からCOMメソッドをインデックス指定で呼ぶ際に使用します。0〜2 は IUnknown。
指定した名前のプロパティを、呼び出し側が初期化した VARIANT に読み込みます。
| pszPropName | LPWSTR | in | 読み込むプロパティの名前へのアドレス。NULL を指定することはできません。 |
| pVar | VARIANT* | inout | 出力時にプロパティ値を受け取る、呼び出し側が初期化した VARIANT のアドレス。この関数は、戻る前に VARIANT の type フィールドと value フィールドを設定します。呼び出し側が入力時に pVar->vt フィールドを初期化していた場合、プロパティバッグは対応する値をこの型に変換しようとします。呼び出し側が pVar->vt を VT_EMPTY に設定した場合、プロパティバッグは都合のよい任意の型を使用できます。 |
| pErrorLog | IErrorLog* | in | 読み込み中に発生したエラーをプロパティバッグが格納する、呼び出し側のエラーログのアドレス。NULL を指定でき、その場合、呼び出し側はエラーを受け取りません。 |
戻り値
HRESULT。
解説(Remarks)
Read メソッドは、pszPropName で指定された名前のプロパティを、pVar にある呼び出し側が初期化した VARIANT に読み込むようプロパティバッグに指示します。エラーは pErrorLog が指すエラーログに記録されます。pVar->vt が別のオブジェクトポインター (VT_UNKNOWN) を指定している場合、プロパティバッグは pszPropName で記述されたオブジェクトの作成と初期化を行う責任を負います。
このインターフェイスを実装するオブジェクトはインターフェイスの全機能をサポートしなければならないため、E_NOTIMPL は有効な戻りコードではありません。
指定した名前のプロパティを、呼び出し側が初期化した VARIANT に格納された値で保存します。
| pszPropName | LPWSTR | in | 書き込むプロパティの名前を含む文字列のアドレス。NULL を指定することはできません。 |
| pVar | VARIANT* | in | 保存するプロパティ値を保持する、呼び出し側が初期化した VARIANT のアドレス。この VARIANT は呼び出し側が所有し、そのすべての割り当てについて責任を負います。つまり、プロパティバッグは VARIANT 内のデータを解放しようとはしません。 |
解説(Remarks)
Write メソッドは、pVar にある呼び出し側が初期化した VARIANT の型と値を使用して、pszPropName で指定された名前のプロパティを保存するようプロパティバッグに指示します。場合によっては、呼び出し側がプロパティバッグに別のオブジェクトの保存を指示していることがあります。たとえば pVar->vt が VT_UNKNOWN の場合です。そのような場合、プロパティバッグはこのオブジェクトポインターに対して IPersistStream や IPersistPropertyBag などの永続化インターフェイスをクエリし、そのオブジェクトにも自身のデータを保存させます。通常、この結果としてプロパティバッグはこのオブジェクトのバイト配列を保持することになり、これは 16 進数文字列や MIME などのエンコードされたテキストとして保存できます。後でプロパティバッグを使用してコントロールを再初期化する際には、プロパティバッグを所有するクライアントは、呼び出し側から要求されたときにオブジェクトを再作成し、以前に保存されたビットでそのオブジェクトを初期化しなければなりません。
これにより、ピクチャなどの Binary Large Object (BLOB) プロパティに対する効率的な永続化操作が可能になります。この場合、プロパティバッグの所有者はピクチャオブジェクト (保存されるコントロール内のプロパティとして管理される) に対して特定の場所への保存を指示します。これにより、他のプロパティベースの永続化メカニズムで発生する可能性のある余分なコピー操作を回避できます。
このインターフェイスを実装するオブジェクトはインターフェイスの全機能をサポートしなければならないため、E_NOTIMPL は有効な戻りコードではありません。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)
HSP用 COM定義
#usecom / #comfunc によるHSPのCOM呼び出し定義。数字は vtbl インデックス(0始まり)。クラスIDが無い場合 #usecom の末尾は "{}"、ある場合は "{CLSID}"。
#define global IID_IPropertyBag "{55272A00-42CB-11CE-8135-00AA004BB851}" #usecom global IPropertyBag IID_IPropertyBag "{}" #comfunc global IPropertyBag_Read 3 wstr,var,sptr #comfunc global IPropertyBag_Write 4 wstr,var ; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。 ; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。 ; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。 ; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。#define global IID_IPropertyBag "{55272A00-42CB-11CE-8135-00AA004BB851}" #usecom global IPropertyBag IID_IPropertyBag "{}" #comfunc global IPropertyBag_Read 3 wstr,sptr,sptr #comfunc global IPropertyBag_Write 4 wstr,sptr ; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。 ; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。 ; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。 ; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。