通过

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） 结构的地址，该结构包含唯一标识 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

SHFILEINFO 结构 psfi 参数指向的大小（以字节为单位）。

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。 返回覆盖图标的索引。 覆盖索引的值在由 psfi指定的结构的 iIcon 成员的上八位中返回。 此标志还需要设置 SHGFI_ICON。

SHGFI_PIDL（0x000000008）

指示 pszPath 是 ITEMIDLIST 结构的地址，而不是路径名称。

SHGFI_SELECTED（0x000010000）

修改 SHGFI_ICON，导致函数将文件的图标与系统突出显示颜色混合。 还必须设置 SHGFI_ICON 标志。

SHGFI_SHELLICONSIZE（0x000000004）

修改 SHGFI_ICON，导致函数检索 Shell 大小的图标。 如果未指定此标志，函数将根据系统指标值调整图标的大小。 还必须设置 SHGFI_ICON 标志。

SHGFI_SMALLICON（0x000000001）

修改 SHGFI_ICON，导致函数检索文件的小图标。 还用于修改 SHGFI_SYSICONINDEX，导致函数将句柄返回到包含小图标图像的系统映像列表。 还必须设置 SHGFI_ICON 和/或 SHGFI_SYSICONINDEX 标志。

SHGFI_SYSICONINDEX（0x000004000）

检索系统映像列表图标的索引。 如果成功，索引将复制到 psfi的 iIcon 成员。 返回值是系统映像列表的句柄。 只有成功将索引复制到 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 像处理任何其他图像列表一样对其进行操作。 由于系统映像列表是按进程创建的，因此应将它们视为只读对象。 写入系统映像列表可能会覆盖或删除其中一个系统映像，使其余进程不可用或不正确。
 
在调用 SHGetFileInfo之前，必须使用 CoInitialize 或 OleInitialize 初始化组件对象模型（COM）。

将 SHGFI_EXETYPE 标志用于 Windows 应用程序时，可执行文件的 Windows 版本在返回值的 HIWORD 中提供。 此版本以十六进制值的形式返回。 有关将此值与特定 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