Home Library Learn Downloads Support Community
Sign in | United States - English | |
3 out of 12 rated this helpful - Rate this topic

SHGetFileInfo function

Applies to: desktop apps only

Retrieves information about an object in the file system, such as a file, folder, directory, or drive root.

Syntax

Copy 
DWORD_PTR SHGetFileInfo(
  __in     LPCTSTR pszPath,
  DWORD dwFileAttributes,
  __inout  SHFILEINFO *psfi,
  UINT cbFileInfo,
  UINT uFlags
);

Parameters

pszPath [in]

Type: LPCTSTR

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.

If the uFlags parameter includes the SHGFI_PIDL flag, this parameter must be the address of an ITEMIDLIST (PIDL) structure that contains the list of item identifiers that uniquely identifies the file within the Shell's namespace. The PIDL must be a fully qualified PIDL. Relative PIDLs are not allowed.

If the uFlags parameter includes the SHGFI_USEFILEATTRIBUTES flag, 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 the dwFileAttributes parameter. This allows you to obtain information about a file type by passing just the extension for pszPath and passing FILE_ATTRIBUTE_NORMAL in dwFileAttributes.

This string can use either short (the 8.3 form) or long file names.

dwFileAttributes

Type: DWORD

A combination of one or more file attribute flags (FILE_ATTRIBUTE_ values as defined in Winnt.h). If uFlags does not include the SHGFI_USEFILEATTRIBUTES flag, this parameter is ignored.

psfi [in, out]

Type: SHFILEINFO*

Pointer to a SHFILEINFO structure to receive the file information.

cbFileInfo

Type: UINT

The size, in bytes, of the SHFILEINFO structure pointed to by the psfi parameter.

uFlags

Type: UINT

The flags that specify the file information to retrieve. This parameter can be a combination of the following values.

SHGFI_ADDOVERLAYS (0x000000020)

Version 5.0. Apply the appropriate overlays to the file's icon. The SHGFI_ICON flag must also be set.

SHGFI_ATTR_SPECIFIED (0x000020000)

Modify SHGFI_ATTRIBUTES to indicate that the dwAttributes member of the SHFILEINFO structure at psfi contains the specific attributes that are desired. These attributes are passed to IShellFolder::GetAttributesOf. If this flag is not specified, 0xFFFFFFFF is passed to IShellFolder::GetAttributesOf, requesting all attributes. This flag cannot be specified with the SHGFI_ICON flag.

SHGFI_ATTRIBUTES (0x000000800)

Retrieve the item attributes. The attributes are copied to the dwAttributes member of the structure specified in the psfi parameter. These are the same attributes that are obtained from IShellFolder::GetAttributesOf.

SHGFI_DISPLAYNAME (0x000000200)

Retrieve the display name for the file. The name is copied to the szDisplayName member of the structure specified in psfi. The returned display name uses the long file name, if there is one, rather than the 8.3 form of the file name.

SHGFI_EXETYPE (0x000002000)

Retrieve the type of the executable file if pszPath identifies an executable file. The information is packed into the return value. This flag cannot be specified with any other flags.

SHGFI_ICON (0x000000100)

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 the hIcon member of the structure specified by psfi, and the index is copied to the iIcon member.

SHGFI_ICONLOCATION (0x000001000)

Retrieve the name of the file that contains the icon representing the file specified by pszPath, as returned by the IExtractIcon::GetIconLocation method 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 the szDisplayName member of the structure specified by psfi. The icon's index is copied to that structure's iIcon member.

SHGFI_LARGEICON (0x000000000)

Modify SHGFI_ICON, causing the function to retrieve the file's large icon. The SHGFI_ICON flag must also be set.

SHGFI_LINKOVERLAY (0x000008000)

Modify SHGFI_ICON, causing the function to add the link overlay to the file's icon. The SHGFI_ICON flag must also be set.

SHGFI_OPENICON (0x000000002)

Modify SHGFI_ICON, causing the function to retrieve the file's open icon. Also used to modify SHGFI_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. The SHGFI_ICON and/or SHGFI_SYSICONINDEX flag must also be set.

SHGFI_OVERLAYINDEX (0x000000040)

Version 5.0. Return the index of the overlay icon. The value of the overlay index is returned in the upper eight bits of the iIcon member of the structure specified by psfi. This flag requires that the SHGFI_ICON be set as well.

SHGFI_PIDL (0x000000008)

Indicate that pszPath is the address of an ITEMIDLIST structure rather than a path name.

SHGFI_SELECTED (0x000010000)

Modify SHGFI_ICON, causing the function to blend the file's icon with the system highlight color. The SHGFI_ICON flag must also be set.

SHGFI_SHELLICONSIZE (0x000000004)

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. The SHGFI_ICON flag must also be set.

SHGFI_SMALLICON (0x000000001)

Modify SHGFI_ICON, causing the function to retrieve the file's small icon. Also used to modify SHGFI_SYSICONINDEX, causing the function to return the handle to the system image list that contains small icon images. The SHGFI_ICON and/or SHGFI_SYSICONINDEX flag must also be set.

SHGFI_SYSICONINDEX (0x000004000)

Retrieve the index of a system image list icon. If successful, the index is copied to the iIcon member of psfi. The return value is a handle to the system image list. Only those images whose indices are successfully copied to iIcon are valid. Attempting to access other images in the system image list will result in undefined behavior.

SHGFI_TYPENAME (0x000000400)

Retrieve the string that describes the file's type. The string is copied to the szTypeName member of the structure specified in psfi.

SHGFI_USEFILEATTRIBUTES (0x000000010)

Indicates that the function should not attempt to access the file specified by pszPath. Rather, it should act as if the file specified by pszPath exists with the file attributes passed in dwFileAttributes. This flag cannot be combined with the SHGFI_ATTRIBUTES, SHGFI_EXETYPE, or SHGFI_PIDL flags.

Return value

Type: DWORD_PTR

Returns a value whose meaning depends on the uFlags parameter.

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.

Return codeDescription
0

Nonexecutable file or an error condition.

LOWORD = NE or PE and HIWORD = Windows version

Windows application.

LOWORD = MZ and HIWORD = 0

MS-DOS .exe or .com file

LOWORD = PE and HIWORD = 0

Console application or .bat file

 

Remarks

You should call this function from a background thread. Failure to do so could cause the UI to stop responding.

If SHGetFileInfo returns an icon handle in the hIcon member of the SHFILEINFO structure pointed to by psfi, you are responsible for freeing it with DestroyIcon when you no longer need it.

Note  Once you have a handle to a system image list, you can use the Image List API to 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) with CoInitialize or OleInitialize prior to calling SHGetFileInfo.

When you use the SHGFI_EXETYPE flag 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 hexadecimal value. For details on equating this value with a specific Windows version, see Using the Windows Headers.

Examples

The following code example uses SHGetFileInfo to retrieve the display name of the Recycle Bin, identified by its PIDL.

Copy 

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);

Requirements

Minimum supported client

Windows XP

Minimum supported server

Windows 2000 Server

Header
Shellapi.h

Library
Shell32.lib

DLL
Shell32.dll (version 4.0 or later)

Unicode and ANSI names

SHGetFileInfoW (Unicode) and SHGetFileInfoA (ANSI)

See also

FileIconInit

 

 

Send comments about this topic to Microsoft

Build date: 3/7/2012

Did you find this helpful?
(1500 characters remaining)
Community Content Add
Annotations FAQ
Only MAX_PATH support
pszPath [in] Type: LPCTSTR, A pointer to a null-terminated string of maximum length MAX_PATH Will there ever be a UNICODE (> MAX_PATH) support for this?
History
C#

[DllImport("shell32.dll", CharSet = CharSet.Auto)]
public static extern IntPtr SHGetFileInfo(string pszPath, uint dwFileAttributes, ref Win32.SHFILEINFO psfi, uint cbFileInfo, uint uFlags);

[StructLayout(LayoutKind.Sequential, CharSet = CharSet.Auto)]
    public struct SHFILEINFO
        {
            public IntPtr hIcon;
            public int iIcon;
            public uint dwAttributes;
            [MarshalAs(UnmanagedType.ByValTStr, SizeConst = 260)]
            public string szDisplayName;
            [MarshalAs(UnmanagedType.ByValTStr, SizeConst = 80)]
            public string szTypeName;
        };

        public const uint SHGFI_ICON = 0x000000100;
        public const uint SHGFI_DISPLAYNAME = 0x000000200;
        public const uint SHGFI_TYPENAME = 0x000000400;
        public const uint SHGFI_ATTRIBUTES = 0x000000800;
        public const uint SHGFI_ICONLOCATION = 0x000001000;
        public const uint SHGFI_EXETYPE = 0x000002000;
        public const uint SHGFI_SYSICONINDEX = 0x000004000;
        public const uint SHGFI_LINKOVERLAY = 0x000008000;
        public const uint SHGFI_SELECTED = 0x000010000;
        public const uint SHGFI_ATTR_SPECIFIED = 0x000020000;
        public const uint SHGFI_LARGEICON = 0x000000000;
        public const uint SHGFI_SMALLICON = 0x000000001;
        public const uint SHGFI_OPENICON = 0x000000002;
        public const uint SHGFI_SHELLICONSIZE = 0x000000004;
        public const uint SHGFI_PIDL = 0x000000008;
        public const uint SHGFI_USEFILEATTRIBUTES = 0x000000010;
        public const uint SHGFI_ADDOVERLAYS = 0x000000020;
        public const uint SHGFI_OVERLAYINDEX = 0x000000040;

History
code sample has a bug, the return value is not an HRESULT
code sample has a bug, the return value is not an HRESULT
History
FileIconInit needs to be called to refresh the system image list cache in the process
see the remarks at the FileIconInit Function
History
Don't use ImageList_Destroy on the ImageList you get
When you pass SHGFI_SYSICONINDEX to this function, it will return an HIMAGELIST; you might expect that you should call ImageList_Destroy when done with it, just as you must DestroyIcon the HICON it gives you. On Windows 7 (64-bit) doing this appears to be harmless- you just get the exact same handle value back, if you repeat the call. It's like Windows 7 protects this imagelist against deletion.

However, on Windows XP (32-bit), I find this is not the case. If you destroy the image list, then you will later crash when calling into the shell again. I guess that on XP, the shell image lists are not protected from destruction.

I do not know what happens on Vista. I expect it is either "crash" or "nothing", so there's no reason to ever destroy this image list.
History
Don't pass an empty name to get the generic file icon
Before Windows 7, you used to be able to use this to get the generic file icon (i.e. the ones for unknown file types):

SHGetFileInfo(L"", FILE_ATTRIBUTE_NORMAL, &sfi, sizeof(sfi), SHGFI_ICON|SHGFI_SMALLICON|SHGFI_USEFILEATTRIBUTES);

In Windows 7 the behaviour seems to have changed and the above call will get you back the icon for your system drive.

Instead, pass a non-empty filename without an extension:

SHGetFileInfo(L"dummy", FILE_ATTRIBUTE_NORMAL, &sfi, sizeof(sfi), 
SHGFI_ICON|SHGFI_SMALLICON|SHGFI_USEFILEATTRIBUTES);


When getting the icon for a particular extension you can still just provide an extension with no base name:


SHGetFileInfo(L".txt", FILE_ATTRIBUTE_NORMAL, &sfi, sizeof(sfi), 
SHGFI_ICON|SHGFI_SMALLICON|SHGFI_USEFILEATTRIBUTES);
History
FILE_ATTRIBUTE_* constant values 
<Flags()> _
        Public Enum FileAttributes As UInt32 
            FILE_ATTRIBUTE_ARCHIVE = &H20
            FILE_ATTRIBUTE_COMPRESSED = &H800
            <EditorBrowsable(EditorBrowsableState.Never)> FILE_ATTRIBUTE_DEVICE = &H40
            FILE_ATTRIBUTE_DIRECTORY = &H10
            FILE_ATTRIBUTE_ENCRYPTED = &H4000
            FILE_ATTRIBUTE_HIDDEN = &H2
            FILE_ATTRIBUTE_NORMAL = &H80
            FILE_ATTRIBUTE_NOT_CONTENT_INDEXED = &H2000
            FILE_ATTRIBUTE_OFFLINE = &H1000
            FILE_ATTRIBUTE_READONLY = &H1
            FILE_ATTRIBUTE_REPARSE_POINT = &H400
            FILE_ATTRIBUTE_SPARSE_FILE = &H200
            FILE_ATTRIBUTE_SYSTEM = &H4
            FILE_ATTRIBUTE_TEMPORARY = &H100
            FILE_ATTRIBUTE_VIRTUAL = &H10000
        End Enum


History
SHGFI_* constant values 
        <Flags()> _
        Public Enum FileInformationFlags As UInt32 
            <EditorBrowsable(EditorBrowsableState.Advanced)> zeor = 0UI
            SHGFI_ADDOVERLAYS = &H20UI
            SHGFI_ATTR_SPECIFIED = &H20000UI
            SHGFI_ATTRIBUTES = &H800UI
            SHGFI_DISPLAYNAME = &H200UI
            SHGFI_EXETYPE = &H2000UI
            SHGFI_ICON = &H100UI
            SHGFI_ICONLOCATION = &H1000UI
            SHGFI_LARGEICON = &H0UI
            SHGFI_LINKOVERLAY = &H8000UI
            SHGFI_OPENICON = &H2UI
            SHGFI_OVERLAYINDEX = &H40UI
            SHGFI_PIDL = &H8UI
            SHGFI_SELECTED = &H10000UI
            SHGFI_SHELLICONSIZE = &H4UI
            SHGFI_SMALLICON = &H1UI
            SHGFI_SYSICONINDEX = &H4000UI
            SHGFI_TYPENAME = &H400UI
            SHGFI_USEFILEATTRIBUTES = &H10UI
        End Enum

History
SHGFI_* constant values
History
Constant values
History
Visual Basic 9 declaration 
        Public Declare Auto Function SHGetFileInfo Lib "shell32.dll" ( _
            ByVal pszPath As String, _
            ByVal dwFileAttributes As FileAttributes, _
            ByRef psfi As SHFILEINFO, _
            ByVal cbFileInfo As UInt32, _
            ByVal uFlags As FileInformationFlags) As IntPtr


History