Windows API Guide: SetMenuItemInfo Function

Declare Function SHGetFileInfo Lib "shell32.dll" Alias "SHGetFileInfoA" (ByVal pszPath As Any, ByVal dwFileAttributes As Long, psfi As SHFILEINFO, ByVal cbFileInfo As Long, ByVal uFlags As Long) As Long

Platforms

Windows 95: Supported.
Windows 98: Supported.
Windows NT: Requires Windows NT 4.0 or later.
Windows 2000: Supported.
Windows CE: Requires Windows CE 1.0 or later.

Description & Usage

SHGetFileInfo retrieves information about a file system object in the shell. Such file system objects include files, directories, virtual folders, and drives. The information retrieved generally relates to how the object appears in the system shell.

Return Value

If the uFlags parameter contains the SHGFI_EXETYPE flag, the function returns a value identifying the type of the executable file. If both the low-order and high-order words are not zero, the file is a Windows application. If only the low-order word is not zero but the high-order word is zero, the file is an MS-DOS based program or batch file or a 32-bit Windows console application. If the entire return value is zero, an error occured.

If the uFlags parameter instead contains the SHGFI_SYSICONINDEX flag, the function returns a handle to an internal image list which contains the icon requested by the function. If this value is zero, an error occured.

If neither of those two flags are specified, the return value is a non-zero value if successful, or zero if an error occured.

Visual Basic-Specific Issues

None.

Parameters

pszPath

The name of the file, directory, or drive to retrieve information about. If uFlags contains the SHGFI_PIDL flag, this is instead a pointer to an ITEMIDLIST structure (a PIDL) identifying a file system object. If uFlags contains the SHGFI_USEFILEATTRIBUTES flag, this parameter does not have to refer to an actual file; the function will instead retrieve attributes which the file would have if it existes (such as information relating to its extension).

dwFileAttributes

If uFlags contains the SHGFI_USEFILEATTRIBUTES flag, this parameter is a combination of the following flags specifying the file attributes of the theoretical file. If that flag is not specified, this parameter is ignored.

FILE_ATTRIBUTE_ARCHIVE: An archive file (which most files are).
FILE_ATTRIBUTE_COMPRESSED: A file residing in a compressed drive or directory.
FILE_ATTRIBUTE_DIRECTORY: A directory instead of a file.
FILE_ATTRIBUTE_HIDDEN: A hidden file, not normally visible to the user.
FILE_ATTRIBUTE_NORMAL: An attribute-less file (cannot be combined with other attributes).
FILE_ATTRIBUTE_READONLY: A read-only file.
FILE_ATTRIBUTE_SYSTEM: A system file, used exclusively by the operating system.

psfi

The structure that receives information about the file.

cbFileInfo

The size in bytes of the structure passed as psfi.

uFlags

A combination of the following flags specifying what information to retrieve about the file system object:

SHGFI_ATTRIBUTES: Retrieve the attributes of the file system object and put that information into the structure.
SHGFI_DISPLAYNAME: Retrieve the display name of the file system object. This is its full name as presented in the system shell.
SHGFI_EXETYPE: Retrieve what type of executable file was passed to the function. The result is returned by the function. This flag cannot be used with any other flags.
SHGFI_ICON: Retrieve a handle to the icon used to depict the file system object and put it into the structure. After using the handle, your program must use DestroyIcon to free up resources.
SHGFI_ICONLOCATION: Retrieve the name of the file which holds the icon used to depict the file system object and put it into the structure.
SHGFI_LARGEICON: When used with SHGFI_ICON, causes the function to retrieve the file system object's large icon.
SHGFI_LINKOVERLAY: When used with SHGFI_ICON, causes the function to add the link overlay (the "shortcut arrow" in the bottom right corner) to the icon.
SHGFI_OPENICON: When used with SHGFI_ICON, causes the function to use the icon which depicts the file system object as being open. (This usually applies only to icons used to depict folders or directories.)
SHGFI_PIDL: Indicates that pszPath contains a PIDL instead of a filename.
SHGFI_SELECTED: When used with SHGFI_ICON, causes the function to add the tint of the system highlight color to the file system object's icon (making it look "selected").
SHGFI_SHELLICONSIZE: When used with SHGFI_ICON, causes the function to retrieve a shell-sized icon instead of the standard size of icon.
SHGFI_SMALLICON: When used with SHGFI_ICON, causes the function to retrieve the file system object's small icon.
SHGFI_SYSICONINDEX: Retrieve the index of the icon in an internal image list and place it into the structure. The function returns a handle to the image list itself. Note that trying to access any icon with an index not equal to the one placed inside the structure will cause unexpected results!
SHGFI_TYPENAME: Retrieve the name of the file type of the file system object and place it into the structure.
SHGFI_USEFILEATTRIBUTES: Instead of specifying a file that actually exists, pszPath gives the name of a possibly ficticious file and dwFileAttributes identifies the pretend file's attributes. The function then behaves as if the file did exist and retrieves the appropriate information. This flag cannot be used with the SHGFI_ATTRIBUTES, SHGFI_EXETYPE, or SHGFI_PIDL flags.

Constant Definitions

Const FILE_ATTRIBUTE_ARCHIVE = &H20 Const FILE_ATTRIBUTE_COMPRESSED = &H800 Const FILE_ATTRIBUTE_DIRECTORY = &H10 Const FILE_ATTRIBUTE_HIDDEN = &H2 Const FILE_ATTRIBUTE_NORMAL = &H0 Const FILE_ATTRIBUTE_READONLY = &H1 Const FILE_ATTRIBUTE_SYSTEM = &H4 Const SHGFI_ATTRIBUTES = &H800 Const SHGFI_DISPLAYNAME = &H200 Const SHGFI_EXETYPE = &H2000 Const SHGFI_ICON = &H100 Const SHGFI_ICONLOCATION = &H1000 Const SHGFI_LARGEICON = &H0 Const SHGFI_LINKOVERLAY = &H8000 Const SHGFI_OPENICON = &H2 Const SHGFI_PIDL = &H8 Const SHGFI_SELECTED = &H10000 Const SHGFI_SHELLICONSIZE = &H4 Const SHGFI_SMALLICON = &H1 Const SHGFI_SYSICONINDEX = &H4000 Const SHGFI_TYPENAME = &H400 Const SHGFI_USEFILEATTRIBUTES = &H10

Example

' This code is licensed according to the terms and conditions listed here. ' Retrieve information about a generic MP3 file found in the system ' shell.  The file specified by the function does not actually exist, ' but its properties will reflect what any MP3 file would probably ' have (the .mp3 extension and the "archive" attribute). Dim info As SHFILEINFO  ' receives information about the file Dim retval As Long  ' return value of the function ' Retrieve information about what the C:\dummy.mp3 file would ' look like if it existed. retval = SHGetFileInfo("C:\dummy.mp3", FILE_ATTRIBUTE_ARCHIVE, info, Len(info), SHGFI_USEFILEATTRIBUTES Or SHGFI_TYPENAME Or SHGFI_ICON) ' Display the name of the .mp3 file type on the computer. ' (Note how the trailing nulls are removed from the string.) Debug.Print "The file type of .mp3 files is "; Left(info.szTypeName, InStr(info.szTypeName, vbNullChar) - 1) ' Draw the icon used for MP3 files in the corner of window Form1. retval = DrawIcon(Form1.hDC, 0, 0, info.hIcon) ' Destroy the icon handle to save resources. retval = DestroyIcon(info.hIcon)