Name: specialFolderPath

Type: function

Syntax: the specialFolderPath of <folderIdentifier> 

Syntax: specialFolderPath(<folderIdentifier>)

Summary: Returns the names and locations of system-related <folders>.

Introduced: 1.1

OS: mac,windows,linux,ios,android

Platforms: desktop,server,web,mobile

Security: disk

Example:
specialFolderPath("Preferences")

Example:
set the defaultFolder to specialFolderPath("desktop")

Example:
put specialFolderPath("asup") into appSupportFolder

Example:
put url ("file:" & specialFolderPath("engine") & slash & "foo.txt") into tFileContents

Example:
set the folder to specialFolderPath("engine") & slash & "myimages"
put the files into tMyImages

Parameters:
folderIdentifier (enum): One of the items below. 
Windows >*Note:* For Windows systems, you can also specify a CSIDL number that identifies a special folder. You can find a complete list of available CDISL values on the <a href="http://vbnet.mvps.org/index.html?code/browse/csidlversions.htm">Microsoft web site</a>. Not all CSIDL numbers work on all Windows versions, refer to the link above to find out more about CSIDLs. 
iOS >*Note:* iOS imposes strict controls over what you can and cannot access. Each application in iOS is stored in its own 'sandbox' folder (referred to as the home folder). An application is free to read and write files within this folder and its descendants, but it is not allowed to access anything outside of the 'sandbox'. 
Android >*Note:* An Android application is installed on the phone in the form of its zip package. This means that any assets that are included are not available as discrete files in the native filesystem. In order to manage this the engine essentially 'virtualizes' the asset files you include, allowing (read-only) manipulation with all the standard LiveCode file and folder handling syntax. To access the assets you have included within your application, use filenames relative to <specialFolderPath> ("engine").  . For Mac OS systems: For Mac OS X systems: For Windows systems: Windows CSIDL numbers: For Unix systems: For iOS systems: For Android systems:
- "Desktop": The Desktop folder, where files or folders on the desktop are placed.
- "System": The active System Folder.
- "Apple": The Apple Menu Items folder inside the System Folder.
- "Control": The Control Panels folder inside the System Folder.
- "Extension": The Extensions folder inside the System Folder.
- "Fonts": The Fonts folder inside the System Folder.
- "Preferences": The Preferences folder inside the System Folder.
- "Temporary": For storage of temporary files.
- "Engine": The folder containing the engine and the executable files copied in the standalone application.
- "Resources": In development mode, the current stack folder. In a standalone, the resources folder where non-executable files, or folders specified from the Standalone Builder, are copied.
- "Home": The current user's home directory (e.g. "/Users/Fred").
- "Desktop": The user's Desktop folder.
- "System": The Apple Menu Items folder inside the System Folder.
- "Control": The active System Folder.
- "Fonts": The system Fonts folder.
- "Preferences": The Preferences folder inside the user's Library folder.
- "Temporary": For storage of temporary files.
- "Documents": For user documents.
- "Support": For application data.
- "Engine": The folder containing the engine and the executable files copied in the standalone application.
- "Resources": In development mode, the current stack folder. In a standalone, the resources folder where non-executable files, or folders specified from the Standalone Builder, are copied.
- "Home": The current user's home directory (e.g. "C:/Documents and Settings/Fred").
- "Desktop": The user's desktop folder.
- "System": For system components.
- "Start": For items in the Start menu.
- "Documents": The user's documents folder.
- "Fonts": For font storage.
- "Temporary": For storage of temporary files.
- "Support": For CSIDL 0x1a (appdata folder) data.
- "Engine": The folder containing the engine.
- "Resources": In development mode, the current stack folder. In a standalone, the resources folder where files or folders specified from the Standalone Builder are copied.
- "0x001a": The user application data folder (e.g. "C:/Documents and settings/Fred/Application Data").
- "0x0023": The "all users" application data folder (e.g. "C:/Documents and settings/all users/Application Data").
- "0x000d": The "My Music" folder.
- "0x000e": The "My Videos" folder.
- "0x0027": The "My Pictures" folder.
- "0x000a": The recycle bin.
- "Engine": The folder containing the engine.
- "Resources": In development mode, the current stack folder. In a standalone, the resources folder where files or folders specified from the Standalone Builder are copied.
- "Home": The current user's home directory (e.g. "/home/fred").
- "Desktop": The current user's desktop (e.g. "/home/fred/Desktop").
- "Temporary": For storage of temporary files (typically "/tmp").
- "0x000e": The "My Videos" folder.
- "Engine": The folder containing the engine.
- "Resources": In development mode, the current stack folder. In a standalone, the resources folder where files or folders specified from the Standalone Builder are copied.
- "home": The (unique) folder containing the application bundle and its associated data and folders.
- "documents": The folder in which the application should store any document data (this folder is backed up by iTunes on sync).
- "cache": The folder in which the application should store any transient data that needs to be preserved between launches (this folder is not backed up by iTunes on sync).
- "library": The folder in which the application can store data of various types. In particular, data private to the application should be stored in a folder named with the app's bundle identifier inside library (this folder is backed up by iTunes on sync).
- "temporary": The folder in which the application should store any temporary data that is not needed between launches (this folder is not backed up by iTunes on sync).
- "engine": The folder containing the built standalone engine (i.e. the bundle). This is useful for constructing paths to resources that have been copied into the bundle at build time.
- "resources": The path to the folder where the files and folders are copied in the standalone application (same as the engine folder).
- "engine": The (virtual) path to the engine and its assets.
- "documents": The path to a folder that can be used for per-application data files.
- "cache": The path to a folder that can be used for transient per-application data files.
- "resources": The path to the folder where files and folders are copied in the standalone application (same as the engine folder).

The result: If the <folderIdentifier> is either not supported on the current platform or doesn't exist on the current system, the result is set to "folder not found".

Returns: The <specialFolderPath> function returns a folder name and location.

Description:
Use the <specialFolderPath> function to place preferences in the Preferences folder, save files to the Documents folder, find out which files are installed in the System or Fonts folders, and so on.

If the folder is not found, the <specialFolderPath> function returns empty. If the <folderIdentifier> is either not supported on the current platform or doesn't exist on the current system, the result is set to "folder not found".
Some of the special folders you can specify with the <specialFolderPath> function need not have the standard names. (For example, the System Folder on Mac OS systems is not necessarily named "System Folder".) For this reason, the <specialFolderPath> function returns the full path to the folder, including the name of the folder.

If you are using the <specialFolderPath> on iOS, the you should only create files within the documents, cache and temporary folders. Be careful not to change or add any files within the application bundle. The application bundle is digitally signed when it is built, and any changes after this point will invalidate the signature and prevent it from launching.

>*Note:* Unlike (most) Mac OS X installs, the Android and iOS filesystems are case-sensitive.

>*Note:* The iOS simulator has the 'same' case-sensitivity as the host system and not the device.

Support for using the <specialFolderPath> function on iOS systems was added in version 4.5.2.
Support for using the <specialFolderPath> function on Unix systems was added in version 2.9.
Support for special folder constants (on Mac OS and OS X) and CSIDL numbers (on Windows) was added in version 2.0.

Changes:
Support for using the <specialFolderPath> function on Android systems was added in version 4.6.2.

References: revSetDatabaseDriverPath (command), tempName (function), folders (function)
