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

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

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

' 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

Related Functions

SHGetFolderLocation, SHGetSpecialFolderPath