IThumbnailCache
COM公式ドキュメント
アプリケーション間で共有されるシステムサムネイルキャッシュのためのメソッドを公開します。
解説(Remarks)
Thumbnail Cache API は、サムネイルの取得とキャッシュを行うための統一された方法をアプリケーションに提供するために設計されています。Windows XP では、サムネイルのキャッシュはフォルダー単位で行われ、キャッシュは各フォルダー内の Thumbs.db ファイルに保持されていました。この方式は空間的局所性を提供しますが、フォルダーをまたいだプレビューやクエリはサポートしていません。Windows Vista のサムネイルキャッシュは、グローバルなキャッシュを提供することでこの欠点を解消しています。
サムネイルをキャッシュするには、アプリケーションはまずサムネイルを取得する対象の項目を表す IShellItem を取得し、その IShellItem を IThumbnailCache::GetThumbnail の呼び出しに渡す必要があります。IThumbnailCache::GetThumbnail の flags パラメーターに WTS_EXTRACT フラグが含まれており、サムネイルがまだキャッシュされていない場合は、サムネイルが抽出されてキャッシュに配置されます。WTS_FORCEEXTRACTION フラグが設定されている場合は、キャッシュが無視され、常に新しいサムネイルが抽出されます。IThumbnailCache::GetThumbnail に渡すフラグの詳細については、IThumbnailCache::GetThumbnail のトピックを参照してください。
サムネイルがまだキャッシュに存在しない場合は、オペレーティングシステムに登録されている既存の IExtractImage または IThumbnailProvider の実装を使用して、ソースファイルから自動的に抽出されます。アプリケーション側でサムネイル抽出機能の実装を用意する必要はありません。
IThumbnailCache::GetThumbnail が戻ると、その pThumbnailID パラメーターに、サムネイルの一意な ID を含む WTS_THUMBNAILID 構造体が格納されます。この ID を保存しておけば、IThumbnailCache::GetThumbnailByID に渡してキャッシュされたサムネイルを取得できます。あるいは、WTS_CACHEONLY フラグを設定して IThumbnailCache::GetThumbnail を呼び出すこともできます。この場合、サムネイルは既にキャッシュされているときのみ返されます。IThumbnailCache::GetThumbnailByID ではなく IThumbnailCache::GetThumbnail を使用する場合の欠点は、依然として IShellItem を提供する必要があることです。
パフォーマンスを向上させるために、複数のスレッドを使用してサムネイルキャッシュにアクセスできます。IThumbnailCache::GetThumbnail を、優先度の高いスレッド上で WTS_INCACHEONLY または WTS_FASTEXTRACT フラグを設定して呼び出すことで、キャッシュされたサムネイルを即座に取得できます。そして、画像がキャッシュに存在しない場合、または WTS_LOWQUALITY によってキャッシュ画像の品質が理想的でないことが示された場合は、優先度の低いスレッドを使用して WTS_EXTRACT フラグを設定した IThumbnailCache::GetThumbnail を呼び出し、サムネイルを抽出できます。
メソッド 2
vtbl = vtable インデックス(0始まり)。HSP等からCOMメソッドをインデックス指定で呼ぶ際に使用します。0〜2 は IUnknown。
指定した Shell 項目に対するキャッシュ済みサムネイルを取得します。
| pShellItem | IShellItem* | in | サムネイルを取得する対象の Shell 項目へのポインター。 |
| cxyRequestedThumbSize | DWORD | in | 要求するサムネイルのサイズ(ピクセル単位)。最大値は 1024 です。 |
| flags | WTS_FLAGS | in | WTS_FLAGS 列挙型の値の組み合わせ。規則および可能な組み合わせの一覧については、「解説」セクションを参照してください。 |
| ppvThumb | ISharedBitmap** | outoptional | ISharedBitmap ポインターのアドレス。このメソッドが正常に返ると、サムネイルへのアクセスに使用するオブジェクトを受け取ります。このパラメーターは NULL でもかまいません。 |
| pOutFlags | WTS_CACHEFLAGS* | outoptional | このメソッドが正常に返ると、WTS_CACHEFLAGS 列挙型の次のフラグの組み合わせを受け取る値へのポインター。 WTS_DEFAULT (0x00000000)0x00000000。 WTS_LOWQUALITY (0x00000001)0x00000001。返されたビットマップの寸法が cxyRequestedThumbSize より小さい場合に設定されます。 WTS_CACHED (0x00000002)0x00000002。返された画像がキャッシュ内にある場合に設定されます。 |
| pThumbnailID | WTS_THUMBNAILID* | outoptional | このメソッドが正常に返ると、返されたサムネイルの一意な ID を受け取る値へのポインター。このパラメーターは NULL でもかまいません。その場合、サムネイル ID は破棄されます。 |
戻り値
型: HRESULT
成功した場合は S_OK を返し、それ以外の場合は次のものを含む標準の COM エラー値を返します。
| 戻り値 | 説明 |
|---|---|
| パラメーターが無効です。 | |
| Shell 項目がサムネイルの抽出をサポートしていません。たとえば .exe や .lnk 項目です。 | |
| 抽出に許容される最大時間よりも長い時間がかかりました。抽出は完了しませんでした。 | |
| 抽出処理に使用できるサロゲートプロセスが利用できませんでした。 | |
| WTS_FASTEXTRACT フラグが設定されましたが、高速抽出は利用できません。 |
解説(Remarks)
サムネイルが抽出された場合、WTS_EXTRACTDONOTCACHE が指定されていない限り、そのサムネイルはキャッシュされます。
flags パラメーターには次の組み合わせが有効です。
| WTS_INCACHEONLY |
| WTS_FASTEXTRACT |
| WTS_EXTRACT |
| WTS_EXTRACT | WTS_SLOWRECLAIM |
| WTS_FORCEEXTRACTION |
| WTS_FORCEEXTRACTION | WTS_SLOWRECLAIM |
| WTS_EXTRACTDONOTCACHE |
GetImage もこのキャッシュを使用しており、サムネイルを取得するより簡単な方法を提供できます。ただし、GetImage はより汎用的であり、フォールバックとしてアイコンを取得します。
ID を指定して、サムネイルキャッシュからサムネイルを取得します。
| thumbnailID | WTS_THUMBNAILID | in | 取得するサムネイルの ID。この ID は GetThumbnail を呼び出すことで取得できます。 |
| cxyRequestedThumbSize | DWORD | in | 要求するサムネイルのサイズ(ピクセル単位)。この値は 1024 より大きくすることはできません。 |
| ppvThumb | ISharedBitmap** | outoptional | ISharedBitmap インターフェイスポインターのアドレス。このメソッドが正常に返ると、要求されたサムネイルにアクセスするためのオブジェクトを受け取ります。このパラメーターは NULL でもかまいません。 |
| pOutFlags | WTS_CACHEFLAGS* | outoptional | このメソッドが正常に返ると、次のフラグの組み合わせを受け取る値へのポインター。この情報が不要な場合は NULL に設定できます。 WTS_DEFAULT (0x00000000)0x00000000。 WTS_LOWQUALITY (0x00000001)0x00000001。返されたビットマップの寸法が cxyRequestedThumbSize より小さい場合に設定されます。 WTS_CACHED (0x00000002)0x00000002。返された画像がキャッシュ内にある場合に設定されます。 |
戻り値
型: HRESULT
成功した場合は S_OK を返し、それ以外の場合は次のものを含むエラー値を返します。
| 戻り値 | 説明 |
|---|---|
| パラメーターが無効です。 | |
| Shell 項目がサムネイルの抽出をサポートしていません。たとえば .exe や .lnk 項目です。 | |
| 抽出に許容される最大時間よりも長い時間がかかりました。抽出は完了しませんでした。 | |
| 抽出処理に使用できるサロゲートプロセスが利用できませんでした。 | |
| WTS_FASTEXTRACT フラグが設定されましたが、高速抽出は利用できません。 |
解説(Remarks)
このメソッドは通常、サムネイル ID を取得するために GetThumbnail が既に呼び出された後に呼び出されます。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)
HSP用 COM定義
#usecom / #comfunc によるHSPのCOM呼び出し定義。数字は vtbl インデックス(0始まり)。クラスIDが無い場合 #usecom の末尾は "{}"、ある場合は "{CLSID}"。
#define global IID_IThumbnailCache "{F676C15D-596A-4CE2-8234-33996F445DB1}" #usecom global IThumbnailCache IID_IThumbnailCache "{}" #comfunc global IThumbnailCache_GetThumbnail 3 sptr,int,int,sptr,var,var #comfunc global IThumbnailCache_GetThumbnailByID 4 int,int,sptr,var ; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。 ; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。 ; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。 ; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。#define global IID_IThumbnailCache "{F676C15D-596A-4CE2-8234-33996F445DB1}" #usecom global IThumbnailCache IID_IThumbnailCache "{}" #comfunc global IThumbnailCache_GetThumbnail 3 sptr,int,int,sptr,sptr,sptr #comfunc global IThumbnailCache_GetThumbnailByID 4 int,int,sptr,sptr ; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。 ; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。 ; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。 ; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。