SHGetFileInfo函数

SHGetFileInfo Function

Retrieves information about an object in the file system, such as a file, folder, directory, or drive root.
获得一个文件系统对象的信息，如一个文件、文件夹、目录或者根驱动器等的信息
语法(Syntax)
DWORD_PTR SHGetFileInfo(
LPCTSTRpszPath,
DWORDdwFileAttributes,
SHFILEINFO *psfi,
UINTcbFileInfo,
UINTuFlags);
参数(Parameters)
pszPath
pszPath
[in] A pointer to a null-terminated string of maximum length MAX_PATH that contains the path and file name. Both absolute and relative paths are valid.
指向一个以NULL结尾且最大长度不超过MAX_PATH字符串的指针，这个字符串包含文件名及其路径。绝对路径和相对路径都是有效的。
If theuFlagsparameter includes theSHGFI_PIDLflag, this parameter must be the address of anITEMIDLIST(PIDL) structure that contains the list of item identifiers that uniquely identifies the file within the Shell's namespace. The pointer to an item identifier list (PIDL) must be a fully qualified PIDL. Relative PIDLs are not allowed.
如果uflags参数为SHGFI_PIDL，那么这个参数必须是ITEMIDLIST(PIDL)结构体的一个地址，ITEMIDLIST(PIDL)结构是在Shell命名空间内唯一标示文件的列表项。这时，PIDL结构体标识的必须是文件的绝对路径，相对路径则不允许
If theuFlagsparameter includes theSHGFI_USEFILEATTRIBUTESflag, this parameter does not have to be a valid file name. The function will proceed as if the file exists with the specified name and with the file attributes passed in thedwFileAttributesparameter. This allows you to obtain information about a file type by passing just the extension forpszPathand passingFILE_ATTRIBUTE_NORMALindwFileAttributes.
This string can use either short (the 8.3 form) or long file names.
如果uflags参数的值包含SHGFI_USEFILEATTRIBUTES，那么这个参数不必必须是一个有效的文件名。那么该函数将继续通过dwFileAttributes 参数来确定指定的文件名及其属性是否有效。这就使得你扩展pszPath参数通过dwFileAttributes 参数的FILE_ATTRIBUTE_NORMAL
这个字符串可以使用短（8.3形式）或长的文件名
dwFileAttributes
[in] A combination of one or morefile attribute flags(FILE_ATTRIBUTE_ values as defined in Winnt.h). IfuFlagsdoes not include theSHGFI_USEFILEATTRIBUTESflag, this parameter is ignored.
一个或多个文件属性标志(file attribute flags)(FILE_ATTRIBUTE 的值定义在Winnt.h中)，如果uFlags参数不是SHGFI_USEFILEATTRIBUTES，那这个参数可以忽略。
psfi
[out] The address of aSHFILEINFOstructure to receive the file information.
指向SHFILEINFO结构体用以接收文件信息的指针。
cbFileInfo
[in] The size, in bytes, of theSHFILEINFOstructure pointed to by thepsfiparameter.
psfi参数指向的SHFILEINFO结构体的大小(以字节为单位)
uFlags
[in] The flags that specify the file information to retrieve. This parameter can be a combination of the following values.
指定要获文件信息的标志。这个参数可以和下面在这些值进行组合。
SHGFI_ADDOVERLAYS
Version 5.0. Apply the appropriate overlays to the file's icon. TheSHGFI_ICONflag must also be set.
5.0版本，提供适当的覆盖文件的图标，和SHGFI_ICON标示一起设置使用。
SHGFI_ATTR_SPECIFIED
ModifySHGFI_ATTRIBUTESto indicate that thedwAttributesmember of theSHFILEINFOstructure atpsficontains the specific attributes that are desired.
These attributes are passed toIShellFolder::GetAttributesOf. If this flag is not specified, 0xFFFFFFFF is passed toIShellFolder::GetAttributesOf,
requesting all attributes. This flag cannot be specified with theSHGFI_ICONflag.
修改SHGFI_ATTRIBUTES以表明dwAttributes 的成员psfi(SHFILEINFO结构体)包含特别指定的属性。这些属性传递给IShellFolder::GetAttributesOf函数。如果这个标志未被指定，0xFFFFFFFF传递给IShellFolder::GetAttributesOf，要求获得所有属性，这个标志不能和SHGFI_ICN 一起使用。
SHGFI_ATTRIBUTES
Retrieve the item attributes. The attributes are copied to thedwAttributesmember of the structure specified in thepsfiparameter.
These are the same attributes that are obtained fromIShellFolder::GetAttributesOf.
获得条目的属性，这个属性被复制到dwAttributes的成员参数psfi结构体中，这和IShellFolder::GetAttributesOf.获得的熟悉是相同的。
SHGFI_DISPLAYNAME
Retrieve the display name for the file. The name is copied to theszDisplayNamemember of the structure specified inpsfi.
The returned display name uses the long file name, if there is one, rather than the 8.3 form of the file name.
获得文件的显示名称，该名称被复制到psfi结构体所指的szDisplayName，如果有一个长文件名，那么就返回它，而不是8.3形式的短文件名。
SHGFI_EXETYPE
Retrieve the type of the executable file ifpszPathidentifies an executable file. The information is packed into the return value.
This flag cannot be specified with any other flags.
如果pszPath标识了一个可执行文件名，则返回可执行文件名，该文件的信息则被封装到返回值中，这个标志不能被任何其他标志所指定。
SHGFI_ICON
Retrieve the handle to the icon that represents the file and the index of the icon within the system image list.
The handle is copied to thehIconmember of the structure specified bypsfi, and the index is copied to theiIconmember.
获得图标代表的文件的句柄和系统图像列表中图标的索引，图标句柄则复制到psfi结构所指的hIcon成员中，索引则被复制到iIcon成员中
SHGFI_ICONLOCATION
Retrieve the name of the file that contains the icon representing the file specified bypszPath,
as returned by theIExtractIcon::GetIconLocationmethod of the file's icon handler. Also retrieve the icon index within that file.
The name of the file containing the icon is copied to theszDisplayNamemember of the structure specified bypsfi.
The icon's index is copied to that structure'siIconmember.
获得由pszPath指定的图标代表的文件的文件名，并通过图标句柄由IExtractIcon::GetIconLocation方法返回，同时也获得在文件中的图标索引。 包含图标的文件名被复制到由psfi结构所指的szDisplayName成员中 ，图标索引则复制到结构体成员的iIcon成员中
SHGFI_LARGEICON
ModifySHGFI_ICON, causing the function to retrieve the file's large icon. TheSHGFI_ICONflag must also be set.
与SHGFI_ICON 一起使用，修改SHGFI_ICON使得函数获得文件的大图标。
SHGFI_LINKOVERLAY
Modify SHGFI_ICON, causing the function to add the link overlay to the file's icon. TheSHGFI_ICONflag must also be set.
与SHGFI_ICON 一起使用，修改SHGFI_ICON 使得函数怎加链接覆盖文件的图标。
SHGFI_OPENICON
Modify SHGFI_ICON, causing the function to retrieve the file's open icon. Also used to modifySHGFI_SYSICONINDEX,
causing the function to return the handle to the system image list that contains the file's small open icon.
A container object displays an open icon to indicate that the container is open.
TheSHGFI_ICONand/orSHGFI_SYSICONINDEXflag must also be set.
与SHGFI_ICON 或者和SHGFI_SYSICONINDEX 一起使用，修改SHGFI_ICON，获得系统图像索引下文件打开的小图标的句柄，一个容器对象显示一个表示打开的图标以表明该容器是打开的。

SHGFI_OVERLAYINDEX
Version 5.0. Return the index of the overlay icon. The value of the overlay index is returned in the upper eight bits of
theiIconmember of the structure specified bypsfi. This flag requires that theSHGFI_ICONbe set as well.
版本5.0. 与SHGFI_ICON 一起使用，返回覆盖图标的索引，返回值由psfi结构所指的iIcon成员的高8位来指定。

SHGFI_PIDL
Indicate that pszPath is the address of anITEMIDLIST structure rather than a path name.
表明pszPath是一个ITEMIDLIST结构的地址，而不是一个路径名。

SHGFI_SELECTED
Modify SHGFI_ICON, causing the function to blend the file's icon with the system highlight color.
TheSHGFI_ICONflag must also be set.
必须和SHGFI_ICON 一起使用 ，可以是使系统文件图标颜色高亮。

SHGFI_SHELLICONSIZE
Modify SHGFI_ICON, causing the function to retrieve a Shell-sized icon. If this flag is not specified the function sizes the icon according to the system metric values.
TheSHGFI_ICONflag must also be set.
必须和SHGFI_ICON 一起使用 ，修改SHGFI_ICON 获得外壳大小的图标，如果没有指定这个标志，则函数依照系统度量值获得图标的尺寸大小。

SHGFI_SMALLICON
Modify SHGFI_ICON, causing the function to retrieve the file's small icon. Also used to modifySHGFI_SYSICONINDEX,
causing the function to return the handle to the system image list that contains small icon images.
TheSHGFI_ICONand/orSHGFI_SYSICONINDEXflag must also be set.
必须和SHGFI_ICON 或者和SHGFI_SYSICONINDEX 一起使用 ，修改SHGFI_ICON ，是函数获得文件的小图标; 也常常用来修饰SHGFI_SYSICONINDEX ，使函数返回系统映像中包含小图像的句柄。
SHGFI_SYSICONINDEX
Retrieve the index of a system image list icon. If successful, the index is copied to theiIconmember ofpsfi.
The return value is a handle to the system image list. Only those images whose indices are successfully copied toiIconare valid.
Attempting to access other images in the system image list will result in undefined behavior.
获得系统映像的索引列表图标，如果成功，索引将被复制到psfi结构的iIcon成员中，返回值是系统映像列表的句柄，只有成功复制到iIcon成员中值才是有效的。任何尝试访问其他列表的都将引起不确定的行为。
SHGFI_TYPENAME
Retrieve the string that describes the file's type. The string is copied to theszTypeNamemember of the structure specified inpsfi.
返回描述文件类型的字符串，该字符串复制到psfi结构的szTypeName 成员中。
SHGFI_USEFILEATTRIBUTES
Indicates that the function should not attempt to access the file specified bypszPath. Rather, it should act as if the file specified by
pszPath exists with the file attributes passed indwFileAttributes. This flag cannot be combined with theSHGFI_ATTRIBUTES,SHGFI_EXETYPE,
orSHGFI_PIDLflags.
指示函数不应该访问由pszPath指定的文件，相反，如果pszPath文件指定的属性存在的话，它指示其将该属性传递给dwFileAttributes ，这个标志不能和SHGFI_ATTRIBUTES,SHGFI_EXETYPE,或者SHGFI_PIDL一起被使用。
返回值(Return Value)
Returns a value whose meaning depends on theuFlagsparameter.
If uFlags does not contain SHGFI_EXETYPE or SHGFI_SYSICONINDEX, the return value is nonzero if successful, or zero otherwise.
If uFlags contains the SHGFI_EXETYPE flag, the return value specifies the type of the executable file. It will be one of the following values.
返回一个值，其具体含义由uFlags参数来指定。
如果uFlags不包含SHGFI_EXETYPE或者SHGFI_SYSICONINDEX，成功则返回0，反之，返回非0.
如果uFlags包含SHGFI_EXETYPE ，则返回值指定了执行文件的类型，返回值为下面值之一：


(备注)Remarks
If SHGetFileInfo returns an icon handle in thehIcon member of the SHFILEINFO structure pointed to bypsfi, you are responsible for freeing it withDestroyIconwhen you no longer need it.
如果SHGetFileInfo 返回由psfi结构指定的hIcon成员的图标句柄，那么当你不需要该句柄时，你需要用DestroyIcon函数去手动释放它
Note Once you have a handle to a system image list, you can use theImage List APIto manipulate it like any other image list.
Because system image lists are created on a per-process basis, you should treat them as read-only objects. Writing to a system image list may overwrite or delete one of the system images,
making it unavailable or incorrect for the remainder of the process.
You must initialize Component Object Model (COM) withCoInitializeorOleInitializeprior to calling HGetFileInfo.
When you use theSHGFI_EXETYPEflag with a Windows application, the Windows version of the executable is given
in the HIWORD of the return value.
This version is returned as a hexidecimal value. For details on equating this value with a specific Windows version,
seeUsing the SDK Headers.
Windows 95,Windows 98,Windows Millennium Edition (Windows Me):SHGetFileInfois supported by the Microsoft Layer for Unicode (MSLU).
To use this, you must add certain files to your application,
as outlined inMicrosoft Layer for Unicode on Windows Me/98/95 Systems.
注意：当你获得了系统映像列表的一个句柄时，你可以像操作任何系统图像列表一样使用Image List API 来操作它，你应该把他们当做只读对象，写入映像列表可能会覆盖或者删除系统图像，从而引起其他处理过程不可用或出错。
你必须在使用CoInitialize或者OleInitialize函数来初始化COM组件对象模型前，调用HGetFileInfo
当你在一个Windows应用程序中使用SHGFI_EXETYPE标志时，Windows的可执行版本以HIWORD形式返回值。这个值为16进制的。该值与特定的Windows版本的详细信息，请参阅：
Windows 95,Windows 98,Windows Me的SHGetFileInfo的由MSLU来支持Unicode 编码，要使用它，你必须添加特定的文件到您的应用程序，如微软的Unicode Windows Me/98/95的系统的概述。
举例（Example）
The following code example usesSHGetFileInfoto retrieve the display name of the Recycle Bin, identified by its PIDL.
Show Example
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);
函数信息(Function Information)
如有错误，请见谅!!!!!