共用方式為

SHGetFileInfoA 函式 （shellapi.h）

  • 發行項

擷取文件系統中對象的相關信息，例如檔案、資料夾、目錄或磁碟驅動器根目錄。

語法

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

參數

[in] pszPath

類型：LPCTSTR

null字串的指標，其長度上限為MAX_PATH，其中包含路徑和檔名。 絕對路徑和相對路徑都是有效的。

如果 uFlags 參數包含 SHGFI_PIDL 旗標，這個參數必須是 ITEMIDLIST （PIDL） 結構的位址，其中包含可唯一識別 Shell 命名空間內檔案的專案標識符清單。 PIDL 必須是完整的 PIDL。 不允許相對 PIDL。

如果 uFlags 參數包含 SHGFI_USEFILEATTRIBUTES 旗標，則此參數不一定是有效的檔名。 函式會繼續，就像檔案存在具有指定名稱，以及傳入 dwFileAttributes 參數的檔案屬性一樣。 這可讓您只傳遞 pszPath 的擴展名，並在 dwFileAttributes中傳遞 FILE_ATTRIBUTE_NORMAL，以取得檔類型的相關信息。

此字串可以使用簡短 （8.3 格式） 或長檔名。

dwFileAttributes

類型：DWORD

一或多個 檔案屬性旗標的組合（如 Winnt.h 中所定義的FILE_ATTRIBUTE_值）。 如果 uFlags 不包含 SHGFI_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，表示 dwAttributesSHFILEINFO 結構的成員，psfi 包含所需的特定屬性。 這些屬性會傳遞至 IShellFolder：：GetAttributesOf。 如果未指定此旗標，0xFFFFFFFF會傳遞至 IShellFolder：：GetAttributesOf，要求所有屬性。 無法使用 SHGFI_ICON 旗標來指定此旗標。

SHGFI_ATTRIBUTES（0x000000800）

擷取項目屬性。 屬性會複製到 dwAttributespsfi 參數中指定的結構成員。 這些是從 IShellFolder：：GetAttributesOf取得的相同屬性。

SHGFI_DISPLAYNAME （0x000000200）

擷取檔案的顯示名稱，也就是 Windows 檔案總管中顯示的名稱。 名稱會複製到 szDisplayNamepsfi中指定的結構成員。 傳回的顯示名稱會使用長檔名，如果有一個，而不是檔名的 8.3 格式。 請注意，顯示名稱可能會受到設定的影響，例如是否顯示延伸模組。

SHGFI_EXETYPE（0x000002000）

如果 pszPath 識別可執行檔，則擷取可執行檔的類型。 資訊會封裝到傳回值中。 這個旗標不能以任何其他旗標指定。

SHGFI_ICON （0x000000100）

擷取代表系統映射清單中圖示的檔案和索引的圖示句柄。 句柄會複製到由 psfi所指定結構的 hIcon 成員，而索引會複製到 iIcon 成員 。

SHGFI_ICONLOCATION（0x000001000）

擷取包含 pszPath所指定之檔案之圖標的檔名，如檔案圖示處理程式的 IExtractIcon：：GetIconLocation 方法所傳回。 同時擷取該檔案內的圖示索引。 包含圖示的檔名會複製到由 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 版。 傳回重迭圖示的索引。 重疊索引的值會傳回 iIcon 結構 psfi所指定之結構的八位。 此旗標也需要設定 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）

擷取描述檔案類型的字串。 字串會複製到 szTypeNamepsfi中指定的結構成員。

SHGFI_USEFILEATTRIBUTES （0x000000010）

表示函式不應該嘗試存取 pszPath 所指定的檔案。 相反地，它應該就像 pszPath 所指定的檔案 存在於 dwFileAttributes中傳遞的檔案屬性一樣。 這個旗標無法與 SHGFI_ATTRIBUTES、SHGFI_EXETYPE或 SHGFI_PIDL 旗標結合。

傳回值

類型：DWORD_PTR

傳回值，其意義取決於 uFlags 參數。

如果 uFlags 不包含 SHGFI_EXETYPE 或 SHGFI_SYSICONINDEX，則如果成功，則傳回值為非零，否則為零。

如果 uFlags 包含 SHGFI_EXETYPE 旗標，則傳回值會指定可執行文件的類型。 這將是下列其中一個值。

傳回碼 描述
0
 不可執行的檔案或錯誤條件。
LOWORD = NE 或 PE 和 HIWORD = Windows 版本
 Windows 應用程式。
LOWORD = MZ，HIWORD = 0
 MS-DOS .exe 或.com檔案
LOWORD = PE 和 HIWORD = 0
 主控台應用程式或 .bat 檔案

言論

您應該從背景線程呼叫此函式。 若無法這麼做，可能會導致UI停止回應。

如果 SHGetFileInfo 傳回 hIconSHFILEINFO 結構中由 psfi所指向的圖示句柄，則您必須負責在不再需要時，將它釋放 DestroyIcon。

注意 一旦您有系統映射清單的句柄，您可以使用 映射清單 API 來操作它，就像任何其他影像清單一樣。 因為系統會根據每個進程建立系統映像清單，因此您應該將它們視為唯讀物件。 寫入系統映像清單可能會覆寫或刪除其中一個系統映像，使得其餘程式無法使用或不正確。
 
您必須使用 CoInitialize 或 OleInitialize 初始化元件物件模型 （COM），才能呼叫 SHGetFileInfo。

當您搭配 Windows 應用程式使用 SHGFI_EXETYPE 旗標時，傳回值的 HIWORD 中會提供可執行檔的 Windows 版本。 此版本會以十六進位值的形式傳回。 如需將此值與特定 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 標頭會將SHGetFileInfo定義為別名，根據UNICODE預處理器常數的定義，自動選取此函式的ANSI或 Unicode 版本。 混合使用編碼中性別名與非編碼中性的程序代碼，可能會導致編譯或運行時間錯誤不符。 如需詳細資訊，請參閱函式原型的 慣例。

要求

要求 價值
最低支援的用戶端 Windows XP [僅限傳統型應用程式]
支援的最低伺服器 Windows 2000 Server [僅限傳統型應用程式]
目標平臺 窗戶
標頭 shellapi.h
連結庫 Shell32.lib
DLL Shell32.dll 版（4.0 版或更新版本）

另請參閱

FileIconInit