SHGetFolderPath Function

Declare Function SHGetFolderPath Lib "shell32.dll" Alias "SHGetFolderPathA" (ByVal hwndOwner As Long, ByVal nFolder As Long, ByVal hToken As Long, ByVal dwFlags As Long, ByVal lpszPath As String) As Long

Platforms

Note: SHGetFolderPath 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

SHGetFolderPath retrieves the name of the path of a special folder on the system. This function only works with special folders which are physical directories on a disk. The function will fail if the special folder is a virtual folder.

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, which will own any dialog boxes the function may create.
nIndex
The CSIDL of the special folder to get the path of.
hToken
A token identifying the user. This is normally 0, but may be other values for security purposes.
dwFlags
One of the following flags specifying which path to retrieve:
SHGFP_TYPE_CURRENT
Retrieve the folder's current path.
SHGFP_TYPE_DEFAULT
Retrieve the folder's default path.
lpszPath
Receives a null-terminated string holding the path name of the special folder. A string at least 260 characters long must be passed as this parameter to receive the result.

Constant Definitions

Const S_OK = &H0
Const S_FALSE = &H1
Const E_INVALIDARG = &H80070057
Const SHGFP_TYPE_CURRENT = 0
Const SHGFP_TYPE_DEFAULT = 1

Example

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

' Display the path of the directory used as the My Documents
' special folder.  This might not be "C:\My Documents" if the user renamed it!
Dim pathname As String  ' receives the path of My Documents
Dim retval As Long  ' return value

' Make enough room in the buffer to receive the string.
pathname = Space(260)
' Get the path name of the My Documents special folder
retval = SHGetolderPath(Form1.hWnd, CSIDL_PERSONAL, 0, SHGFP_TYPE_CURRENT, pathname)
' Remove the empty space from the string.
pathname = Left(pathname, InStr(pathname, vbNullChar) - 1)
' Display the result.
Debug.Print "The My Documents special folder is: "; pathname

See Also

SHGetFolderLocation, SHGetSpecialFolderPath

Category

Shell

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


Last Modified: September 26, 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/shgetfolderpath.html