SHGetFileInfoA 関数 (shellapi.h)

ファイル、フォルダー、ディレクトリ、ドライブ ルートなど、ファイル システム内のオブジェクトに関する情報を取得します。

構文

DWORD_PTR SHGetFileInfoA(
  [in]      LPCSTR      pszPath,
            DWORD       dwFileAttributes,
  [in, out] SHFILEINFOA *psfi,
            UINT        cbFileInfo,
            UINT        uFlags
);

パラメーター

[in] pszPath

種類: LPCTSTR

パスとファイル名を含む最大長MAX_PATH の null で終わる文字列へのポインター。 絶対パスと相対パスの両方が有効です。

uFlags パラメーターに SHGFI_PIDL フラグが含まれている場合、このパラメーターは、シェルの名前空間内のファイルを一意に識別する項目識別子のリストを含む ITEMIDLIST (PIDL) 構造体のアドレスである必要があります。 PIDL は完全修飾 PIDL である必要があります。 相対 PIDL は使用できません。

uFlags パラメーターに SHGFI_USEFILEATTRIBUTES フラグが含まれている場合、このパラメーターは有効なファイル名である必要はありません。 関数は、指定した名前と dwFileAttributes パラメーターで渡されたファイル属性を持つファイルが存在するかのように処理されます。 これにより、pszPath の拡張子だけを渡し、dwFileAttributesFILE_ATTRIBUTE_NORMALを渡すことで、ファイルの種類に関する情報を取得できます。

この文字列では、short (8.3 形式) または長いファイル名を使用できます。

dwFileAttributes

型: DWORD

1 つ以上の ファイル属性フラグ の組み合わせ (Winnt.h で定義されている値をFILE_ATTRIBUTE_)。 uFlagsSHGFI_USEFILEATTRIBUTES フラグが含まれていない場合、このパラメーターは無視されます。

[in, out] psfi

種類: SHFILEINFO*

ファイル情報を受け取る SHFILEINFO 構造体へのポインター。

cbFileInfo

型: UINT

psfi パラメーターが指す SHFILEINFO 構造体のサイズ (バイト単位)。

uFlags

型: UINT

取得するファイル情報を指定するフラグ。 このパラメーターは、次の値と組み合わせて使用できます。

SHGFI_ADDOVERLAYS (0x000000020)

バージョン 5.0。 ファイルのアイコンに適切なオーバーレイを適用します。 SHGFI_ICON フラグも設定する必要があります。

SHGFI_ATTR_SPECIFIED (0x000020000)

SHGFI_ATTRIBUTESを変更して、psfiSHFILEINFO 構造体の dwAttributes メンバーに必要な特定の属性が含まれていることを示します。 これらの属性は 、IShellFolder::GetAttributesOf に渡されます。 このフラグを指定しない場合、0xFFFFFFFFは IShellFolder::GetAttributesOf に渡され、すべての属性が要求されます。 このフラグは 、SHGFI_ICON フラグでは指定できません。

SHGFI_ATTRIBUTES (0x000000800)

項目属性を取得します。 属性は、psfi パラメーターで指定された構造体の dwAttributes メンバーにコピーされます。 これらは、 IShellFolder::GetAttributesOf から取得されるのと同じ属性です。

SHGFI_DISPLAYNAME (0x000000200)

ファイルの表示名 (Windows エクスプローラーに表示される名前) を取得します。 名前は、psfi で指定された構造体の szDisplayName メンバーにコピーされます。 返される表示名には、ファイル名の 8.3 形式ではなく、長いファイル名 (存在する場合) が使用されます。 表示名は、拡張機能が表示されるかどうかなどの設定によって影響を受ける可能性があることに注意してください。

SHGFI_EXETYPE (0x000002000)

pszPath が実行可能ファイルを識別する場合は、実行可能ファイルの種類を取得します。 情報は戻り値にパックされます。 このフラグを他のフラグと共に指定することはできません。

SHGFI_ICON (0x000000100)

ファイルを表すアイコンへのハンドルと、システム イメージ リスト内のアイコンのインデックスを取得します。 psfi で指定された構造体の hIcon メンバーにハンドルがコピーされ、インデックスが iIcon メンバーにコピーされます。

SHGFI_ICONLOCATION (0x000001000)

ファイルのアイコン ハンドラーの IExtractIcon::GetIconLocation メソッドによって返される、pszPath で指定されたファイルを表すアイコンを含むファイルの名前を取得します。 また、そのファイル内のアイコン インデックスも取得します。 アイコンを含むファイルの名前は、psfi で指定された構造体の szDisplayName メンバーにコピーされます。 アイコンのインデックスは、その構造体の iIcon メンバーにコピーされます。

SHGFI_LARGEICON (0x000000000)

SHGFI_ICONを変更すると、関数はファイルの大きなアイコンを取得します。 SHGFI_ICON フラグも設定する必要があります。

SHGFI_LINKOVERLAY (0x000008000)

SHGFI_ICON変更すると、関数はファイルのアイコンにリンク オーバーレイを追加します。 SHGFI_ICON フラグも設定する必要があります。

SHGFI_OPENICON (0x000000002)

SHGFI_ICON変更すると、関数はファイルの開いているアイコンを取得します。 また、 SHGFI_SYSICONINDEXを変更するためにも使用され、関数はファイルの小さな開いているアイコンを含むシステム イメージ リストにハンドルを返します。 コンテナー オブジェクトには、コンテナーが開かれていることを示す開いているアイコンが表示されます。 SHGFI_ICONフラグまたはSHGFI_SYSICONINDEX フラグも設定する必要があります。

SHGFI_OVERLAYINDEX (0x000000040)

バージョン 5.0。 オーバーレイ アイコンのインデックスを返します。 オーバーレイ インデックスの値は、psfi で指定された構造体の iIcon メンバーの上位 8 ビットで返されます。 このフラグを設定するには、 SHGFI_ICON も設定する必要があります。

SHGFI_PIDL (0x000000008)

pszPath がパス名ではなく ITEMIDLIST 構造体のアドレスであることを示します。

SHGFI_SELECTED (0x000010000)

SHGFI_ICONを変更すると、関数はファイルのアイコンとシステムの強調表示色をブレンドします。 SHGFI_ICON フラグも設定する必要があります。

SHGFI_SHELLICONSIZE (0x000000004)

SHGFI_ICON変更すると、関数はシェル サイズのアイコンを取得します。 このフラグが指定されていない場合、関数はシステム メトリック値に従ってアイコンのサイズを設定します。 SHGFI_ICON フラグも設定する必要があります。

SHGFI_SMALLICON (0x000000001)

SHGFI_ICON変更すると、関数はファイルの小さなアイコンを取得します。 また、 SHGFI_SYSICONINDEXを変更するためにも使用され、関数は小さなアイコン イメージを含むシステム イメージ リストにハンドルを返します。 SHGFI_ICONフラグまたはSHGFI_SYSICONINDEX フラグも設定する必要があります。

SHGFI_SYSICONINDEX (0x000004000)

システム イメージ リスト アイコンのインデックスを取得します。 成功した場合、インデックスは psfiiIcon メンバーにコピーされます。 戻り値は、システム・イメージ・リストへのハンドルです。 インデックスが iIcon に正常にコピーされたイメージのみが有効です。 システム イメージ リスト内の他のイメージにアクセスしようとすると、未定義の動作が発生します。

SHGFI_TYPENAME (0x000000400)

ファイルの型を記述する文字列を取得します。 この文字列は、psfi で指定された構造体の szTypeName メンバーにコピーされます。

SHGFI_USEFILEATTRIBUTES (0x000000010)

関数が pszPath で指定されたファイルへのアクセスを試みないことを示します。 代わりに、 pszPath で指定されたファイルが dwFileAttributes で渡されたファイル属性と共に存在するかのように動作する必要があります。 このフラグは、SHGFI_ATTRIBUTES、SHGFI_EXETYPE、またはSHGFI_PIDLフラグと組み合わせることはできません。

戻り値

種類: DWORD_PTR

uFlags パラメーターに依存する意味を持つ値を返します。

uFlagsSHGFI_EXETYPEまたはSHGFI_SYSICONINDEXが含まれていない場合、戻り値は成功した場合は 0 以外、それ以外の場合は 0 になります。

uFlagsSHGFI_EXETYPE フラグが含まれている場合、戻り値は実行可能ファイルの種類を指定します。 次のいずれかの値になります。

リターン コード 説明
0
実行できないファイルまたはエラー条件。
LOWORD = NE または PE および HIWORD = Windows バージョン
Windows アプリケーション。
LOWORD = MZ および HIWORD = 0
MS-DOS .exe または.com ファイル
LOWORD = PE および HIWORD = 0
コンソール アプリケーションまたは .bat ファイル

注釈

この関数は、バックグラウンド スレッドから呼び出す必要があります。 これを行わないと、UI の応答が停止する可能性があります。

SHGetFileInfopsfi が指す SHFILEINFO 構造体の hIcon メンバーでアイコン ハンドルを返す場合は、不要になったときに DestroyIcon で解放する必要があります。

メモ システム イメージ リストへのハンドルを取得したら、 Image List API を使用して、他のイメージ リストと同様に操作できます。 システム イメージ リストはプロセスごとに作成されるため、読み取り専用オブジェクトとして扱う必要があります。 システム イメージ リストに書き込むと、システム イメージの 1 つが上書きまたは削除され、プロセスの残りの部分で使用できなくなったり、正しくなくなる可能性があります。
 
SHGetFileInfo を呼び出す前に、CoInitialize または OleInitialize を使用してコンポーネント オブジェクト モデル (COM) を初期化する必要があります。

Windows アプリケーションで SHGFI_EXETYPE フラグを使用する場合、Windows バージョンの実行可能ファイルは、戻り値の HIWORD で指定されます。 このバージョンは、16 進数の値として返されます。 この値を特定の Windows バージョンと同一視する方法の詳細については、「 Windows ヘッダーの使用」を参照してください。

次のコード例では 、SHGetFileInfo を使用して、PIDL によって識別されるごみ箱の表示名を取得します。

LPITEMIDLIST pidl = NULL;
hr = SHGetFolderLocation(NULL, CSIDL_BITBUCKET, NULL, 0, &pidl);

if (SUCCEEDED(hr))                    
{
    SHFILEINFOW sfi = {0};
    hr = SHGetFileInfo((LPCTSTR)pidl,
                        -1,
                        &sfi,
                        sizeof(sfi),
                        SHGFI_PIDL | SHGFI_DISPLAYNAME)
            
    if (SUCCEEDED(hr))
    {
        // The display name is now held in sfi.szDisplayName.
    }
}

ILFree(pidl);

注意

shellapi.h ヘッダーは、UNICODE プリプロセッサ定数の定義に基づいて、この関数の ANSI または Unicode バージョンを自動的に選択するエイリアスとして SHGetFileInfo を定義します。 エンコードに依存しないエイリアスをエンコードニュートラルでないコードと組み合わせて使用すると、コンパイルまたはランタイム エラーが発生する不一致が発生する可能性があります。 詳細については、「 関数プロトタイプの規則」を参照してください。

要件

要件
サポートされている最小のクライアント Windows XP (デスクトップ アプリのみ)
サポートされている最小のサーバー Windows 2000 Server [デスクトップ アプリのみ]
対象プラットフォーム Windows
ヘッダー shellapi.h
Library Shell32.lib
[DLL] Shell32.dll (バージョン 4.0 以降)

こちらもご覧ください

FileIconInit