IExtractImage
COM公式ドキュメント
Shell フォルダーからサムネイル画像を要求するためのメソッドを公開します。
解説(Remarks)
この処理には 2 つのステップがあります。まず GetLocation を使用して画像のパス記述を要求し、画像のレンダリング方法を指定します。次に Extract を呼び出して画像を抽出します。
オブジェクトがフリースレッドである場合は、必要に応じて停止および開始できるように IRunnableTask インターフェイスも公開する必要があります。この機能は、抽出処理に時間がかかる場合に特に役立ちます。
名前空間拡張機能が Shell ビューに表示するサムネイル画像を提供する必要がある場合は、IExtractImage を実装します。
名前空間オブジェクトのビューを実装し、サムネイル画像を表示したい場合は IExtractImage を使用します。Shell フォルダーの IShellFolder::GetUIObjectOf メソッドを使用して、その IExtractImage インターフェイスにバインドできます。
メソッド 2
vtbl = vtable インデックス(0始まり)。HSP等からCOMメソッドをインデックス指定で呼ぶ際に使用します。0〜2 は IUnknown。
抽出する画像へのパスを取得します。
| pszPathBuffer | LPWSTR | out | パス記述を返すために使用されるバッファーです。この値によって画像が識別されるため、同じ画像を複数回読み込むことを回避できます。 |
| cch | DWORD | in | pszPathBuffer のサイズ (文字数単位) です。 |
| pdwPriority | DWORD* | inout | 使用されません。 Microsoft Windows XP 以前: pdwFlags に IEIFLAG_ASYNC フラグが設定されている場合に、項目の優先度を返すために使用されるポインターです。このパラメーターを NULL にすることはできません。IEIFLAG_ASYNC フラグが設定されているかどうかにかかわらず、このパラメーターが NULL の場合、関数は失敗します。 このパラメーターは通常、画像の抽出に必要な時間を示すために使用されます。サムネイルを抽出する順序をより細かく制御したい場合は、最大 32 ビットまでの複数の優先度レベルを定義できます。異なる優先度レベルに割り当てる整数値が低い優先度から高い優先度へと増加する限り、使用する実際の数値は重要ではありません。これらの数値は画像が抽出される順序を決定するためにのみ使用されます。標準の優先度レベルは 3 つあります。 IEI_PRIORITY_MAX最高優先度。 IEI_PRIORITY_MIN最低優先度。 IEIT_PRIORITY_NORMAL通常の優先度。 Microsoft Windows XP。 使用されません。 |
| prgSize | SIZE* | in | 画像の希望する幅と高さを格納した SIZE 構造体へのポインターです。NULL にすることはできません。 |
| dwRecClrDepth | DWORD | in | 1 ピクセルあたりのビット数単位で表される推奨の色深度です。NULL にすることはできません。 |
| pdwFlags | DWORD* | inout | 画像の処理方法を指定するフラグです。値は次のいずれか 1 つ以上である必要があります。 IEIFLAG_ASPECT指定されたアスペクト比を使用するようオブジェクトに要求するために使用します。このフラグが設定されている場合、希望するアスペクト比を持つ四角形が prgSize に渡されます。このフラグは IEIFLAG_SCREEN と併用できません。 IEIFLAG_ASYNC使用されません。サムネイルは常にバックグラウンドスレッドで抽出されます。 Microsoft Windows XP 以前。 このインスタンスが非同期 (フリースレッド) 抽出をサポートするかどうかを問い合わせるために使用します。呼び出し側アプリケーションがこのフラグを設定すると、IExtractImage::GetLocation は E_PENDING を返すことがあり、これは呼び出し側アプリケーションに別のスレッドで画像を抽出するよう示します。E_PENDING が返された場合、項目の優先度が pdwPriority に返されます。 IEIFLAG_CACHEサポートされていません。 Windows XP 以前: 画像をキャッシュしないことを示すためにオブジェクトによって設定されます。このフラグが返された場合、Shell は画像のコピーをキャッシュします。 IEIFLAG_GLEAMサポートされていません。 IEIFLAG_NOBORDER (0x0100)サポートされていません。 IEIFLAG_NOSTAMP (0x0080)サポートされていません。 IEIFLAG_OFFLINEレンダリングにローカルコンテンツのみを使用するようオブジェクトに指示するために使用します。 IEIFLAG_ORIGSIZEバージョン 5.0。prgSize で渡されたおおよそのサイズに画像をレンダリングし、必要に応じてトリミングするようオブジェクトに指示するために使用します。 IEIFLAG_QUALITY (0x0200)より高品質な画像が要求されていることを示すために IExtractImage::Extract メソッドに渡されます。 このフラグが設定されていない場合、ユーザーが要求するサイズにかかわらず、ファイルに埋め込みサムネイルがあれば IExtractImage はそれを取得します。たとえば、ファイルが 2000x2000 ピクセルで埋め込みサムネイルが 100x100 ピクセルしかない場合、ユーザーがこのフラグを設定せずに 1000x1000 ピクセルのサムネイルを要求しても、IExtractImage は常に 100x100 ピクセルのサムネイルを返します。これは IExtractImage が拡大処理を行わないための仕様です。より大きなサムネイル (埋め込みサムネイルは通常 160x160) を希望する場合は、このフラグを設定する必要があります。 IEIFLAG_REFRESH (0x0400)項目のショートカットメニューに [サムネイルの更新] を表示すべきであることを示すためにオブジェクトによって返されます。 IEIFLAG_SCREEN画面向けであるかのようにレンダリングするようオブジェクトに指示するために使用します。このフラグは IEIFLAG_ASPECT と併用できません。 |
戻り値
型: HRESULT
このメソッドは COM で定義されたエラーコード、または次のいずれかを返すことがあります。
| 戻り値 | 説明 |
|---|---|
| 成功 | |
| Windows XP 以前: IEIFLAG_ASYNC フラグが設定されている場合、この戻り値はオブジェクトがフリースレッドであることを Shell に示すために使用されます。 |
解説(Remarks)
Microsoft Windows XP 以前: このメソッドは画像へのパスを返し、画像のレンダリング方法を指定します。IExtractImage::GetLocation はフリースレッド、すなわちマルチスレッドアパートメントモデル (MTA) をサポートするため、バックグラウンドスレッドに配置できます。呼び出し側アプリケーションが必要に応じて抽出処理を開始および停止できるように、オブジェクトは IRunnableTask インターフェイスも公開する必要があります。
prgSize で定義された境界に収まる画像を返す必要があります。Windows 2000 以降のシステムでは、IEIFLAG_ORIGSIZE を設定することで標準的なアスペクト比を持たないオブジェクトを使用でき、それらは適切に表示されます。四角形の未使用部分を埋める必要はありません。以前のバージョンの Shell で非標準のアスペクト比の画像を使用しようとすると、画像は prgSize の四角形に合わせて引き伸ばされます。アスペクト比が指定されたものとどれだけ異なるかに応じて、画像がひどく歪む場合があります。
Shell フォルダー内の項目などのオブジェクトから画像を要求します。
| phBmpThumbnail | HBITMAP* | out | ビットマップ画像を保持するバッファーです。 |
戻り値
型: HRESULT
成功した場合は S_OK を返し、それ以外の場合は COM で定義されたエラーコードを返します。
解説(Remarks)
Extract を呼び出す前に IExtractImage::GetLocation を呼び出す必要があります。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)
HSP用 COM定義
#usecom / #comfunc によるHSPのCOM呼び出し定義。数字は vtbl インデックス(0始まり)。クラスIDが無い場合 #usecom の末尾は "{}"、ある場合は "{CLSID}"。
#define global IID_IExtractImage "{BB2E617C-0920-11D1-9A0B-00C04FC2D6C1}" #usecom global IExtractImage IID_IExtractImage "{}" #comfunc global IExtractImage_GetLocation 3 var,int,var,var,int,var #comfunc global IExtractImage_Extract 4 sptr ; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。 ; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。 ; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。 ; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。#define global IID_IExtractImage "{BB2E617C-0920-11D1-9A0B-00C04FC2D6C1}" #usecom global IExtractImage IID_IExtractImage "{}" #comfunc global IExtractImage_GetLocation 3 sptr,int,sptr,sptr,int,sptr #comfunc global IExtractImage_Extract 4 sptr ; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。 ; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。 ; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。 ; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。