shGetFileInfoW 函数 (shellapi.h)

项目
03/01/2024

检索有关文件系统中的对象的信息，例如文件、文件夹、目录或驱动器根目录。

语法

DWORD_PTR SHGetFileInfoW(
  [in]      LPCWSTR     pszPath,
            DWORD       dwFileAttributes,
  [in, out] SHFILEINFOW *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，使函数检索 Shell 大小的图标。如果未指定此标志，函数将根据系统指标值调整图标大小。还必须设置 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 像任何其他图像列表一样对其进行操作。由于系统映像列表是按进程创建的，因此应将它们视为只读对象。写入系统映像列表可能会覆盖或删除其中一个系统映像，使其在过程的其余部分不可用或不正确。

在调用 SHGetFileInfo 之前，必须使用 CoInitialize 或 OleInitialize (COM) 初始化组件对象模型。

将 SHGFI_EXETYPE 标志用于 Windows 应用程序时，将在返回值的 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
Library	Shell32.lib
DLL	Shell32.dll (4.0 或更高版本)

另请参阅

FileIconInit