ssCore.FileSys.specialFolder

Return the location of Windows special folders using a system independent folder id.


Availability:

First available in version 3.0 build 2039.


Input Parameters:

folderID - CSIDL value identifying the required special folder.


Output Parameters:

result - Path to requested special folder.


Asynchronous Mode:

When this method is called asynchronously, a return object containing the output parameters is passed to the specified callback function.

ssCore.FileSys.specialFolder( paramsObject [, callbackParamsObject] [, errorParamsObject] );


Synchronous Mode:

When this method is called synchronously, a return object containing the output parameters is returned to the caller immediately.

var returnObject = ssCore.FileSys.specialFolder( paramsObject );


Notes:

The variable identified in result will be set to the fully qualified path of the folder identified by folderID. If you provide an invalid folderID, an invalid CSIDL or the special folder path does not exist on the computer, then the command will fail (the error code will be set to "3").

A number of commonly used folders are designated as special by Windows. These folders have a well-defined purpose, and most of them are present on all systems. Even if they are not present initially, their names and locations are still defined, so they can be added later. The collection of special folders includes all of the system's standard virtual folders, such as Printers, My Documents, and Network Neighborhood. It also includes a number of standard file system folders, such as Program Files and System. Even though these folders are a standard component of all systems, their names and locations in the namespace can vary. For example, the System directory is C:\Winnt\System32 on some systems and C:\Windows\System32 on others. The FileSys.specialFolder command provides a more flexible way to identify special folders, using their folder ids.

Folder IDs are built on top of an even more generic set of IDs, CSIDLs, which provide a uniform way of identifying and locating special folders, regardless of their name or location on a particular system. CSIDLs can be used with virtual folders as well as file system folders. Each special folder has a unique CSIDL assigned to it. For example, the current user's desktop folder has a CSIDL of 00000010 (hex). If you know the CSIDL of the folder you want you can find ANY special folder. You can find a complete list of the more than 50 CSIDLs in SHELLOBJ.H (which ships with Microsoft Visual Studio) or at MSDN.Microsoft.com. Folder paths you can retrieve easily using CSIDLs are:

                

Examples:

var return_obj = ssCore.FileSys.specialFolder({folderID:"MyPictures"});

ssDebug.trace(return_obj.result);