SHGetSpecialFolderLocation Function

Declare Function SHGetSpecialFolderLocation Lib "shell32.dll" (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

If successful, the function returns zero. If an error occured, the function returns an error code.

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 (unless it is a virtual folder). Any folder under My Computer may be selected. To run this example, place a command button named Command1 on a form window.

' This code is licensed according to the terms and conditions listed here.

' Declarations and such needed for the example:
' (Copy them to the (declarations) section of a module.)
Public Declare Function SHGetSpecialFolderLocation Lib "shell32.dll" (ByVal hwndOwner As Long, _
	ByVal nFolder As Long, ppidl As Long) As Long
Public Const CSIDL_DRIVES = &H11
Public Type BROWSEINFO
	hwndOwner As Long
	pidlRoot As Long
	pszDisplayName As String
	lpszTitle As String
	ulFlags As Long
	lpfn As Long
	lParam As Long
	iImage As Long
End Type
Public Declare Function SHBrowseForFolder Lib "shell32.dll" Alias "SHBrowseForFolderA" _
	(lpbi As BROWSEINFO) As Long
Public Declare Function SHGetPathFromIDList Lib "shell32.dll" Alias "SHGetPathFromIDListA" _
	(ByVal pidl As Long, ByVal pszPath As String) As Long
Public Declare Sub CoTaskMemFree Lib "ole32.dll" (ByVal pv As Long)

' *** Place the following code inside a form window. ***

Private Sub Command1_Click()
	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.
	With bi
		' The owner of the dialog box.
		.hwndOwner = Me.hWnd
		' Specify the My Computer virtual folder as the root.
		retval = SHGetSpecialFolderLocation(Me.hWnd, CSIDL_DRIVES, .pidlRoot)
		' Make room in the buffer to get the [virtual] folder's display name.
		.pszDisplayName = Space(260)
		' Message displayed to the user.
		.lpszTitle = "Please choose a folder."
		' Nothing else needs to be set.
		.ulFlags = 0
		.lpfn = 0
		.lParam = 0
		.iImage = 0
	End With
	
	' 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)
		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
End Sub