Win32 API 日本語リファレンス
ホーム › UI.Shell › IAssocHandler

IAssocHandler

COM
📘 Microsoft Learn (日本語) · English
IIDf04061ac-1659-4a3f-a954-775aa57fc083継承元IUnknown自前メソッド開始 vtbl3

公式ドキュメント

ファイルの関連付けダイアログボックスまたはメニューに関する操作のためのメソッドを公開します。

メソッド 7

vtbl = vtable インデックス(0始まり)。HSP等からCOMメソッドをインデックス指定で呼ぶ際に使用します。0〜2 は IUnknown。

vtbl 3 HRESULT GetName(LPWSTR* ppsz)

ファイルの種類に関連付けられた実行可能ファイルのフルパスとファイル名を取得します。

ppszLPWSTR*outこのメソッドが返るとき、ファイル名を含むファイルのフルパスを格納した、null 終端の Unicode 文字列へのポインターのアドレスを格納します。

戻り値

型: HRESULT

このメソッドが成功した場合、S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

vtbl 4 HRESULT GetUIName(LPWSTR* ppsz)

アプリケーションの表示名を取得します。

ppszLPWSTR*outこのメソッドが返るとき、アプリケーションの表示名を格納した、null 終端の Unicode 文字列へのポインターのアドレスを格納します。

戻り値

型: HRESULT

このメソッドが成功した場合、S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

vtbl 5 HRESULT GetIconLocation(LPWSTR* ppszPath, INT* pIndex)

アプリケーションに関連付けられたアイコンの場所を取得します。

ppszPathLPWSTR*outこのメソッドが返るとき、アプリケーションのアイコンへのパスを格納した、null 終端の Unicode 文字列へのポインターのアドレスを格納します。
pIndexINT*outこのメソッドが返るとき、ppszPath で指定されたリソース内のアイコンのインデックスへのポインターを格納します。

戻り値

型: HRESULT

このメソッドが成功した場合、S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

解説(Remarks)

アイコンが見つからない場合、この関数は実行可能ファイルへのパスと、0 のアイコンインデックスを返します。

パフォーマンス上の理由から、アプリケーションは返されたパスから直接アイコンを読み込むのではなく、Shell イメージキャッシュを使用してアイコンを取得することがあります。パスとアイコンインデックスは、Shell_GetCachedImageIndex に直接渡すことができます。これには、アプリケーションで利用可能なアイコンがない場合に、Shell キャッシュが既定のアイコンを提供できるという利点があります。

vtbl 6 HRESULT IsRecommended()

アプリケーションが、照会されたファイルの種類に対する推奨ハンドラーとして登録されているかどうかを示します。

戻り値

型: HRESULT

プログラムが推奨される場合は S_OK を返します。それ以外の場合は S_FALSE を返します。

解説(Remarks)

特定のファイルの種類のハンドラーとして自身を登録するアプリケーションは、自身が推奨ハンドラーであるかどうかを指定できます。これは、起動時のアプリケーションの実際の動作には影響しません。これは単にユーザーへのヒントとして、また必要に応じて UI がプログラム的に利用できる値として提供されます。たとえば、Shell の プログラムから開く ダイアログでは、エントリを 推奨されるプログラム と その他のプログラム に分けて表示します。

プログラムの推奨は時間の経過とともに変化する可能性があることに注意してください。一例として、ユーザーが特定のファイルの種類を開くために プログラムから開く ダイアログの その他のプログラム からアプリケーションを選択した場合が挙げられます。これにより、Shell がそのアプリケーションをそのファイルの種類に対する推奨ステータスに「昇格」させることがあります。推奨ステータスは時間の経過とともに変化する可能性があるため、アプリケーションはこの値をキャッシュせず、必要になるたびに照会する必要があります。

SHAssocEnumHandlers が ASSOC_FILTER_RECOMMENDED フラグ付きで呼び出された場合は、推奨ハンドラーのみが返されます。ASSOC_FILTER_NONE フラグが使用された場合は、各 IAssocHandler オブジェクトに対して IAssocHandler::IsRecommended を呼び出して、それが推奨されるかどうかを判定する必要があります。

vtbl 7 HRESULT MakeDefault(LPWSTR pszDescription)

アプリケーションを、このファイルの種類に対する既定のアプリケーションとして設定します。

pszDescriptionLPWSTRinアプリケーションの表示名を格納した、null 終端の Unicode 文字列へのポインター。

戻り値

型: HRESULT

このメソッドが成功した場合、S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

vtbl 8 HRESULT Invoke(IDataObject* pdo)

関連付けられたハンドラーを直接呼び出します。

pdoIDataObject*inハンドラーを呼び出す対象として選択された項目を表す IDataObject へのポインター。複数の項目が選択された状態で IAssocHandler::Invoke を呼び出さないでください。複数の項目がある場合は、代わりに IAssocHandler::CreateInvoker を呼び出してください。詳細については「解説」を参照してください。

戻り値

型: HRESULT

このメソッドが成功した場合、S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

解説(Remarks)

IAssocHandler オブジェクトは、通常 プログラムから開く メニューを設定するために使用されます。これらのメニュー項目のいずれかが選択されると、選択されたアプリケーションを起動するためにこのメソッドが呼び出されます。

Invoke と CreateInvoker

これらのメソッドで使用される IDataObject は、単一のファイルまたは複数のファイルの選択のいずれかを表すことができます。すべてのアプリケーションが複数ファイルのオプションをサポートしているわけではありません。このシナリオをサポートするアプリケーションでも、同時に開けるファイル数や、許容されるファイルの種類の組み合わせなど、他の制限を課す場合があります。

したがって、アプリケーションはハンドラーを呼び出す前に、ハンドラーがその選択をサポートしているかどうかを判定しなければならないことがよくあります。たとえば、対象の選択がそのハンドラーによってサポートされていることを確認した場合にのみ、メニュー項目を有効にすることがあります。

一般に、アプリケーションが単一の項目に対する呼び出しをサポートすると想定するのは安全であり、そのような場合、アプリケーションは通常その想定に基づいて IAssocHandler::Invoke を呼び出します。

ただし、複数選択のシナリオでは、アプリケーションは IAssocHandler::CreateInvoker を呼び出す必要があります。このメソッドは IAssocHandlerInvoker オブジェクトを取得します。これにより、呼び出し側のアプリケーションはまず選択がサポートされているかどうかを確認し(SupportsSelection)、その後ハンドラーを呼び出す(Invoke)ことができます。

IAssocHandler::Invoke は複数ファイルの選択に対して呼び出すこともできますが、処理負荷が大きく成功する保証もないため、推奨されません。

vtbl 9 HRESULT CreateInvoker(IDataObject* pdo, IAssocHandlerInvoker** ppInvoker)

現在の選択に対して、関連付けられたハンドラーの呼び出しを可能にするオブジェクトを取得します。この呼び出しオブジェクト(invoker)には、現在の選択がサポートされているかどうかを検証する機能が含まれます。

pdoIDataObject*inハンドラーを呼び出す対象として選択された 1 つまたは複数の項目を表す IDataObject へのポインター。項目が 1 つだけの場合は、IAssocHandler::Invoke の方が適切な選択肢となる場合があります。詳細については「解説」を参照してください。
ppInvokerIAssocHandlerInvoker**outこのメソッドが返るとき、IAssocHandlerInvoker オブジェクトへのポインターのアドレスを格納します。このオブジェクトは、選択された項目が関連付けられたハンドラーによってサポートされていることを確認したうえで、メニュー項目を呼び出すために使用されます。

戻り値

型: HRESULT

このメソッドが成功した場合、S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

解説(Remarks)

IAssocHandler オブジェクトは、通常 プログラムから開く メニューを設定するために使用されます。これらのメニュー項目のいずれかが選択されると、選択されたアプリケーションを起動するためにこのメソッドが呼び出されます。

Invoke と CreateInvoker

これらのメソッドで使用される IDataObject は、単一のファイルを表すことも、複数のファイルの選択を表すこともできます。すべてのアプリケーションが複数ファイルのオプションをサポートしているわけではありません。このシナリオをサポートするアプリケーションでも、同時に開けるファイル数や、許容されるファイルの種類の組み合わせなど、他の制限を課す場合があります。

したがって、アプリケーションはハンドラーを呼び出す前に、ハンドラーがその選択をサポートしているかどうかを判定しなければならないことがよくあります。たとえば、対象の選択がそのハンドラーによってサポートされていることが分かっている場合にのみ、メニュー項目を有効にすることがあります。

一般に、アプリケーションが単一の項目に対する呼び出しをサポートすると想定するのは安全であり、そのような場合、アプリケーションは通常 IAssocHandler::Invoke を呼び出します。

複数選択のシナリオでは、アプリケーションは IAssocHandler::CreateInvoker を呼び出す必要があります。このメソッドは IAssocHandlerInvoker オブジェクトを取得します。これにより、呼び出し側のアプリケーションはまず選択がサポートされているかどうかを確認し(SupportsSelection)、その後ハンドラーを呼び出す(Invoke)ことができます。

IAssocHandler::Invoke は複数ファイルの選択に対して呼び出すこともできますが、処理負荷が大きく成功する保証もないため、推奨されません。

出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)

HSP用 COM定義

#usecom / #comfunc によるHSPのCOM呼び出し定義。数字は vtbl インデックス(0始まり)。クラスIDが無い場合 #usecom の末尾は "{}"、ある場合は "{CLSID}"。

出力引数: 
#define global IID_IAssocHandler "{F04061AC-1659-4A3F-A954-775AA57FC083}"
#usecom global IAssocHandler IID_IAssocHandler "{}"
#comfunc global IAssocHandler_GetName          3 var
#comfunc global IAssocHandler_GetUIName        4 var
#comfunc global IAssocHandler_GetIconLocation  5 var,var
#comfunc global IAssocHandler_IsRecommended    6
#comfunc global IAssocHandler_MakeDefault      7 wstr
#comfunc global IAssocHandler_Invoke           8 sptr
#comfunc global IAssocHandler_CreateInvoker    9 sptr,sptr
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。