IComponent2
COM公式ドキュメント
IComponent2 インターフェイスはスナップインによって実装され、MMC 2.0 で導入されました。IComponent インターフェイスに代わるものです。
メソッド 3
vtbl = vtable インデックス(0始まり)。HSP等からCOMメソッドをインデックス指定で呼ぶ際に使用します。0〜2 は IUnknown。
QueryDispatch メソッドは、指定した項目に対するスナップインの IDispatch インターフェイスを返します。
| cookie | INT_PTR | in | IDispatch インターフェイスの取得対象となるコンテキスト項目(1つまたは複数)を指定する値です。cookie 値はあらかじめスナップインによって提供され、MMC がこのメソッド呼び出しで使用します。 |
| type | DATA_OBJECT_TYPES | in | データオブジェクトを、次の定数値のいずれかとして指定する値です。これらの値は DATA_OBJECT_TYPES 列挙体のメンバーです。 CCT_SCOPE = 0x8000スコープペイン用のデータオブジェクトです。 CCT_RESULT = 0x8001結果ペイン用のデータオブジェクトです。 |
| ppDispatch | IDispatch** | out | ディスパッチインターフェイスのポインターです。スナップインは、cookie 値に対応する IDispatch インターフェイスを *ppDispatch に設定します。 |
戻り値
成功した場合、戻り値は S_OK です。それ以外の戻り値はエラーコードを示します。
GetResultViewType2 メソッドは、結果ビューの種類を取得します。このメソッドは IComponent::GetResultViewType メソッドに代わるものです。
| cookie | INT_PTR | in | スコープ項目に対してスナップインが提供する一意の識別子を指定する値です。MMC における cookie の詳細については、Cookies を参照してください。 |
| pResultViewType | RESULT_VIEW_TYPE_INFO* | inout | 結果ビュー用の RESULT_VIEW_TYPE_INFO 構造体へのポインターです。スナップインが IComponent2 を実装する場合、RESULT_VIEW_TYPE_INFO 構造体の pstrPersistableViewDescription メンバーには有効なビュー記述文字列が含まれている必要があります。そうでない場合、MMC はスナップインを初期化しません。pstrPersistableViewDescription メンバーは CoTaskMemAlloc によって割り当てる必要があります。pstrPersistableViewDescription は MMC によって解放されるため、スナップインが解放してはなりません。 |
戻り値
成功した場合、戻り値は S_OK です。それ以外の戻り値はエラーコードを示します。
解説(Remarks)
結果ビューの作成時に、MMC はスナップインの IComponent2::GetResultViewType2 メソッドを呼び出します。*pResultViewType の pstrPersistableViewDescription メンバーで名前が付けられた結果ビューをユーザーが再び表示すると、MMC はスナップインの IComponent2::RestoreResultView メソッドを呼び出します。このとき、スナップインは復元される結果ビューに対してスナップイン固有の詳細情報(存在する場合)を提供できます。ユーザーは、MMC の 戻る/進む ボタン、または保存済みコンソールファイルの読み込みによって結果ビューを再表示します。IComponent2::GetResultViewType2 メソッドおよび IComponent2::RestoreResultView メソッドの使用方法の詳細については、 Restoring Result Views を参照してください。
スナップインが OCX(ActiveX コントロール)ビューを実装している場合、スナップインは OCX を作成し、RESULT_VIEW_TYPE_INFO 構造体(具体的には構造体の pUnkControl メンバー)を通じて OCX の IUnknown ポインターを MMC に提供します。OCX の作成はスナップインが制御するため、スナップインは必要に応じてライセンスやセキュリティの問題に対処できます。 GetResultViewType2 の呼び出し中に、スナップインは OCX を初期化することもできます(スナップインは MMCN_INITOCX 通知を受け取りません)。
RestoreResultView メソッドは、結果ビューを復元します。このメソッドにより、スナップインは結果ビューのスナップイン固有の詳細情報を復元できます。詳細については、Restoring Result Views を参照してください。
| cookie | INT_PTR | in | 結果ビューが復元される対象の一意の識別子を指定する値です。 |
| pResultViewType | RESULT_VIEW_TYPE_INFO* | in | 結果ビュー用の RESULT_VIEW_TYPE_INFO 構造体へのポインターです。 |
戻り値
成功した場合、戻り値は S_OK です。スナップインは S_FALSE を返すことで、*pResultViewType の情報に基づいて MMC がビューを復元しないようにできます。それ以外の戻り値はエラーコードを示します。
解説(Remarks)
*pResultViewType の pstrPersistableViewDescription メンバーは、結果ビューに割り当てられた名前を指定します。pstrPersistableViewDescription メンバーで識別される結果ビューを復元するために、スナップインは *pResultViewType の残りのメンバーを設定します。結果ビューの名前は、スナップインによる IComponent2::GetResultViewType2 の実装時に最初に割り当てられます。MMC は IComponent2::RestoreResultView を呼び出すことで、結果ビューがユーザーによって再表示されたときにスナップインが内部ビュー設定を復元できるようにします。
ユーザーがビューをカスタマイズすると、一部の設定(ビューオプションやビューモードなど)は MMC が把握していますが、一部(イベントビューアースナップインの Oldest First など)はスナップインの内部設定です。MMC 2.0 より前では、内部ビュー設定を復元するために MMC がスナップインと通信する仕組みはありませんでした。しかし、MMC 2.0 の IComponent2::GetResultViewType2 メソッドおよび IComponent2::RestoreResultView メソッドは、内部ビュー設定を復元する仕組みを提供します。スナップインは、RESULT_VIEW_TYPE_INFO 構造体の pstrPersistableViewDescription メンバーに関連付けて内部ビュー設定を永続化します。MMC が結果ビューを復元するために IComponent2::RestoreResultView を呼び出すと、スナップインは永続化された設定を使用してビューの復元を完了します。
ユーザーは、MMC の 戻る/進む ボタンを押すか、保存済みコンソールファイルを読み込むことで結果ビューを再表示します。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)
HSP用 COM定義
#usecom / #comfunc によるHSPのCOM呼び出し定義。数字は vtbl インデックス(0始まり)。クラスIDが無い場合 #usecom の末尾は "{}"、ある場合は "{CLSID}"。
#define global IID_IComponent2 "{79A2D615-4A10-4ED4-8C65-8633F9335095}" #usecom global IComponent2 IID_IComponent2 "{}" #comfunc global IComponent2_QueryDispatch 10 sptr,int,sptr #comfunc global IComponent2_GetResultViewType2 11 sptr,var #comfunc global IComponent2_RestoreResultView 12 sptr,var ; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。 ; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。 ; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。 ; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。#define global IID_IComponent2 "{79A2D615-4A10-4ED4-8C65-8633F9335095}" #usecom global IComponent2 IID_IComponent2 "{}" #comfunc global IComponent2_QueryDispatch 10 sptr,int,sptr #comfunc global IComponent2_GetResultViewType2 11 sptr,sptr #comfunc global IComponent2_RestoreResultView 12 sptr,sptr ; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。 ; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。 ; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。 ; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。