SHGetSpecialFolderLocation reference for Network Programming in .NET with C# & Visual Basic .NET (VB.NET)

SHGetSpecialFolderLocation Reference in C#, VB.NET and VB6

Library:shell32.dll

Visual Basic 6 definition

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

Description

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.

Parameters

Further Information:

For further information on Windows API functions such as these, and how to use these API's in your C# and VB.NET applications, please refer to the book 'Network programming in .NET' (Buy at Amazon UK) (Buy at Amazon US)

Visual Basic 6 example source code

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.

' 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