SHGetSpecialFolderLocation Function

Declare Function SHGetSpecialFolderLocation Lib "shell32.dll" Alias "SHGetSpecialFolderLocationA" (ByVal hwndOwner As Long, ByVal nFolder As Long, ppidl As Long) As Long

Platforms

Windows 95: Supported.
Windows 98: Supported.
Windows NT: Requires Windows NT 4.0 or later.
Windows 2000: Supported but Obsolete; use SHGetFolderLocation instead.
Windows CE: Not Supported.

Description & Usage

SHGetSpecialFolderLocation 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 a non-zero error code if an error occured, or 0 if successful.

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.
ppidl: Receives a PIDL to the desired special folder.

Example

' 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 = SHGetSpecialFolderLocation(Form1.hWnd, CSIDL_DRIVES, 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

Related Functions

SHGetFolderLocation, SHGetSpecialFolderPath