IExtractImage::GetLocation メソッド (shobjidl_core.h)

  • [アーティクル]

抽出するイメージへのパスを取得します。

構文

HRESULT GetLocation(
  [out]     LPWSTR     pszPathBuffer,
  [in]      DWORD      cch,
  [out]     DWORD      *pdwPriority,
  [in]      const SIZE *prgSize,
  [in]      DWORD      dwRecClrDepth,
  [in, out] DWORD      *pdwFlags
);

パラメーター

[out] pszPathBuffer

種類: LPWSTR

パスの説明を返すために使用されるバッファー。 この値によってイメージが識別されるため、同じイメージを複数回読み込むのを回避できます。

[in] cch

型: DWORD

文字単位の pszPathBuffer のサイズ。

[out] pdwPriority

種類: DWORD*

使用されていません。

Microsoft Windows XP 以前:pdwFlags でIEIFLAG_ASYNC フラグが設定されている場合に、項目の優先度を返すために使用されるポインター。 このパラメーターは NULL にすることはできません。 このパラメーターが NULL の場合、 IEIFLAG_ASYNC フラグが設定されているかどうかに関係なく、関数は失敗します。

このパラメーターは、通常、イメージの抽出に必要な時間を示すために使用されます。 サムネイルの抽出順序をより細かく制御する場合は、最大 32 ビットの複数の優先度レベルを定義できます。 異なる優先度レベルに割り当てられた整数値が低い優先度から高い優先度に増加する限り、実際に使用する数値は重要になりません。 これらは、画像を抽出する順序を決定するためにのみ使用されます。 次の 3 つの標準優先度レベルがあります。

IEI_PRIORITY_MAX

最大優先度。

IEI_PRIORITY_MIN

最小優先度。

IEIT_PRIORITY_NORMAL

通常の優先度。

Microsoft Windows XP。 使用されていません。

[in] prgSize

型: const SIZE*

イメージの幅と高さが必要な SIZE 構造体へのポインター。 NULL にすることはできません。

[in] dwRecClrDepth

型: DWORD

推奨される色深度 (ピクセルあたりのビット単位)。 NULL にすることはできません。

[in, out] pdwFlags

種類: DWORD*

イメージの処理方法を指定するフラグ。 値は、次の 1 つ以上である必要があります。

IEIFLAG_ASPECT

指定された縦横比を使用するようにオブジェクトに要求するために使用されます。 このフラグを設定すると、必要な縦横比を持つ四角形が prgSize で渡されます。 このフラグは 、IEIFLAG_SCREENでは使用できません。

IEIFLAG_ASYNC

使用されていません。 サムネイルは常にバックグラウンド スレッドで抽出されます。

Microsoft Windows XP 以前。 このインスタンスが非同期 (フリースレッド) 抽出をサポートしているかどうかを確認するために使用されます。 呼び出し元のアプリケーションによってこのフラグが設定されている場合、 IExtractImage::GetLocation は 、呼び出し元のアプリケーションに別のスレッドでイメージを抽出することを示すE_PENDINGを返す場合があります。 E_PENDINGが返された場合、項目の優先度は pdwPriority で返されます。

IEIFLAG_CACHE

サポートされていません。

Windows XP 以前: イメージをキャッシュしないことを示す オブジェクトによって設定されます。 このフラグが返された場合、シェルはイメージのコピーをキャッシュします。

IEIFLAG_GLEAM

サポートされていません。

IEIFLAG_NOBORDER (0x0100)

サポートされていません。

IEIFLAG_NOSTAMP (0x0080)

サポートされていません。

IEIFLAG_OFFLINE

レンダリングにローカル コンテンツのみを使用するようにオブジェクトに指示するために使用されます。

IEIFLAG_ORIGSIZE

バージョン 5.0。 prgSize で渡されたおおよそのサイズにイメージをレンダリングするようにオブジェクトに指示するために使用しますが、必要に応じてトリミングします。

IEIFLAG_QUALITY (0x0200)

高品質のイメージが要求されることを示すために 、IExtractImage::Extract メソッドに渡されます。

このフラグが設定されていない場合、 IExtractImage は、ユーザーが要求したサイズに関係なく、ファイルにサムネイルが埋め込まれている場合に取得します。 たとえば、ファイルが 2000 x 2000 ピクセルで、埋め込みサムネイルが 100 x 100 ピクセルのみで、ユーザーがこのフラグを設定していないのに 1000 x 1000 ピクセルのサムネイルを要求している場合、 IExtractImage は常に 100 x 100 ピクセルのサムネイルを返します。 これは仕様上、 IExtractImage はスケールアップしないためです。 大きなサムネイルが必要な場合 (通常、埋め込みサムネイルは 160 x 160)、このフラグを設定する必要があります。

IEIFLAG_REFRESH (0x0400)

アイテムのショートカット メニューに [サムネイルの更新] を表示する必要があることを示すために、 オブジェクトによって返されます。

IEIFLAG_SCREEN

画面の場合と同様にレンダリングするようにオブジェクトに指示するために使用されます。 このフラグは 、IEIFLAG_ASPECTでは使用できません。

戻り値

種類: HRESULT

このメソッドは、COM 定義のエラー コードまたは次のいずれかを返す場合があります。

リターン コード 説明
S_OK
 Success
E_PENDING
 Windows XP 以前:IEIFLAG_ASYNC フラグが設定されている場合、この戻り値は、オブジェクトがフリー スレッドであることをシェルに示すために使用されます。

解説

Microsoft Windows XP 以前: このメソッドは、イメージへのパスを返し、イメージのレンダリング方法を指定します。 IExtractImage::GetLocation はフリー スレッドです。つまり、マルチスレッド アパートメント モデル (MTA) をサポートしているため、バックグラウンド スレッドに配置できます。 呼び出し元のアプリケーションが必要に応じて抽出プロセスを開始および停止できるように、オブジェクトは IRunnableTask インターフェイスも公開する必要があります。

prgSize によって定義された境界内に収まるイメージを返す必要があります。 Windows 2000 以降のシステムでは、標準の縦横比を持たないオブジェクトを使用するように IEIFLAG_ORIGSIZE を設定でき、正しく表示されます。 四角形の未使用の部分を入力する必要はありません。 以前のバージョンのシェルで標準外の縦横比イメージを使用しようとすると、 prgSize 四角形に合わせてストレッチされます。 縦横比が指定されたものとどの程度異なるかによって、画像が不適切に歪む可能性があります。

要件

   
サポートされている最小のクライアント Windows 2000 Professional、Windows XP [デスクトップ アプリのみ]
サポートされている最小のサーバー Windows Server 2003 (デスクトップ アプリのみ)
対象プラットフォーム Windows
ヘッダー shobjidl_core.h (Shobjidl.h を含む)
[DLL] Shell32.dll (バージョン 4.70 以降)