IQueryAssociations
COM公式ドキュメント
ファイルの種類やプロトコルの定義と、それをアプリケーションに関連付けることに関連してレジストリに格納された情報を取得する処理を簡素化するメソッドを公開します。
解説(Remarks)
実装するタイミング
このインターフェイスは、ファイルおよびプロトコルの関連付けの処理を簡素化するために、シェルまたは名前空間拡張によって公開されます。このインターフェイスを実装しないでください。使用するタイミング
ファイルまたはプロトコルの関連付けに関連する情報をレジストリから取得する必要がある場合に、このインターフェイスを使用します。たとえば、このインターフェイスを使用して、ファイル名拡張子に関連付けられた情報(その動詞のいずれかのコマンド文字列など)を取得できます。完全なレジストリパスや HKEY 値は必要ありません。代わりに、ファイル名拡張子や実行可能ファイル名などの条件に基づいて情報を取得できます。ファイルの関連付けについては、File Types を参照してください。
このインターフェイスを使用して、アプリケーションの名前を取得することもできます。IQueryAssociations::GetString メソッドを使用します。str パラメーターに ASSOCSTR_FRIENDLYAPPNAME を設定してください。
このインターフェイスを使用するには、最初にそのインターフェイスへのポインターを取得する必要があります。通常、シェルオブジェクトの IShellFolder::GetUIObjectOf メソッドを呼び出して QueryInterface ポインターを取得します。また、AssocCreate を呼び出す(clsid に CLSID_QueryAssociations を設定する)ことでインターフェイスポインターを取得することもできます。インターフェイスは IQueryAssociations::Init で初期化します。このメソッドは、レジストリから情報を取得するために残りの 3 つのメソッドのいずれかを呼び出す際に使用されるルートキーを設定します。これらのメソッドはルートキーより下のみを検索します。不要になったらインターフェイスを解放する必要があります。
IQueryAssociations インターフェイスは、レジストリから情報を繰り返しクエリする必要がある場合に役立ちます。インターフェイスが初期化されると、各種メソッドを呼び出すオーバーヘッドは比較的小さくなります。関連する複数の関数も存在し(「関連項目」セクションに一覧表示)、これらを使用すると単一の関数呼び出しでレジストリから同じ情報を取得できます。これらは使用が簡単ですが、呼び出されるたびに IQueryAssociations の作成と初期化のオーバーヘッドが発生します。このため、これらは 1 回限りの使用に最も適しています。
メソッド 5
vtbl = vtable インデックス(0始まり)。HSP等からCOMメソッドをインデックス指定で呼ぶ際に使用します。0〜2 は IUnknown。
IQueryAssociations インターフェイスを初期化し、ルートキーを適切な ProgID に設定します。
| flags | ASSOCF | in | 検索の初期化方法を指定するフラグです。通常はゼロに設定されますが、次の ASSOCF 値のいずれかを指定することもできます。 |
| pszAssoc | LPWSTR | inoptional | ルートキーを決定するために使用される Unicode 文字列です。hkProgid に値が指定されている場合は、このパラメーターを NULL に設定してください。次の 4 種類の文字列を使用できます。 ファイル名拡張子.txt などのファイル名拡張子。 CLSID標準の "{GUID}" 形式の CLSID GUID。 ProgIDWord.Document.8 などのアプリケーションの ProgID。 実行可能ファイル名アプリケーションの .exe ファイルの名前。flags に ASSOCF_OPEN_BYEXENAME フラグを設定する必要があります。 |
| hkProgid | HKEY | inoptional | ルートキーとして使用されるサブキーの HKEY 値です。検索はこのキーより下のみを対象とします。pwszAssoc に値が指定されている場合は、このパラメーターを NULL に設定してください。 |
| hwnd | HWND | inoptional |
戻り値
型: HRESULT
このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。
解説(Remarks)
このメソッドはインターフェイスを初期化し、新しいルートキーを指定する必要があるたびに呼び出されます。pwszAssoc を使用して、ルートキーを識別する文字列(ファイル名拡張子やそれに関連付けられた ProgID など)を指定できます。また、ルートキーの HKEY 値を指定することもできます。Init はこの情報を使用して、レジストリ内のルートキーを特定します。その他の IQueryAssociations メソッドへの後続の呼び出しは、これを起点として使用し、ルートキーのサブキー内で情報を検索します。
ファイルまたはプロトコルの関連付けに関連する文字列をレジストリから検索して取得します。(IQueryAssociations.GetString)
| flags | ASSOCF | in | 検索を制御するために使用できるフラグです。次の ASSOCF 値の任意の組み合わせを指定できます。 |
| str | ASSOCSTR | in | 返される文字列の種類を指定する ASSOCSTR 値です。 |
| pszExtra | LPWSTR | inoptional | 文字列の場所に関する情報を含む、オプションの null 終端 Unicode 文字列へのポインターです。通常は open などのシェル動詞に設定されます。使用しない場合は、このパラメーターを NULL に設定してください。 |
| pszOut | LPWSTR | outoptional | 要求された文字列を返すために使用される null 終端 Unicode 文字列へのポインターです。必要なバッファーサイズを取得するには、このパラメーターを NULL に設定してください。 |
| pcchOut | DWORD* | inout | 入力時には pwszOut バッファー内の文字数に設定される値へのポインターです。関数が正常に返された場合は、バッファーに格納された文字数を指します。 flags に ASSOCF_NOTRUNCATE フラグが設定されており、pwszOut で指定されたバッファーが小さすぎる場合、関数は E_POINTER を返し、pcchOut は必要なバッファーサイズを指します。 pwszOut が NULL の場合、関数は S_FALSE を返し、pcchOut は必要なバッファーサイズを指します。 |
戻り値
型: HRESULT
次を含む標準の COM エラー値を返します。
| エラー | 意味 |
|---|---|
| S_OK | 成功。 |
| E_POINTER | pwszOut バッファーが小さすぎて文字列全体を保持できません。 |
| S_FALSE | pwszOut が NULL です。pcchOut に必要なバッファーサイズが格納されます。 |
ファイルまたはプロトコルの関連付けに関連するキーをレジストリから検索して取得します。
| flags | ASSOCF | in | 検索を制御するために使用できる ASSOCF 値です。 |
| key | ASSOCKEY | in | 返されるキーの種類を指定する ASSOCKEY 値です。 |
| pszExtra | LPWSTR | inoptional | キーの場所に関する情報を含む、オプションの null 終端 Unicode 文字列へのポインターです。通常は open などのシェル動詞に設定されます。使用しない場合は、このパラメーターを NULL に設定してください。 |
| phkeyOut | HKEY* | out | キーの HKEY 値へのポインターです。 |
戻り値
型: HRESULT
このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。
ファイルまたはプロトコルの関連付けに関連するバイナリデータをレジストリから検索して取得します。
| flags | ASSOCF | in | 検索を制御するために使用できる ASSOCF 値です。 |
| data | ASSOCDATA | in | 返されるデータの種類を指定する ASSOCDATA 値です。 |
| pszExtra | LPWSTR | inoptional | データの場所に関する情報を含む、オプションの null 終端 Unicode 文字列へのポインターです。通常は open などのシェル動詞に設定されます。使用しない場合は、このパラメーターを NULL に設定してください。 |
| pvOut | void* | outoptional | このメソッドが正常に返されたときに、要求されたデータ値を受け取る値へのポインターです。 |
| pcbOut | DWORD* | inoutoptional | このメソッドが呼び出されたときに pvOut のサイズ(バイト単位)を保持する値へのポインターです。このメソッドが正常に返されると、この値には実際に取得されたデータのサイズが格納されます。 |
戻り値
型: HRESULT
このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。
このメソッドは実装されていません。(IQueryAssociations.GetEnum)
| flags | ASSOCF | in | TBD |
| assocenum | ASSOCENUM | in | TBD |
| pszExtra | LPWSTR | inoptional | TBD |
| riid | GUID* | in | TBD |
| ppvOut | void** | out | TBD |
戻り値
このメソッドは値を返しません。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)
HSP用 COM定義
#usecom / #comfunc によるHSPのCOM呼び出し定義。数字は vtbl インデックス(0始まり)。クラスIDが無い場合 #usecom の末尾は "{}"、ある場合は "{CLSID}"。
#define global IID_IQueryAssociations "{C46CA590-3C3F-11D2-BEE6-0000F805CA57}" #usecom global IQueryAssociations IID_IQueryAssociations "{A07034FD-6CAA-4954-AC3F-97A27216F98A}" #comfunc global IQueryAssociations_Init 3 int,wstr,sptr,sptr #comfunc global IQueryAssociations_GetString 4 int,int,wstr,var,var #comfunc global IQueryAssociations_GetKey 5 int,int,wstr,sptr #comfunc global IQueryAssociations_GetData 6 int,int,wstr,sptr,var #comfunc global IQueryAssociations_GetEnum 7 int,int,wstr,var,sptr ; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。 ; ※#usecom 末尾は CoCreateInstance 用のクラスID(コクラスCLSID, SDKから自動取得)。 ; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。 ; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。#define global IID_IQueryAssociations "{C46CA590-3C3F-11D2-BEE6-0000F805CA57}" #usecom global IQueryAssociations IID_IQueryAssociations "{A07034FD-6CAA-4954-AC3F-97A27216F98A}" #comfunc global IQueryAssociations_Init 3 int,wstr,sptr,sptr #comfunc global IQueryAssociations_GetString 4 int,int,wstr,sptr,sptr #comfunc global IQueryAssociations_GetKey 5 int,int,wstr,sptr #comfunc global IQueryAssociations_GetData 6 int,int,wstr,sptr,sptr #comfunc global IQueryAssociations_GetEnum 7 int,int,wstr,sptr,sptr ; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。 ; ※#usecom 末尾は CoCreateInstance 用のクラスID(コクラスCLSID, SDKから自動取得)。 ; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。 ; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。