SHGetFileInfo

Windows Mobile 6.5
A version of this page is also available for
4/8/2010

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


WINSHELLAPI DWORD WINAPI SHGetFileInfo(
  LPCTSTR pszPath, 
  DWORD dwFileAttributes, 
  SHFILEINFO FAR* psfi, 
  UINT cbFileInfo, 
  UINT uFlags 
);

pszPath

[in] Pointer to a buffer that contains the path and file name. Both absolute and relative paths are valid. For more information, see Remarks.

dwFileAttributes

[in] Combination of one or more file attribute flags (FILE_ATTRIBUTE_* values). If uFlags does not include the SHGFI_USEFILEATTRIBUTES flag, this parameter is ignored.

The following table shows the additional values supported by Windows Embedded CE.

Value Description

FILE_ATTRIBUTE_INROM

The file is an operating system (OS) file stored in ROM. These files are read-only.

FILE_ATTRIBUTE_ROMMODULE

The file is an operating system file stored in ROM, designed to execute in place. In other words, code from this file is executed directly from ROM, rather than being first copied to RAM. The CreateFile function cannot be used to access this file. Use the LoadLibrary and CreateProcess functions instead.

psfi

[in] Pointer to a SHFILEINFO structure to receive the file information.

cbFileInfo

[in] Size, in bytes, of the SHFILEINFO structure pointed to by the psfi parameter.

uFlags

[in] Flags that specify the file information to retrieve. It can be a combination of the values in the following table.

Value Description

SHGFI_ATTRIBUTES

Retrieves the item attributes. The attributes are copied to the dwAttributes member of the structure specified in the psfi parameter.

SHGFI_DISPLAYNAME

Retrieves the display name for the file. The name is copied to the szDisplayName member of the structure specified in psfi.

SHGFI_EXETYPE

Retrieves the type of the executable file if pszPath identifies an executable file. This flag cannot be specified with any other flags.

SHGFI_ICON

Retrieves 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. The return value is the handle to the system image list. You must call the DestroyIcon function on this icon handle.

SHGFI_ICONLOCATION

Retrieves the name of the file that contains the icon representing the file. The name is copied to the szDisplayName member of the structure specified in psfi.

SHGFI_LARGEICON

Modifies SHGFI_ICON, causing the function to retrieve the file's large icon.

SHGFI_LINKOVERLAY

Modifies SHGFI_ICON, causing the function to add the link overlay to the file's icon.

SHGFI_OPENICON

Modifies SHGFI_ICON, causing the function to retrieve the file's open icon. A container object displays an open icon to indicate that the container is open.

SHGFI_PIDL

For Windows CE 1.0 through 2.01 and for Windows Embedded CE Handheld PC Edition version 3.0 and Windows Embedded CE Handheld PC Professional Edition version 3.0, indicates that pszPath is the address of an ITEMIDLIST structure rather than a path name.

SHGFI_SELECTED

Modifies SHGFI_ICON, causing the function to blend the file's icon with the system highlight color.

SHGFI_SMALLICON

Modifies SHGFI_ICON, causing the function to retrieve the file's small icon.

SHGFI_SYSICONINDEX

Retrieves the index of the icon within the system image list. The index is copied to the iIcon member of the structure specified by psfi. The return value is the handle to the system image list.

SHGFI_TYPENAME

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

SHGFI_USEFILEATTRIBUTES

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.

SHGFI_SELECTICON

Modifies SHGFI_ICON, causing the function to retrieve the file's icon in the selected state.

If SHGetFileInfo function cannot find a registered select icon for a file when SHGFI_SELECTICON was requested, it will return the default icon.

Aa931527.note(en-us,MSDN.10).gifNote:
This flag is supported only for a Windows Mobile device.

SHGFI_SHELLICONSIZE

Modifies 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.

Aa931527.note(en-us,MSDN.10).gifNote:
This flag is not supported for a Windows Mobile device.

Returns a value with a meaning that depends on the uFlags parameter. If uFlags contains the SHGFI_EXETYPE flag, the return value specifies the type of the executable file. The following table shows the possible values.

Value Executable File Type

0

Non-executable file or an error condition

Low-order word = NE or PE and high-order word = 3.0, 3.5, or 4.0

Windows application

Low-order word = MZ and high-order word = 0

MS-DOS .exe, .com, or .bat file

Low-order word = PE and high-order word = 0

Microsoft Win32®-based console application

If uFlags contains SHGFI_SYSICONINDEX, the return value is the handle to the system image list that contains the large icon images. If SHGFI_SMALLICON is included with SHGFI_SYSICONINDEX, the return value is the handle to the image list that contains the small icon images.

If uFlags does not contain SHGFI_EXETYPE or SHGFI_SYSICONINDEX, the return value is nonzero if successful, or zero otherwise.

If the uFlags parameter includes the SHGFI_USEFILEATTRIBUTES flag, the pszPath parameter does not have to be a valid file name. The function proceeds as if the file exists with the specified name and with the file attributes passed in the dwFileAttributes parameter. This enables you to obtain information about a file type by passing just the extension for pszPath and passing FILE_ATTRIBUTE_NORMAL in dwFileAttributes.

For Windows CE 2.10 and later, SHGetFileInfo does not support the following values for uFlags:

SHGFI_EXETYPE

SHGFI_ICONLOCATION

SHGFI_LINKOVERLAY

SHGFI_OPENICON

SHGFI_SELECTED

SHGFI_SHELLICONSIZE

Also for Windows CE 2.10 and later, SHGetFileInfo supports the SHGFI_PIDL flag only for Windows Embedded CE Handheld PC Edition version 3.0 and Windows Embedded CE Handheld PC Professional Edition version 3.0.

The following code example demonstrates how to to enable two-state filesytem icon animation.

Aa931527.note(en-us,MSDN.10).gifNote:
To make the following code example easier to read, security checking and error handling are not included. This code example should not be used in a release configuration unless it has been modified to include them.
LRESULT CALLBACK TwoStateFileAnimProc(HWND hwnd, UINT message, WPARAM wParam, LPARAM lParam)
{
    LPCTSTR szFileName                    = TEXT("myfile.xls");
    LRESULT lRet                          = 0;
    static SHFILEINFO s_sfiLarge          = {0};
    static SHFILEINFO s_sfiLargeSelected  = {0};
    static HIMAGELIST s_himlLarge         = NULL;
    static HIMAGELIST s_himlLargeSelected = NULL;
    switch (message)
    {
        case WM_CREATE:
            // Cache the file information and the imagelist.
            // Get the large default icon for the file.
            s_himlLarge = (HIMAGELIST)SHGetFileInfo(szFileName, 0, &s_sfiLarge, sizeof(s_sfiLarge), SHGFI_SYSICONINDEX|SHGFI_LARGEICON);
            // Get the large selected icon for the file.
            s_himlLargeSelected = (HIMAGELIST)SHGetFileInfo(szFileName, 0, &s_sfiLargeSelected, sizeof(s_sfiLargeSelected), SHGFI_SYSICONINDEX|SHGFI_LARGEICON|SHGFI_SELECTICON);
            break;
        case WM_PAINT:
            {
                PAINTSTRUCT ps;
                HDC hdc = BeginPaint(hwnd, &ps);
                // Draw the file icon in the selected state.
                ImageList_Draw(s_himlLargeSelected, s_sfiLargeSelected.iIcon, hdc, 0, 0, ILD_TRANSPARENT);
                // Draw the file icon in the default state.
                ImageList_Draw(s_himlLarge, s_sfiLarge.iIcon, hdc, 0, 100, ILD_TRANSPARENT);
                EndPaint(hwnd, &ps);
                break;
            }
    }
    return lRet;
}

Headershellapi.h
Windows Embedded CEWindows CE 1.0 and later
Windows MobileWindows Mobile Version 5.0 and later

Reference

DestroyIcon
SHFILEINFO

Other Resources


Community Additions

Show: