Windows API Guide - Reference - Volume 1: Version 3.0 For the MS-DOS and PC-DOS Operating Systems

2017-07-07 02:10:07

Declare Function SHGetFolderLocation Lib "shell32.dll" Alias "SHGetFolderLocationA" (ByVal hwndOwner As Long, ByVal nFolder As Long, ByVal hToken As Long, ByVal dwReserved As Long, ppidl As Long) As Long

Platforms

Windows 95: Not Supported.
Windows 98: Not Supported.
Windows NT: Not Supported
Windows 2000: Supported.
Windows CE: Not Supported.

Note: SHGetFolderLocation may be available on platforms other than Windows 2000. It also appears in shfolder.dll, a redistributable DLL. The Declare for that function is identical to the one above, except for the filename. shfolder.dll is not necessarily guaranteed to be on a system.

Description & Usage

SHGetFolderLocation creates a pointer to an ITEMIDLIST structure (a.k.a. a PIDL) refering to a special folder on the computer. The PIDL can refer to special folders which are either a physical path on a drive or a virtual folder. After your program is finished using the PIDL obtained by this function, use CoTaskMemFree to release it.

Return Value

The function returns one of the following flags:

S_OK: The function completed successfully.
S_FALSE: The CSIDL of the special folder is valid but is a virtual folder.
E_INVALIDARG: The CSIDL is not valid.

Visual Basic-Specific Issues

None.

Parameters

hwndOwner: A handle to the window calling the function. This window will own any dialog boxes created by this function.
nFolder: The CSIDL of the special folder to get a PIDL to.
hToken: A token identifying the user. This is normally 0, but may be other values for security purposes.
dwReserved: Reserved -- set to 0.
ppidl: Receives a PIDL to the desired special folder.

Example

' This code is licensed according to the terms and conditions listed here. ' Open the Browse for Folder dialog box and display both the display name and ' the actual name of the folder (if it is not a virtual folder). Any folder under My Computer ' may be selected. Dim bi As BROWSEINFO ' structure passed to the function Dim pidl As Long ' PIDL to the user's selection Dim physpath As String ' string used to temporarily hold the physical path Dim retval As Long ' return value ' Initialize the structure to be passed to the function. bi.hwndOwner = Form1.hWnd ' window Form1 is the owner of the dialog box ' Specify the My Computer virtual folder as the root retval = SHGetFolderLocation(Form1.hWnd, CSIDL_DRIVES, 0, 0, bi.pidlRoot) ' Make room in the buffer to get the [virtual] folder's display name bi.pszDisplayName = Space(260) bi.lpszTitle = "Please choose a folder." ' Message displayed to the user bi.ulFlags = 0 ' no flags are needed here bi.lpfn = 0 ' no callback function is being used bi.lParam = 0 ' not needed bi.iImage = 0 ' this will be set by the function ' Open the Browse for Folder dialog box. pidl = SHBrowseForFolder(bi) ' If the user selected something, display its display name ' and its physical location on the system. If pidl <> 0 Then ' Remove the empty space from the display name variable. bi.pszDisplayName = Left(bi.pszDisplayName, InStr(bi.pszDisplayName, vbNullChar) - 1) Debug.Print "The user selected: "; bi.pszDisplayName ' If the folder is not a virtual folder, display its physical location. physpath = Space(260) ' make room in the buffer retval = SHGetPathFromIDList(pidl, physpath) If retval = 0 Then Debug.Print "Physical Location: (virtual folder)" Else ' Remove the empty space and display the result. physpath = Left(physpath, InStr(physpath, vbNullChar) - 1) Debug.Print "Physical Location: "; physpath End If ' Free the pidl returned by the function. CoTaskMemFree pidl End If ' Whether successful or not, free the PIDL which was used to ' identify the My Computer virtual folder. CoTaskMemFree bi.pidlRoot