IShellImageData
COM公式ドキュメント
画像データを表示、操作、記述するためのメソッドとプロパティを公開します。
解説(Remarks)
このインターフェイスは、Windows Vista より前の公開ヘッダーファイルには含まれていませんでした。
メソッド 30
vtbl = vtable インデックス(0始まり)。HSP等からCOMメソッドをインデックス指定で呼ぶ際に使用します。0〜2 は IUnknown。
画像ファイルをデコードし、状態を設定します。
| dwFlags | DWORD | in | 次のいずれかのフラグ。 SHIMGDEC_DEFAULT (0x00)完全な画像を作成します。 SHIMGDEC_THUMBNAIL (0x01)サムネイル画像のみをデコードします。 SHIMGDEC_LOADFULL (0x02)画像ファイル全体をメモリに読み込みます。 |
| cxDesired | DWORD | in | デコードされた画像に希望する水平方向のサイズ。このパラメーターは SHIMGDEC_THUMBNAIL フラグが設定されている場合にのみ使用されます。代わりに SHIMGDEC_DEFAULT フラグが設定されている場合、この値は無視されます。 |
| cyDesired | DWORD | in | デコードされた画像に希望する垂直方向のサイズ。このパラメーターは SHIMGDEC_THUMBNAIL フラグが設定されている場合にのみ使用されます。代わりに SHIMGDEC_DEFAULT フラグが設定されている場合、この値は無視されます。 |
戻り値
型: HRESULT
成功した場合は S_OK を返し、それ以外の場合は次を含むエラー値を返します。
| 戻り値のコード | 説明 |
|---|---|
| ファイルを読み込めなかったか、呼び出し元のアプリケーションが登録済みの IShellImageDataAbort の呼び出しを通じてデコード処理を停止しました(詳細については IShellImageData::RegisterAbort を参照してください)。 | |
| 内部オブジェクトをインスタンス化できません。 | |
| この IShellImageData のインスタンスを作成するために使用されたパスが URL でした。 | |
| 画像は既にデコードされています。 |
解説(Remarks)
ほとんどの IShellImageData メソッドを呼び出す前に、IShellImageData::Decode を呼び出す必要があります。呼び出さない場合、それらのメソッドは失敗します。
IShellImageData::Decode は元の画像の縦横比を維持しようとするため、そのために cxDesired または cyDesired に渡された値のいずれかが上書きされる場合があります。
デコードされた画像を描画します。
| hdc | HDC | in | 画像のハンドル。 |
| prcDest | RECT* | inout | 描画される画像の範囲をピクセル単位で指定する RECT へのポインター。prcSrc で指定された画像の部分は、prcDest で指定された矩形を満たすように拡大縮小されます。 |
| prcSrc | RECT* | inout | 描画する画像の部分を指定する RECT へのポインター。 |
戻り値
型: HRESULT
成功した場合は S_OK を返し、それ以外の場合は次を含むエラー値を返します。
| 戻り値のコード | 説明 |
|---|---|
| 画像が事前にデコードされていない、IShellImageData::Decode の呼び出しが失敗した、または hdc が NULL です。その他の内部呼び出しでもこのエラーが返される場合があります。 | |
| prcDest パラメーターが NULL です。 | |
| 呼び出し元のアプリケーションが、登録済みの IShellImageDataAbort のインスタンスを通じて処理を終了しました。 |
解説(Remarks)
prcSrc が NULL の場合、何も描画されず、メソッドは S_OK を返します。
アニメーション画像の次のフレームに切り替えます。
戻り値
型: HRESULT
成功した場合は S_OK を返し、それ以外の場合は次を含むエラー値を返します。
| 戻り値のコード | 説明 |
|---|---|
| 現在のフレームを取得できません。 | |
| 画像がアニメーションではない、画像がまだデコードされていない、またはアニメーションのループ回数の上限に達しました。 | |
| 次のフレームはまだ利用できません。 | |
|
これ以上のデータは利用できません。 |
複数ページ画像の次のページに切り替えます。関連するアニメーションはリセットされます。
戻り値
型: HRESULT
成功した場合は S_OK を返し、それ以外の場合は次を含むエラー値を返します。
| 戻り値のコード | 説明 |
|---|---|
| 現在のページを取得できません。 | |
| これ以上のページが利用できない、画像が事前にデコードされていない、またはデコード処理が失敗しました。 |
複数ページ画像の前のページに切り替えます。関連するアニメーションはリセットされます。
戻り値
型: HRESULT
成功した場合は S_OK を返し、それ以外の場合は次を含むエラー値を返します。
| 戻り値のコード | 説明 |
|---|---|
| 現在のフレームを取得できません。 | |
| 前のページが利用できない、画像が事前にデコードされていない、またはデコード処理が失敗しました。 |
画像が透過性を持つかどうかを判定します。
戻り値
解説(Remarks)
画像が透過性をサポートしていても使用していない場合、メソッドは S_FALSE を返します。
画像がアニメーションかどうかを判定します。
戻り値
型: HRESULT
次のいずれかを返します。
| 戻り値のコード | 説明 |
|---|---|
| 画像はアニメーションです。 | |
| 画像がアニメーションではない、デコードされていない、またはデコード処理が失敗しました。 |
画像がベクター画像かどうかを判定します。
戻り値
型: HRESULT
次のいずれかを返します。
| 戻り値のコード | 説明 |
|---|---|
| 画像はベクター画像であり、GDI+ フラグ ImageFlagsScalable をサポートしています。 | |
| 画像がデコードされていない、画像が空である、またはファイルが画像ではありません。 | |
| その他すべての場合。 |
画像が複数ページの Tagged Image File Format (TIFF) 画像かどうかを判定します。
戻り値
型: HRESULT
次のいずれかを返します。
| 戻り値のコード | 説明 |
|---|---|
| 画像は複数のページを含みます。 | |
| 画像が 1 ページしかない、画像がデコードされていない、またはデコード処理が失敗しました。 |
画像が編集可能かどうかを判定します。
戻り値
型: HRESULT
次のいずれかを返します。
| 戻り値のコード | 説明 |
|---|---|
| 画像は編集可能です。 | |
| 画像が編集できない、画像がデコードされていない、またはデコード処理が失敗しました。 |
解説(Remarks)
現時点では、画像が編集可能かどうかを判定する基準は、Exif IFD タグが設定された Tagged Image File Format (TIFF) 画像であることのみです。
画像が印刷可能かどうかを判定します。
戻り値
IShellImageData::Decode を呼び出すことによって画像がデコードされたかどうかを判定します。画像が先にデコードされていない場合、多くの操作は失敗コードを返します。
戻り値
複数ページ画像の現在のページを取得します。
| pnPage | DWORD* | inout | ページ番号へのポインター。 |
戻り値
複数ページ画像のページ数を取得します。
| pcPages | DWORD* | inout | ページ数へのポインター。この値はメソッドが S_OK を返す場合にのみ有効です。 |
戻り値
解説(Remarks)
.jpg ファイルなど、画像が複数ページ画像でない場合、メソッドはページ数 1 とともに S_OK を返します。
複数ページ画像内の指定されたページを選択します。
| iPage | DWORD | in | 選択するページのページ番号。 |
戻り値
型: HRESULT
成功した場合は S_OK を返し、それ以外の場合は次を含むエラー値を返します。
| 戻り値のコード | 説明 |
|---|---|
| 現在のページを取得できない、画像がデコードされていない、またはデコード処理が失敗しました。 | |
| 指定されたページ番号は存在しません。 |
画像ファイルの寸法を取得します。
| pSize | SIZE* | inout | 画像のサイズを含む SIZE 構造体へのポインター。この値はメソッドが S_OK を返す場合にのみ有効です。 |
戻り値
画像の形式を識別する GUID を取得します。
| pDataFormat | GUID* | inout | 形式を示す値へのポインター。この値はメソッドが S_OK を返す場合にのみ有効です。 |
戻り値
解説(Remarks)
さまざまなファイル形式を識別する GUID は Gdiplusimaging.h で定義されています。
画像のピクセル形式を取得します。
| pFormat | DWORD* | inout | ピクセル形式を示す PixelFormat 型の値へのポインター。この値はメソッドが S_OK を返す場合にのみ有効です。 |
戻り値
解説(Remarks)
さまざまなピクセル形式を識別する値は Gdipluspixelformats.h で定義されています。
アニメーションの現在のフレームの遅延値を取得します。
| pdwDelay | DWORD* | inout | 遅延値(ミリ秒単位)へのポインター。この値はメソッドが S_OK を返す場合にのみ有効です。 |
戻り値
解説(Remarks)
アニメーション画像では、遅延はフレームごとに異なる場合があります。
このメソッドは最小値として 100 ミリ秒を取得します。この時間より短い値も 100 ミリ秒として報告されます。
画像のプロパティにアクセスするための IPropertySetStorage を取得します。
| dwMode | DWORD | in | 使用されません。0 を設定します。 |
| ppPropSet | IPropertySetStorage** | out | IPropertySetStorage インターフェイスへのポインターのアドレス。 |
戻り値
型: HRESULT
成功した場合は S_OK を返し、それ以外の場合は次を含むエラー値を返します。
| 戻り値のコード | 説明 |
|---|---|
| 画像がデコードされていないか、デコード処理が失敗しました。 | |
| ppPropSet ポインターが無効です。 |
画像を 90 度単位で回転します。
| dwAngle | DWORD | in | 回転角度。0、90、180、270 の角度のみが認識されます。 |
戻り値
型: HRESULT
成功した場合は S_OK を返し、それ以外の場合は次を含むエラー値を返します。
| 戻り値のコード | 説明 |
|---|---|
| 画像がデコードされていないか、デコード処理が失敗しました。この値は、GDI+ メソッドへの特定の内部呼び出しが失敗した場合にも返されます。 | |
| 画像はアニメーション画像であり、回転できません。 | |
| dwAngle パラメーターが 0、90、180、270 以外の値です。 | |
| dwAngle パラメーターが 0 です。 | |
| メソッドが画像の内部作業コピーを作成するのに十分なリソースがありません。 |
画像のサイズを調整します。
| cx | DWORD | in | 水平方向(x)の寸法。この値が 0 の場合、x の寸法は cy で指定された値に基づいて拡大縮小された値に設定されます。 |
| cy | DWORD | in | 垂直方向(y)の寸法。この値が 0 の場合、y の寸法は cx で指定された値に基づいて拡大縮小された値に設定されます。 |
| hints | InterpolationMode | in | 画像を拡大縮小する際に使用されるアルゴリズムを指定する InterpolationMode 列挙型のメンバー。 |
戻り値
型: HRESULT
成功した場合は S_OK を返し、それ以外の場合は次を含むエラー値を返します。
| 戻り値のコード | 説明 |
|---|---|
| 画像が事前にデコードされていないか、IShellImageData::Decode の呼び出しが失敗しました。その他の内部呼び出しでもこのエラーが返される場合があります。 | |
| 画像はアニメーション画像であり、このメソッドでは拡大縮小できません。 | |
| 内部オブジェクトをインスタンス化できません。 | |
| 呼び出し元のアプリケーションが、登録済みの IShellImageDataAbort のインスタンスを通じて処理を停止しました。 |
画像に加えられた編集を破棄します。
戻り値
型: HRESULT
常に S_OK を返します。
エンコーダーのパラメーターを設定します。
| pbagEnc | IPropertyBag* | in | エンコーダーのプロパティを含む IPropertyBag へのポインター。 |
戻り値
型: HRESULT
常に S_OK を返します。
解説(Remarks)
pbagEnc に渡された IPropertyBag は、保存操作中に使用されます。画像および Rotate や Scale などそれに加えられた編集は、IPersistFile または IPersistStream のいずれかに対して QueryInterface を呼び出し、それらの Save メソッドを呼び出すことで保存できます。
IShellImageData がファイルパスで初期化された場合はファイル名を取得します。それ以外の場合はデータストリームの名前を取得します。
| wszName | LPWSTR | in | 表示名を Unicode 文字列として含むバッファーへのポインター。終了時、バッファーの内容はメソッドが S_OK を返す場合にのみ有効です。 |
| cch | DWORD | in | wszName が指すバッファーのサイズ(文字数単位)。 |
戻り値
画像の解像度を 1 インチあたりのドット数(dpi)で取得します。
| puResolutionX | DWORD* | inout | 水平方向の解像度へのポインター。 |
| puResolutionY | DWORD* | inout | 垂直方向の解像度へのポインター。 |
戻り値
型: HRESULT
成功した場合は S_OK を返し、それ以外の場合は次を含むエラー値を返します。
| 戻り値のコード | 説明 |
|---|---|
| 画像がデコードされていない、デコード処理が失敗した、または解像度を取得できません。後者の場合、puResolutionX と puResolutionY の両方が 0 に設定されます。 | |
| puResolutionX と puResolutionY の両方が NULL です。 |
解説(Remarks)
puResolutionX または puResolutionY のいずれかが NULL の場合、メソッドは NULL でない方のパラメーターの値のみを返します。
現在のエンコーダーパラメーターのセットを取得します。
| pguidFmt | GUID* | inout | エンコーダーを指定する GUID へのポインター。これは GDI+ でサポートされているエンコーダーである必要があります。このパラメーターが NULL の場合、ハンドルされない例外が発生します。 |
| ppEncParams | BYTE** | inout | EncoderParameter オブジェクトの配列へのポインターのアドレス。 |
戻り値
型: HRESULT
成功した場合は S_OK を返し、それ以外の場合は次を含むエラー値を返します。
| 戻り値のコード | 説明 |
|---|---|
いくつかの状況でこの戻り値が生成されます。
|
コールバック用の中止オブジェクトを設定し、必要に応じて前のオブジェクトへのポインターを返します。
| pAbort | IShellImageDataAbort* | in | 中止オブジェクトへのポインター。このパラメーターが NULL の場合、ハンドルされない例外が発生します。 |
| ppAbortPrev | IShellImageDataAbort** | out | 前の中止オブジェクトへのポインターのアドレス。前のオブジェクトが不要な場合、このパラメーターは NULL にできます。 |
戻り値
型: HRESULT
成功した場合は S_OK を返し、それ以外の場合はエラー値を返します。
現在の画像またはフレームのクローンを取得します。
| ppImg | BYTE** | inout | クローン画像へのポインターを受け取るアドレス。このパラメーターが入力時に NULL の場合、ハンドルされない例外が発生します。 |
戻り値
型: HRESULT
成功した場合は S_OK を返し、それ以外の場合は次を含むエラー値を返します。
| 戻り値のコード | 説明 |
|---|---|
| ppImg パラメーターが入力時に NULL であるか、画像をクローンできません。後者の場合、ppImg は NULL に設定されます。 |
解説(Remarks)
.gif ファイルなどの複数フレーム画像の場合、現在のフレームがクローンされます。.jpg ファイルなどの複数フレームでない画像の場合、画像全体がクローンされます。
現在のフレームを新しい画像で置き換えます。
| pImg | BYTE* | inout | 新しい画像のアドレス。 |
戻り値
型: HRESULT
常に S_OK を返します。
解説(Remarks)
元の画像の編集済みプロパティが保持されないようにするため、IShellImageData::DiscardEdit も呼び出す必要があります。
.gif ファイルなどの複数フレーム画像の場合、現在のフレームが置き換えられます。.jpg ファイルなどの複数フレームでない画像の場合、画像全体が置き換えられます。
アニメーション .gif ファイルのフレームを置き換えると、そのファイルのアニメーションが機能しなくなります。Tagged Image File Format (TIFF) ファイルのフレームを置き換えると、特に TIFF フレームの画像が元と同じサイズでない場合、そのファイルがページを失う可能性があります。可能な限り、TIFF フレームの画像は常に同じサイズの TIFF で置き換える必要があります。
IShellImageData の実装は pImg で指定された画像の所有権を取得するため、呼び出し元は IShellImageData::ReplaceFrame を呼び出した後にそれを使用しようとしてはなりません。
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 指定が可能。#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,sptr,sptr #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 sptr #comfunc global IShellImageData_GetPageCount 16 sptr #comfunc global IShellImageData_SelectPage 17 int #comfunc global IShellImageData_GetSize 18 sptr #comfunc global IShellImageData_GetRawDataFormat 19 sptr #comfunc global IShellImageData_GetPixelFormat 20 sptr #comfunc global IShellImageData_GetDelay 21 sptr #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 sptr,sptr #comfunc global IShellImageData_GetEncoderParams 29 sptr,sptr #comfunc global IShellImageData_RegisterAbort 30 sptr,sptr #comfunc global IShellImageData_CloneFrame 31 sptr #comfunc global IShellImageData_ReplaceFrame 32 sptr ; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。 ; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。 ; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。 ; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。