IPropertySheetProvider
COM公式ドキュメント
IPropertySheetProvider インターフェイスは、Windows のプロパティシートを COM オブジェクトとして実装します。
メソッド 5
vtbl = vtable インデックス(0始まり)。HSP等からCOMメソッドをインデックス指定で呼ぶ際に使用します。0〜2 は IUnknown。
プロパティシートフレームを作成します。
| title | LPWSTR | in | プロパティページのタイトルを含む null 終端文字列へのポインター。このパラメーターに NULL を指定することはできません。 |
| type | BYTE | in | TRUE はプロパティシートを作成し、FALSE はウィザードを作成します。 |
| cookie | INT_PTR | in | 現在選択されている項目の Cookie 値。拡張スナップインによって CreatePropertySheet が呼び出される場合、これは NULL になることがあります。 |
| pIDataObjectm | IDataObject* | in | cookie のデータオブジェクト上の IDataObject インターフェイスへのポインター。このパラメーターの値が NULL の場合、MMC は拡張スナップインが実装する IExtendPropertySheet2 メソッドを一切呼び出しません。 |
| dwOptions | DWORD | in | メソッド呼び出しで設定できるフラグを指定する値。このパラメーターには、次の値を組み合わせて指定できます。 MMC_PSO_NOAPPLYNOW[今すぐ適用] ボタンを削除します。 MMC_PSO_HASHELPヘルプ ボタンを追加します。 MMC_PSO_NO_PROPTITLEウィザードでは無視されます。プロパティシートの場合、このオプションを指定すると、プロパティシートのタイトルバーの先頭に "Properties for" という語句が挿入されません。 MMC_PSO_NEWWIZARDTYPEWizard 97 スタイルを使用します。 たとえば、ヘルプ ボタンを持ち、[今すぐ適用] ボタンを持たないプロパティシートを作成するには、dwOptions パラメーターを |
戻り値
このメソッドは、次のいずれかの値を返すことがあります。
解説(Remarks)
このメソッドは、プロパティシートの作成に必要なすべての情報を収集するオブジェクトを作成します。 CreatePropertySheet の呼び出しは成功したものの、その後にエラーが発生した場合は、 IPropertySheetProvider::Show( –1, 0) を呼び出してオブジェクトを解放する必要があります。この場合、戻り値のコードは無視できます。
スナップインが IPropertySheetProvider::CreatePropertySheet の呼び出しでプロパティシートを作成し、続いて任意で IPropertySheetProvider::AddPrimaryPages と IPropertySheetProvider::AddExtensionPages を呼び出した後、プロパティシートを表示しないことにした場合は、IPropertySheetProvider::Show( –1, 0) を呼び出してプロパティシートを削除し、そのリソースを解放する必要があります。この場合、スナップインは作成したプロパティページのハンドルを削除する必要があります。MMC はプロパティページのハンドルを使用しないため、これはスナップインが IPropertySheetProvider::Show( –1, 0) を呼び出す前でも後でも実行できます。
MMC 1.1 を対象とするスナップインの場合、IPropertySheetProvider::CreatePropertySheet の呼び出しで MMC に渡す IDataObject インターフェイスに対して、追加の参照を保持する必要があります。この参照は、IPropertySheetProvider::CreatePropertySheet の呼び出し前から、IPropertySheetProvider::Show( –1, 0) の呼び出しによってプロパティシートが閉じられる可能性がある後まで保持する必要があります。
特定のプロパティシートが存在するかどうかを判定します。
| hItem | INT_PTR | in | スコープペインで選択されている項目へのハンドル。 |
| lpComponent | IComponent* | in | 選択されたオブジェクト上の
IComponent インターフェイスへのポインター。選択されたオブジェクトが(スコープペインまたは結果ペイン上の)フォルダーの場合は NULL、結果ペインのリーフ項目の場合はスナップインの IComponent になります。 |
| lpDataObject | IDataObject* | in | データオブジェクト上の IDataObject インターフェイスへのポインター。 |
戻り値
このメソッドは、次のいずれかの値を返すことがあります。
解説(Remarks)
スコープペイン内の項目はコンソールが所有しているため、 IComponentData インターフェイスとやり取りする必要はありません。スナップインは、データオブジェクトを既存のプロパティシートの他のデータオブジェクトと比較するために、 IComponent::CompareObjects または IComponentData::CompareObjects を実装する必要があります。
IPropertySheetProvider::AddPrimaryPages メソッドは、プライマリスナップインからページを収集します。
| lpUnknown | IUnknown* | inoptional | IExtendPropertySheet インターフェイスを照会する対象となるスナップインインターフェイスへのポインター。bCreateHandle が TRUE に設定されている場合、これは IExtendPropertySheet を照会する対象となるスナップインの IComponent または IComponentData インターフェイスへのポインターでもある必要があります。この値は NULL になることがある点に注意してください。詳細については「解説」を参照してください。 |
| bCreateHandle | BOOL | in | MMCPropertyChangeNotify の呼び出し時に、MMCN_PROPERTY_CHANGE 通知を適切な IComponent または IComponentData インターフェイスへルーティングするために使用される、コンソール提供の通知ハンドルを作成するかどうかを指定する値。通知ハンドルは、スナップインが実装する IExtendPropertySheet2::CreatePropertyPages メソッドの呼び出し時にスナップインへ返されます。 bCreateHandle が TRUE に設定されている場合、lpUnknown パラメーターは、MMCN_PROPERTY_CHANGE 通知を受け取る IComponent または IComponentData へのポインターである必要があります。 |
| hNotifyWindow | HWND | in | 将来の使用のために予約されています。この値は NULL にする必要があります。 |
| bScopePane | BOOL | in | 項目がスコープペインにある場合は TRUE に設定します。結果ペインにある場合は FALSE に設定します。 |
戻り値
このメソッドは、次のいずれかの値を返すことがあります。
解説(Remarks)
このメソッドの呼び出し中に、スナップインがページを一切追加しないことがあります。その場合は、拡張ページを追加すべきではありません。
IPropertySheetProvider::AddExtensionPages メソッドは、拡張スナップインからページを収集します。
戻り値
このメソッドは、次のいずれかの値を返すことがあります。
解説(Remarks)
IPropertySheetProvider インターフェイスを直接使用するスナップインは、拡張機能がページを追加できるようにする前に、少なくとも 1 つのページを追加する必要があります。また、拡張機能が独自のプロパティページを追加できるようにするために、IPropertySheetProvider::AddExtensionPages メソッドを呼び出す必要があります。
IPropertySheetProvider::CreatePropertySheet で設定された種類がプロパティシートである場合、IPropertySheetProvider::Show は、非表示ウィンドウを親とするプロパティシートフレームを表示します。
| window | INT_PTR | in | 親ウィンドウへのハンドルを指定する値。 |
| page | INT | in | プロパティシート上のどのページを表示するかを指定する値。0 から始まるインデックスです。 |
戻り値
このメソッドは、次のいずれかの値を返すことがあります。
解説(Remarks)
IPropertySheetProvider::Show( –1, 0) は E_FAIL を返します。この場合、この戻り値のコードは無視できます。
スナップインが IPropertySheetProvider::CreatePropertySheet の呼び出しでプロパティシートを作成し、任意で IPropertySheetProvider::AddPrimaryPages と IPropertySheetProvider::AddExtensionPages を呼び出した後、プロパティシートを表示しないことにした場合は、IPropertySheetProvider::Show( –1, 0) を呼び出してプロパティシートを削除し、そのリソースを解放する必要があります。この場合、スナップインは作成したプロパティページのハンドルを削除する必要があります。MMC はプロパティページのハンドルを使用しないため、これはスナップインが IPropertySheetProvider::Show( –1, 0) を呼び出す前でも後でも実行できます。
IPropertySheetProvider::Show( –1, 0) は、現在のプロパティシート、つまり作成済みだがまだ表示されていないものだけを削除します。プロパティシートが表示された後は、スナップインからプログラムでそれを閉じることはできません。表示されたプロパティシートは、ユーザーだけが閉じることができます。この場合、MMC はスナップインが提供するすべての関連プロパティページ(PROPSHEETPAGE 構造体)を自動的に削除します。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)
HSP用 COM定義
#usecom / #comfunc によるHSPのCOM呼び出し定義。数字は vtbl インデックス(0始まり)。クラスIDが無い場合 #usecom の末尾は "{}"、ある場合は "{CLSID}"。
#define global IID_IPropertySheetProvider "{85DE64DE-EF21-11CF-A285-00C04FD8DBE6}"
#usecom global IPropertySheetProvider IID_IPropertySheetProvider "{}"
#comfunc global IPropertySheetProvider_CreatePropertySheet 3 wstr,int,sptr,sptr,int
#comfunc global IPropertySheetProvider_FindPropertySheet 4 sptr,sptr,sptr
#comfunc global IPropertySheetProvider_AddPrimaryPages 5 sptr,int,sptr,int
#comfunc global IPropertySheetProvider_AddExtensionPages 6
#comfunc global IPropertySheetProvider_Show 7 sptr,int
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。