SHGetFileInfo 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

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)

Category

Shell

Go back to the alphabetical Function listing.
Go back to the Reference section index.


Last Modified: December 22, 1999
This page is copyright © 1999 Paul Kuliniewicz. Copyright Information Revised October 29, 2000
Go back to the Windows API Guide home page.
E-mail: vbapi@vbapi.com Send Encrypted E-Mail
This page is at http://www.vbapi.com/ref/s/shgetfileinfo.html