SHGetFileInfoA 函式 (shellapi.h)

發行項
03/05/2024

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

語法

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) 結構的位址，其中包含唯一識別 Shell 命名空間內檔案的專案標識符清單。 PIDL 必須是完整的 PIDL。不允許相對 PIDL。

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

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

dwFileAttributes

類型： DWORD

一或多個檔案屬性旗標的組合 (FILE_ATTRIBUTE_ 值，如 Winnt.h) 中所定義。如果 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，指出 psfi 上 SHFILEINFO 結構的 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)

擷取包含 代表 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 版。傳回重迭圖示的索引。重疊索引的值會傳回 psfi 所指定結構之 iIcon 成員的上八位。此旗標也需要設定 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)

擷取系統映射清單圖示的索引。如果成功，索引會複製到 psfi 的 iIcon 成員。傳回值是系統映像清單的句柄。只有成功將索引複製到 iIcon 的影像才有效。嘗試存取系統映像清單中的其他映像會導致未定義的行為。

SHGFI_TYPENAME (0x000000400)

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

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 在 psfi 所指向之 SHFILEINFO 結構的 hIcon 成員中傳回圖示句柄，則當您不再需要時，您必須負責將它與 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 [僅限桌面應用程式]
目標平台	Windows
標頭	shellapi.h
程式庫	Shell32.lib
Dll	Shell32.dll (4.0 版或更新版本)

另請參閱

FileIconInit

共用方式為