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

IShellImageData

COM
IIDbfdeec12-8040-4403-a5ea-9e07dafcf530継承元IUnknown自前メソッド開始 vtbl3

公式ドキュメント

画像データを表示、操作、記述するためのメソッドとプロパティを公開します。

解説(Remarks)

このインターフェイスは、Windows Vista より前の公開ヘッダーファイルには含まれていませんでした。

メソッド 30

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

vtbl 3 HRESULT Decode(DWORD dwFlags, DWORD cxDesired, DWORD cyDesired)

画像ファイルをデコードし、状態を設定します。

dwFlagsDWORDin

次のいずれかのフラグ。

SHIMGDEC_DEFAULT (0x00)

完全な画像を作成します。

SHIMGDEC_THUMBNAIL (0x01)

サムネイル画像のみをデコードします。

SHIMGDEC_LOADFULL (0x02)

画像ファイル全体をメモリに読み込みます。

cxDesiredDWORDinデコードされた画像に希望する水平方向のサイズ。このパラメーターは SHIMGDEC_THUMBNAIL フラグが設定されている場合にのみ使用されます。代わりに SHIMGDEC_DEFAULT フラグが設定されている場合、この値は無視されます。
cyDesiredDWORDinデコードされた画像に希望する垂直方向のサイズ。このパラメーターは SHIMGDEC_THUMBNAIL フラグが設定されている場合にのみ使用されます。代わりに SHIMGDEC_DEFAULT フラグが設定されている場合、この値は無視されます。

戻り値

型: HRESULT

成功した場合は S_OK を返し、それ以外の場合は次を含むエラー値を返します。

戻り値のコード 説明
E_FAIL
ファイルを読み込めなかったか、呼び出し元のアプリケーションが登録済みの IShellImageDataAbort の呼び出しを通じてデコード処理を停止しました(詳細については IShellImageData::RegisterAbort を参照してください)。
E_OUTOFMEMORY
内部オブジェクトをインスタンス化できません。
E_NOTIMPL
この IShellImageData のインスタンスを作成するために使用されたパスが URL でした。
S_FALSE
画像は既にデコードされています。

解説(Remarks)

ほとんどの IShellImageData メソッドを呼び出す前に、IShellImageData::Decode を呼び出す必要があります。呼び出さない場合、それらのメソッドは失敗します。

IShellImageData::Decode は元の画像の縦横比を維持しようとするため、そのために cxDesired または cyDesired に渡された値のいずれかが上書きされる場合があります。

vtbl 4 HRESULT Draw(HDC hdc, RECT* prcDest, RECT* prcSrc)

デコードされた画像を描画します。

hdcHDCin画像のハンドル。
prcDestRECT*inout描画される画像の範囲をピクセル単位で指定する RECT へのポインター。prcSrc で指定された画像の部分は、prcDest で指定された矩形を満たすように拡大縮小されます。
prcSrcRECT*inout描画する画像の部分を指定する RECT へのポインター。

戻り値

型: HRESULT

成功した場合は S_OK を返し、それ以外の場合は次を含むエラー値を返します。

戻り値のコード 説明
E_FAIL
画像が事前にデコードされていない、IShellImageData::Decode の呼び出しが失敗した、または hdcNULL です。その他の内部呼び出しでもこのエラーが返される場合があります。
E_INVALIDARG
prcDest パラメーターが NULL です。
E_ABORT
呼び出し元のアプリケーションが、登録済みの IShellImageDataAbort のインスタンスを通じて処理を終了しました。

解説(Remarks)

prcSrcNULL の場合、何も描画されず、メソッドは S_OK を返します。

vtbl 5 HRESULT NextFrame()

アニメーション画像の次のフレームに切り替えます。

戻り値

型: HRESULT

成功した場合は S_OK を返し、それ以外の場合は次を含むエラー値を返します。

戻り値のコード 説明
E_FAIL
現在のフレームを取得できません。
S_FALSE
画像がアニメーションではない、画像がまだデコードされていない、またはアニメーションのループ回数の上限に達しました。
E_PENDING
次のフレームはまだ利用できません。
E_NOMOREDATA
これ以上のデータは利用できません。
vtbl 6 HRESULT NextPage()

複数ページ画像の次のページに切り替えます。関連するアニメーションはリセットされます。

戻り値

型: HRESULT

成功した場合は S_OK を返し、それ以外の場合は次を含むエラー値を返します。

戻り値のコード 説明
E_FAIL
現在のページを取得できません。
OLE_E_ENUM_NOMORE
これ以上のページが利用できない、画像が事前にデコードされていない、またはデコード処理が失敗しました。
vtbl 7 HRESULT PrevPage()

複数ページ画像の前のページに切り替えます。関連するアニメーションはリセットされます。

戻り値

型: HRESULT

成功した場合は S_OK を返し、それ以外の場合は次を含むエラー値を返します。

戻り値のコード 説明
E_FAIL
現在のフレームを取得できません。
OLE_E_ENUM_NOMORE
前のページが利用できない、画像が事前にデコードされていない、またはデコード処理が失敗しました。
vtbl 8 HRESULT IsTransparent()

画像が透過性を持つかどうかを判定します。

戻り値

型: HRESULT

次のいずれかを返します。

戻り値のコード 説明
S_OK
画像は透過性を持ちます。
S_FALSE
画像は透過性を持ちません。
E_FAIL
画像はデコードされていません。

解説(Remarks)

画像が透過性をサポートしていても使用していない場合、メソッドは S_FALSE を返します。

vtbl 9 HRESULT IsAnimated()

画像がアニメーションかどうかを判定します。

戻り値

型: HRESULT

次のいずれかを返します。

戻り値のコード 説明
S_OK
画像はアニメーションです。
S_FALSE
画像がアニメーションではない、デコードされていない、またはデコード処理が失敗しました。
vtbl 10 HRESULT IsVector()

画像がベクター画像かどうかを判定します。

戻り値

型: HRESULT

次のいずれかを返します。

戻り値のコード 説明
S_OK
画像はベクター画像であり、GDI+ フラグ ImageFlagsScalable をサポートしています。
E_FAIL
画像がデコードされていない、画像が空である、またはファイルが画像ではありません。
S_FALSE
その他すべての場合。
vtbl 11 HRESULT IsMultipage()

画像が複数ページの Tagged Image File Format (TIFF) 画像かどうかを判定します。

戻り値

型: HRESULT

次のいずれかを返します。

戻り値のコード 説明
S_OK
画像は複数のページを含みます。
E_FAIL
画像が 1 ページしかない、画像がデコードされていない、またはデコード処理が失敗しました。
vtbl 12 HRESULT IsEditable()

画像が編集可能かどうかを判定します。

戻り値

型: HRESULT

次のいずれかを返します。

戻り値のコード 説明
S_OK
画像は編集可能です。
S_FALSE
画像が編集できない、画像がデコードされていない、またはデコード処理が失敗しました。

解説(Remarks)

現時点では、画像が編集可能かどうかを判定する基準は、Exif IFD タグが設定された Tagged Image File Format (TIFF) 画像であることのみです。

vtbl 13 HRESULT IsPrintable()

画像が印刷可能かどうかを判定します。

戻り値

型: HRESULT

成功した場合は S_OK を返し、それ以外の場合は次を含むエラー値を返します。

戻り値のコード 説明
E_FAIL
画像はデコードされていません。
vtbl 14 HRESULT IsDecoded()

IShellImageData::Decode を呼び出すことによって画像がデコードされたかどうかを判定します。画像が先にデコードされていない場合、多くの操作は失敗コードを返します。

戻り値

型: HRESULT

次のいずれかを返します。

戻り値のコード 説明
S_OK

画像に対して IShellImageData::Decode が呼び出され、成功しました。

S_FALSE
その他すべての場合。
vtbl 15 HRESULT GetCurrentPage(DWORD* pnPage)

複数ページ画像の現在のページを取得します。

pnPageDWORD*inoutページ番号へのポインター。

戻り値

型: HRESULT

S_OK を返します。.jpg ファイルなど、画像が複数ページ画像でない場合、メソッドはページ番号 0 とともに S_OK を返します。

vtbl 16 HRESULT GetPageCount(DWORD* pcPages)

複数ページ画像のページ数を取得します。

pcPagesDWORD*inoutページ数へのポインター。この値はメソッドが S_OK を返す場合にのみ有効です。

戻り値

型: HRESULT

成功した場合は S_OK を返し、それ以外の場合は次を含むエラー値を返します。

戻り値のコード 説明
E_FAIL
画像がデコードされていないか、デコード処理が失敗しました。

解説(Remarks)

.jpg ファイルなど、画像が複数ページ画像でない場合、メソッドはページ数 1 とともに S_OK を返します。

vtbl 17 HRESULT SelectPage(DWORD iPage)

複数ページ画像内の指定されたページを選択します。

iPageDWORDin選択するページのページ番号。

戻り値

型: HRESULT

成功した場合は S_OK を返し、それ以外の場合は次を含むエラー値を返します。

戻り値のコード 説明
E_FAIL
現在のページを取得できない、画像がデコードされていない、またはデコード処理が失敗しました。
OLE_E_ENUM_NOMORE
指定されたページ番号は存在しません。
vtbl 18 HRESULT GetSize(SIZE* pSize)

画像ファイルの寸法を取得します。

pSizeSIZE*inout画像のサイズを含む SIZE 構造体へのポインター。この値はメソッドが S_OK を返す場合にのみ有効です。

戻り値

型: HRESULT

成功した場合は S_OK を返し、それ以外の場合は次を含むエラー値を返します。

戻り値のコード 説明
E_FAIL
画像がデコードされていないか、デコード処理が失敗しました。
vtbl 19 HRESULT GetRawDataFormat(GUID* pDataFormat)

画像の形式を識別する GUID を取得します。

pDataFormatGUID*inout形式を示す値へのポインター。この値はメソッドが S_OK を返す場合にのみ有効です。

戻り値

型: HRESULT

成功した場合は S_OK を返し、それ以外の場合は次を含むエラー値を返します。

戻り値のコード 説明
E_FAIL
画像がデコードされていないか、デコード処理が失敗しました。

解説(Remarks)

さまざまなファイル形式を識別する GUID は Gdiplusimaging.h で定義されています。

vtbl 20 HRESULT GetPixelFormat(DWORD* pFormat)

画像のピクセル形式を取得します。

pFormatDWORD*inoutピクセル形式を示す PixelFormat 型の値へのポインター。この値はメソッドが S_OK を返す場合にのみ有効です。

戻り値

型: HRESULT

成功した場合は S_OK を返し、それ以外の場合は次を含むエラー値を返します。

戻り値のコード 説明
E_FAIL
画像がデコードされていないか、デコード処理が失敗しました。

解説(Remarks)

さまざまなピクセル形式を識別する値は Gdipluspixelformats.h で定義されています。

vtbl 21 HRESULT GetDelay(DWORD* pdwDelay)

アニメーションの現在のフレームの遅延値を取得します。

pdwDelayDWORD*inout遅延値(ミリ秒単位)へのポインター。この値はメソッドが S_OK を返す場合にのみ有効です。

戻り値

型: HRESULT

成功した場合は S_OK を返し、それ以外の場合は次を含むエラー値を返します。

戻り値のコード 説明
E_FAIL
画像がデコードされていないか、デコード処理が失敗しました。

解説(Remarks)

アニメーション画像では、遅延はフレームごとに異なる場合があります。

このメソッドは最小値として 100 ミリ秒を取得します。この時間より短い値も 100 ミリ秒として報告されます。

vtbl 22 HRESULT GetProperties(DWORD dwMode, IPropertySetStorage** ppPropSet)

画像のプロパティにアクセスするための IPropertySetStorage を取得します。

dwModeDWORDin使用されません。0 を設定します。
ppPropSetIPropertySetStorage**outIPropertySetStorage インターフェイスへのポインターのアドレス。

戻り値

型: HRESULT

成功した場合は S_OK を返し、それ以外の場合は次を含むエラー値を返します。

戻り値のコード 説明
E_FAIL
画像がデコードされていないか、デコード処理が失敗しました。
E_POINTER
ppPropSet ポインターが無効です。
vtbl 23 HRESULT Rotate(DWORD dwAngle)

画像を 90 度単位で回転します。

dwAngleDWORDin回転角度。0、90、180、270 の角度のみが認識されます。

戻り値

型: HRESULT

成功した場合は S_OK を返し、それ以外の場合は次を含むエラー値を返します。

戻り値のコード 説明
E_FAIL
画像がデコードされていないか、デコード処理が失敗しました。この値は、GDI+ メソッドへの特定の内部呼び出しが失敗した場合にも返されます。
E_NOTVALIDFORANIMATEDIMAGE
画像はアニメーション画像であり、回転できません。
E_INVALIDARG
dwAngle パラメーターが 0、90、180、270 以外の値です。
S_FALSE
dwAngle パラメーターが 0 です。
E_OUTOFMEMORY
メソッドが画像の内部作業コピーを作成するのに十分なリソースがありません。
vtbl 24 HRESULT Scale(DWORD cx, DWORD cy, InterpolationMode hints)

画像のサイズを調整します。

cxDWORDin水平方向(x)の寸法。この値が 0 の場合、x の寸法は cy で指定された値に基づいて拡大縮小された値に設定されます。
cyDWORDin垂直方向(y)の寸法。この値が 0 の場合、y の寸法は cx で指定された値に基づいて拡大縮小された値に設定されます。
hintsInterpolationModein画像を拡大縮小する際に使用されるアルゴリズムを指定する InterpolationMode 列挙型のメンバー。

戻り値

型: HRESULT

成功した場合は S_OK を返し、それ以外の場合は次を含むエラー値を返します。

戻り値のコード 説明
E_FAIL
画像が事前にデコードされていないか、IShellImageData::Decode の呼び出しが失敗しました。その他の内部呼び出しでもこのエラーが返される場合があります。
E_NOTVALIDFORANIMATEDIMAGE
画像はアニメーション画像であり、このメソッドでは拡大縮小できません。
E_OUTOFMEMORY
内部オブジェクトをインスタンス化できません。
E_ABORT
呼び出し元のアプリケーションが、登録済みの IShellImageDataAbort のインスタンスを通じて処理を停止しました。
vtbl 25 HRESULT DiscardEdit()

画像に加えられた編集を破棄します。

戻り値

型: HRESULT

常に S_OK を返します。

vtbl 26 HRESULT SetEncoderParams(IPropertyBag* pbagEnc)

エンコーダーのパラメーターを設定します。

pbagEncIPropertyBag*inエンコーダーのプロパティを含む IPropertyBag へのポインター。

戻り値

型: HRESULT

常に S_OK を返します。

解説(Remarks)

pbagEnc に渡された IPropertyBag は、保存操作中に使用されます。画像および RotateScale などそれに加えられた編集は、IPersistFile または IPersistStream のいずれかに対して QueryInterface を呼び出し、それらの Save メソッドを呼び出すことで保存できます。

vtbl 27 HRESULT DisplayName(LPWSTR wszName, DWORD cch)

IShellImageData がファイルパスで初期化された場合はファイル名を取得します。それ以外の場合はデータストリームの名前を取得します。

wszNameLPWSTRin表示名を Unicode 文字列として含むバッファーへのポインター。終了時、バッファーの内容はメソッドが S_OK を返す場合にのみ有効です。
cchDWORDinwszName が指すバッファーのサイズ(文字数単位)。

戻り値

型: HRESULT

成功した場合は S_OK を返し、それ以外の場合は次を含むエラー値を返します。

戻り値のコード 説明
E_FAIL
ファイル名またはストリーム名を取得できません。
vtbl 28 HRESULT GetResolution(DWORD* puResolutionX, DWORD* puResolutionY)

画像の解像度を 1 インチあたりのドット数(dpi)で取得します。

puResolutionXDWORD*inout水平方向の解像度へのポインター。
puResolutionYDWORD*inout垂直方向の解像度へのポインター。

戻り値

型: HRESULT

成功した場合は S_OK を返し、それ以外の場合は次を含むエラー値を返します。

戻り値のコード 説明
E_FAIL
画像がデコードされていない、デコード処理が失敗した、または解像度を取得できません。後者の場合、puResolutionXpuResolutionY の両方が 0 に設定されます。
E_INVALIDARG
puResolutionXpuResolutionY の両方が NULL です。

解説(Remarks)

puResolutionX または puResolutionY のいずれかが NULL の場合、メソッドは NULL でない方のパラメーターの値のみを返します。

vtbl 29 HRESULT GetEncoderParams(GUID* pguidFmt, BYTE** ppEncParams)

現在のエンコーダーパラメーターのセットを取得します。

pguidFmtGUID*inoutエンコーダーを指定する GUID へのポインター。これは GDI+ でサポートされているエンコーダーである必要があります。このパラメーターが NULL の場合、ハンドルされない例外が発生します。
ppEncParamsBYTE**inoutEncoderParameter オブジェクトの配列へのポインターのアドレス。

戻り値

型: HRESULT

成功した場合は S_OK を返し、それ以外の場合は次を含むエラー値を返します。

戻り値のコード 説明
E_FAIL
いくつかの状況でこの戻り値が生成されます。
  • 画像がデコードされていないか、デコード処理が失敗した。
  • pguidFmt が GDI+ でサポートされていない形式を参照している。
  • 内部呼び出しが失敗した。
vtbl 30 HRESULT RegisterAbort(IShellImageDataAbort* pAbort, IShellImageDataAbort** ppAbortPrev)

コールバック用の中止オブジェクトを設定し、必要に応じて前のオブジェクトへのポインターを返します。

pAbortIShellImageDataAbort*in中止オブジェクトへのポインター。このパラメーターが NULL の場合、ハンドルされない例外が発生します。
ppAbortPrevIShellImageDataAbort**out前の中止オブジェクトへのポインターのアドレス。前のオブジェクトが不要な場合、このパラメーターは NULL にできます。

戻り値

型: HRESULT

成功した場合は S_OK を返し、それ以外の場合はエラー値を返します。

vtbl 31 HRESULT CloneFrame(BYTE** ppImg)

現在の画像またはフレームのクローンを取得します。

ppImgBYTE**inoutクローン画像へのポインターを受け取るアドレス。このパラメーターが入力時に NULL の場合、ハンドルされない例外が発生します。

戻り値

型: HRESULT

成功した場合は S_OK を返し、それ以外の場合は次を含むエラー値を返します。

戻り値のコード 説明
E_FAIL
ppImg パラメーターが入力時に NULL であるか、画像をクローンできません。後者の場合、ppImgNULL に設定されます。

解説(Remarks)

.gif ファイルなどの複数フレーム画像の場合、現在のフレームがクローンされます。.jpg ファイルなどの複数フレームでない画像の場合、画像全体がクローンされます。

vtbl 32 HRESULT ReplaceFrame(BYTE* pImg)

現在のフレームを新しい画像で置き換えます。

pImgBYTE*inout新しい画像のアドレス。

戻り値

型: HRESULT

常に S_OK を返します。

解説(Remarks)

元の画像の編集済みプロパティが保持されないようにするため、IShellImageData::DiscardEdit も呼び出す必要があります。

.gif ファイルなどの複数フレーム画像の場合、現在のフレームが置き換えられます。.jpg ファイルなどの複数フレームでない画像の場合、画像全体が置き換えられます。

アニメーション .gif ファイルのフレームを置き換えると、そのファイルのアニメーションが機能しなくなります。Tagged Image File Format (TIFF) ファイルのフレームを置き換えると、特に TIFF フレームの画像が元と同じサイズでない場合、そのファイルがページを失う可能性があります。可能な限り、TIFF フレームの画像は常に同じサイズの TIFF で置き換える必要があります。

IShellImageData の実装は pImg で指定された画像の所有権を取得するため、呼び出し元は IShellImageData::ReplaceFrame を呼び出した後にそれを使用しようとしてはなりません。

出典・ライセンス: 上記「公式ドキュメント」の内容は 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_IShellImageData "{BFDEEC12-8040-4403-A5EA-9E07DAFCF530}"
#usecom global IShellImageData IID_IShellImageData "{}"
#comfunc global IShellImageData_Decode            3 int,int,int
#comfunc global IShellImageData_Draw              4 sptr,var,var
#comfunc global IShellImageData_NextFrame         5
#comfunc global IShellImageData_NextPage          6
#comfunc global IShellImageData_PrevPage          7
#comfunc global IShellImageData_IsTransparent     8
#comfunc global IShellImageData_IsAnimated        9
#comfunc global IShellImageData_IsVector          10
#comfunc global IShellImageData_IsMultipage       11
#comfunc global IShellImageData_IsEditable        12
#comfunc global IShellImageData_IsPrintable       13
#comfunc global IShellImageData_IsDecoded         14
#comfunc global IShellImageData_GetCurrentPage    15 var
#comfunc global IShellImageData_GetPageCount      16 var
#comfunc global IShellImageData_SelectPage        17 int
#comfunc global IShellImageData_GetSize           18 var
#comfunc global IShellImageData_GetRawDataFormat  19 var
#comfunc global IShellImageData_GetPixelFormat    20 var
#comfunc global IShellImageData_GetDelay          21 var
#comfunc global IShellImageData_GetProperties     22 int,sptr
#comfunc global IShellImageData_Rotate            23 int
#comfunc global IShellImageData_Scale             24 int,int,int
#comfunc global IShellImageData_DiscardEdit       25
#comfunc global IShellImageData_SetEncoderParams  26 sptr
#comfunc global IShellImageData_DisplayName       27 wstr,int
#comfunc global IShellImageData_GetResolution     28 var,var
#comfunc global IShellImageData_GetEncoderParams  29 var,var
#comfunc global IShellImageData_RegisterAbort     30 sptr,sptr
#comfunc global IShellImageData_CloneFrame        31 var
#comfunc global IShellImageData_ReplaceFrame      32 var
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。