|
Action:
|
Takes the CSIDL of a folder and returns the pathname
|
| |
|
|
Syntax:
|
RetVal%
=
SHGetFolderPath
(
hWndOwner%,
csidl%,
hToken%,
dwFlags%,
pszPath$)
|
| |
|
|
|
hWndOwner%
|
Handle to an owner window. This parameter is typically set to
0. If it is not 0, it must be a valid window handle. Normally
this parameters applies only if a dial-up connection needs to be made to access the folder,
so this prompt will appear in the given window.
|
|
csidl%
|
A CSIDL value that identifies the folder whose path is to be retrieved.
You can force creation of a folder with SHGetFolderPath by combining the folder's CSIDL with
CSIDL_FLAG_CREATE (Or): If the folder does not exist, then the SHGetFolderPath function creates it for you, fills the string buffer with the path, and returns S_OK.
If you do not use the CSIDL_FLAG_CREATE flag, and the folder does not exist, then the SHGetFolder function returns S_FALSE and nothing is placed in your string buffer.
|
|
hToken%
|
An access token that can be used to represent a particular user. For systems earlier than Microsoft® Windows® 2000, it should be set to
0. See the access token explanation in the Platform SDK for
further information about obtaining tokens. Access token
represent a special user.
|
|
dwFlags%
|
Flags to specify which path is to be returned. It is used for cases where the folder associated with a CSIDL may be moved or renamed by the
user:
SHGFP_TYPE_CURRENT = Return the folder's current path
SHGFP_TYPE_DEFAULT = Return the folder's default path
|
|
pszPath$
|
Buffer of length of
MAX_PATH (260 characters) to receive the path. Empty on error.
Use pszPath$=Space$(260) to create the buffer and
pszPath$=ZTrim(pszPath$) to obtain the value after the function
returns successfully.
|
|
| |
|
|
Explanation:
|
Because the location of special folders can change from system to
system (it depends on the user's choice, and many systems do not use
the default names!),
Microsoft recommends that you use the SHGetFolderPath function to
determine the path for a special folder. For example, you might want to
determine the user's Application Data folder to store user-specific data
for your application. You can determine this at run time using the
SHGetFolderPath function. This function is a superset of SHGetSpecialFolderPath, included with earlier versions of the shell.
SHGetFolderPath returns one of these values:
S_OK = Function successfully returned, buffer filled
S_FALSE = The CSIDL is valid, but the folder does not exist
E_INVALIDARG = The CSIDL is not valid
|
| |
|
|
Example:
|
' Include Library
$Library "ShFolder"
Local buf$ = Space$(260)
If SHGetFolderPath(0, CSIDL_PROGRAM_FILES, 0, _
SHGFP_TYPE_CURRENT, buf$) = S_OK
Message "Your Program Path: " + ZTrim(buf)
EndIf
|
| |
|
|
Remark:
|
SHGetFolderPath is new to the Windows 2000 API.
If you call SHGetFolderPath from an application that can be installed on a
previous version of Windows, then you will need to redistribute the file
SHFolder.dll with your application.
The SHFolder.dll file is freely redistributable and can be obtained from the
latest Platform SDK, which is available from the following Web site: http://msdn.microsoft.com/developer/sdk/platform.asp
|
| |
|
|
See Also:
|
App.scSpecialDir, App.scCommonPrograms, App.scCommonStartMenu, App.scPrograms, App.scStartMenu, SHGetPathFromIDList, SHGetSpecialFolderLocation
|