ホーム › UI.Shell › IThumbnailProvider

IThumbnailProvider

COM

IIDe357fccd-a995-4576-b01f-234630154e96継承元IUnknown自前メソッド開始 vtbl3

公式ドキュメント

サムネイル画像を取得するためのメソッドを公開します。サムネイルハンドラーで実装されることを意図しています。このインターフェイスを実装するオブジェクトは、IInitializeWithStream も実装する必要があります。

解説(Remarks)

シェルは IThumbnailProvider::GetThumbnail を呼び出して、項目を表現するために使用する画像を取得します。

写真のサムネイル向けのこのインターフェイスの実装は、Microsoft Windows において CLSID_PhotoThumbnailProvider として提供されています。提供される実装を使用するアプリケーションは、GUID {C7657C4A-9F68-40fa-A4DF-96BC08EB3551} を用いて定数 CLSID 識別子を定義する必要があります。

// {C7657C4A-9F68-40fa-A4DF-96BC08EB3551}
const CLSID CLSID_PhotoThumbnailProvider = {0xC7657C4A, 0x9F68, 0x40fa, {0xA4, 0xDF, 0x96, 0xBC, 0x08, 0xEB, 0x35, 0x51}} ;

初期化 このインターフェイスを実装するオブジェクトは、IInitializeWithStream も実装する必要があります。シェルは項目のストリームを指定して IInitializeWithStream::Initialize を呼び出します。IInitializeWithStream は、IThumbnailProvider インスタンスが(分離を目的として)プロセス外で読み込まれる際に使用される唯一の初期化インターフェイスです。これは、すべての IThumbnailCache のコードパスにおける Windows の主要なコードパスです。

IThumbnailCache API を使用せずにサードパーティによってハンドラーが要求された場合、サムネイル実装が IInitializeWithItem または IInitializeWithFile で初期化されることもありますが、これはまれです。IInitializeWithItem を実装した場合、シェルは項目の IShellItem 表現を指定して IInitializeWithItem::Initialize を呼び出します。IInitializeWithFile を実装した場合、シェルはファイルのパスを指定して IInitializeWithFile::Initialize を呼び出します。

これらのインターフェイスがいずれも存在しない場合、IThumbnailProvider は呼び出されません。

クライアントアプリ クライアントアプリを開発している場合は、代わりに IShellItemImageFactory を使用してください。

Windows Vista IThumbnailProvider は Vista で新規に導入され、IExtractImage を置き換えます。Vista は引き続き IExtractImage をサポートしますが、画像の種類(アルファの有無)を返す機能はありません。

メソッド 1

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

vtbl 3 HRESULT GetThumbnail(DWORD cx, HBITMAP* phbmp, WTS_ALPHATYPE* pdwAlpha)

サムネイル画像とアルファの種類を取得します。

DWORD

サムネイルの最大サイズ(ピクセル単位)。シェルは返されたビットマップをこのサイズ以下で描画します。返されるビットマップは幅と高さが cx の正方形に収まる必要がありますが、正方形の画像である必要はありません。シェルはより小さいサイズで描画するためにビットマップを縮小します。たとえば、画像が 6:4 のアスペクト比を持つ場合、返されるビットマップも 6:4 のアスペクト比を持つ必要があります。

phbmp

HBITMAP*

out

このメソッドが返るとき、サムネイル画像ハンドルへのポインターが格納されます。画像は DIB セクションで、1 ピクセルあたり 32 ビットである必要があります。シェルは、幅または高さが cx で指定されたサイズより大きい場合、ビットマップを縮小します。シェルは常にアスペクト比を維持し、ビットマップを元のサイズより大きく拡大することはありません。

pdwAlpha

WTS_ALPHATYPE*

out

このメソッドが返るとき、WTS_ALPHATYPE 列挙型の次の値のいずれかへのポインターが格納されます。

WTSAT_UNKNOWN (0x0)

0x0。ビットマップは不明な形式です。それでもシェルは、画像にアルファチャネルがあるかどうかの検出を試みます。

WTSAT_RGB (0x1)

0x1。ビットマップはアルファのない RGB 画像です。アルファチャネルは無効であり、シェルはそれを無視します。

WTSAT_ARGB (0x2)

0x2。ビットマップは有効なアルファチャネルを持つ ARGB 画像です。

戻り値

型: HRESULT

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

出典・ライセンス: 上記「公式ドキュメント」の内容は 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_IThumbnailProvider "{E357FCCD-A995-4576-B01F-234630154E96}"
#usecom global IThumbnailProvider IID_IThumbnailProvider "{}"
#comfunc global IThumbnailProvider_GetThumbnail  3 int,sptr,var
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。#define global IID_IThumbnailProvider "{E357FCCD-A995-4576-B01F-234630154E96}"
#usecom global IThumbnailProvider IID_IThumbnailProvider "{}"
#comfunc global IThumbnailProvider_GetThumbnail  3 int,sptr,sptr
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。