# Titanium.Filesystem

The top level filesystem module, used to access files and directories on the device.

Availability
0.8
0.8
9.2.0
4.1.0

# Overview

For examples of using the Filesystem APIs, refer to the Filesystem Access and Storage guide (opens new window) as well as the other Filesystem submodule API documentation.

# Examples

# Getting a directory for an application group (iOS)

This example writes a string to a text file in a shared directory

var suiteDir = Ti.Filesystem.directoryForSuite('group.appc.Sharing');
if (!suiteDir) {
    logInApp('Suite Directory not found, check Entitlements.');
    return;
}
var f = Ti.Filesystem.getFile(suiteDir,'emptyfile.txt');
f.write('The file is no longer empty!');

# Properties

# applicationCacheDirectory READONLY

Availability
1.8.3
1.8.3
9.2.0
4.1.0
applicationCacheDirectory :String

Path to the application's internal cache directory.

Files stored in the cache directory remain after the application is closed but at the discretion of the operating system.

On the Android platform, the cache is limited to 25 MB and the files remain for the lifetime of the application, that is, until the application is uninstalled.

On the iOS platform, the cache does not have a size limit but the data remains until iOS cleans the directory to recover the disk space.


# applicationDataDirectory READONLY

Availability
0.8
0.8
9.2.0
4.1.0
applicationDataDirectory :String

Path to the application's data directory.

This is a writable directory that can be used to store applications-specific files.

On iOS, this directory is specifically designated for user documents, and a separate directory, applicationSupportDirectory is used for other application data.

On iOS, files in this directory are backed up unless the remoteBackup flag is set to false.


# applicationDirectory READONLY

Availability
0.8
9.2.0
4.1.0
applicationDirectory :String

Path to the iOS application directory.


# applicationSupportDirectory READONLY

Availability
0.8
9.2.0
4.1.0
applicationSupportDirectory :String

Path to the application support directory.

This is a writable directory used on iOS for application files that are not user documents--including settings files, caches, and so on.

On iOS, files in this directory are backed up unless the remoteBackup flag is set to false.


# externalCacheDirectory READONLY

Availability
9.3.0
externalCacheDirectory :String

Path to the app's sandboxed cache folder on removable storage, such as SD card.

This directory is intended to be used to store large temporary files since external storage typically has a larger capacity than internal storage. This is a good place to store videos and large photos.

The application should check isExternalStoragePresent before accessing this location. This is because external storage is sometimes removable on same devices, such as an SD card.

This directory does not require the Manifest.permission.READ_EXTERNAL_STORAGE and Manifest.permission.WRITE_EXTERNAL_STORAGE permissions.


# externalStorageDirectory READONLY

Availability
0.8
4.1.0
externalStorageDirectory :String

Path to the app's sandboxed folder on removable storage, such as SD card.

This directory is intended to be used to store large files since external storage typically has a larger capacity than internal storage. This is a good place to store videos and large photos.

The application should check isExternalStoragePresent before accessing this location. This is because external storage is sometimes removable on same devices, such as an SD card.

As of Titanium 9.3.0, this directory does not require the Manifest.permission.READ_EXTERNAL_STORAGE and Manifest.permission.WRITE_EXTERNAL_STORAGE permissions. For older Titanium SDK versions, these permission are required and you must call the requestStoragePermissions method to request the end-user's permission to read/write to external storage.


# lineEnding READONLY

Availability
0.8
0.8
9.2.0
4.1.0
lineEnding :String

Platform-specific line ending constant.


# resourcesDirectory READONLY

Availability
0.8
0.8
9.2.0
4.1.0
resourcesDirectory :String

Path to the application's resource directory.

This directory is read-only. If you need to modify any files in this directory, they must first be copied to another directory, such as applicationDataDirectory or tempDirectory.

On iOS, writable files can also be placed in the applicationSupportDirectory. On Android, writable files can also be placed in the externalStorageDirectory.

Note that when running on the simulator, the resources directory may be writable, but it is not writable on device.


# resRawDirectory READONLY

Availability
3.0.2
resRawDirectory :String

Path to the application's raw resource directory.

On Android, the raw resources directory can be used for resources that need to be accessed as individual files, not included in the Android resources bundle. For example, sound files placed in the raw resources directory can be accessed by notifications, which cannot access sound files from the resource directory.

To use raw resources, place files in the platform/android/res/raw folder, where platform is at the top level of the project, not inside the Resources folder. You will need to create the platform folder and subfolders.

This directory is read-only. If you need to modify any files in this directory, they must first be copied to another directory, such as applicationDataDirectory or tempDirectory.


# separator READONLY

Availability
0.8
0.8
9.2.0
4.1.0
separator :String

Platform-specific path separator constant.


# tempDirectory READONLY

Availability
0.8
0.8
9.2.0
4.1.0
tempDirectory :String

Path for the application's temporary directory.

This directory can be used for storing temporary files. Files in this directory may not persist when the application is shut down and restarted.

# Methods

# createTempDirectory

Availability
0.8
0.8
9.2.0
4.1.0
createTempDirectory() Titanium.Filesystem.File

Creates a temporary directory and returns a Titanium.Filesystem.File object representing the new directory.

Returns


# createTempFile

Availability
0.8
0.8
9.2.0
4.1.0
createTempFile() Titanium.Filesystem.File

Creates a temporary file and returns a Titanium.Filesystem.File object representing the new file.

Returns


# directoryForSuite

Availability
4.0.0
9.2.0
directoryForSuite(suiteName) String

Returns the path to the container directory associated with the specified security application group ID.

This is a writable directory used on iOS. Groups of sandboxed apps that need to share files and other information can request a container directory as part of their entitlements.

When called with a valid group identifier, this method returns the location of that directory as a string. Returns null if the group identifier is invalid; check the app's entitlements.

Parameters

Name Type Description
suiteName String

The name of the suite.

Returns

Type
String

# getAsset

Availability
5.4.0
9.2.0
getAsset(...path) Titanium.Blob

Returns a Blob object representing the asset catalog image identified by the path arguments.

This method is only applicable on images in assets catalogs for apps with app-thinning enabled on iOS. Since the bundled image has been reallocated into assets catalog, it is no longer accessible via the original file path. To obtain a Blob object representing this image, use the original file path as the parameter in this method instead of using it in getFile

Similar to getFile, this method takes a variable number of arguments, where each argument is treated as a path component. All of the arguments are joined together using the platform-specific path separator to make the final path.

If a relative path is passed, the full path should be interpreted relative to the current file. For example, if the file Resources/login/login.js contains the following code:

var icon = Titanium.Filesystem.getAsset('icon.png');

The path is interpreted as Resources/login/icon.png.

On iOS, all relative paths are currently interpreted as relative to the Resources directory, not to the current context. This is a known issue that will be addressed in a future release.

Parameters

Name Type Description
path String

One or more path components. Path arguments are joined together using the platform specific path separator to form the full path.

Returns


# getFile

Availability
0.8
0.8
9.2.0
4.1.0
getFile(...path) Titanium.Filesystem.File

Returns a File object representing the file identified by the path arguments.

Note that getFile does not create a file if one does not exist at the specified path. It returns a new File object referring to the specified file path. The application can create a file at that path by calling write or create a directory by calling createDirectory on the File object.

This method takes a variable number of arguments, where each argument is treated as a path component. All of the arguments are joined together using the platform-specific path separator to make the final path.

If a relative path is passed, the full path should be interpreted relative to the current file. For example, if the file Resources/login/login.js contains the following code:

var icon = Titanium.Filesystem.getFile('icon.png');

The path is interpreted as Resources/login/icon.png.

On iOS, all relative paths are currently interpreted as relative to the Resources directory, not to the current context. This is a known issue that will be addressed in a future release.

On iOS9, if app thinning is enabled, and the file of interest is an image file that was bundled with the app (not downloaded during runtime), this will not return the image file since it is already allocated inside the assets catalog. Please use getAsset instead for this case.

Parameters

Name Type Description
path String | Array<String>

One or more path components. Path arguments are joined together using the platform specific path separator to form the full path.

Returns


# hasStoragePermissions

Availability
5.4.0
hasStoragePermissions() Boolean

Returns true if the app has storage permissions.

Returns

Type
Boolean

# isExternalStoragePresent

Availability
0.8
0.8
9.2.0
4.1.0
isExternalStoragePresent() Boolean

Returns true if the device supports external storage and the external storage device is mounted.

Returns true on Android if an external storage device, such as an SD card, is available for reading and writing.

Returns false on iOS.

Returns

Type
Boolean

# openStream

Availability
0.8
0.8
9.2.0
4.1.0
openStream(mode, path) Titanium.Filesystem.FileStream

Opens file using the Titanium.IOStream interface.

Parameters

Name Type Description
mode Number

Access mode.

path String

One or more path components. Path arguments are joined together using the platform-specific path separator to form the full path.

Returns


# requestStoragePermissions

Availability
5.4.0
requestStoragePermissions([callback]) Promise<RequestStorageAccessResult>

Requests for storage permissions

On Android, the dialog will only appear if the permission is not accepted by the user and the user did not check the box "Never ask again" when denying the request. If the user checks the box "Never ask again," the user has to manually enable the permission in device settings.

This method requests Manifest.permission.READ_EXTERNAL_STORAGE and Manifest.permission.WRITE_EXTERNAL_STORAGE. If you require other permissions, you can also use requestPermissions.

Parameters

Name Type Description
callback Callback<RequestStorageAccessResult>

Function to call upon user decision to grant storage access. Optional on SDK 10, as this method will return a Promise, which may be used to handle the result.

Returns

On SDK 10+, this method will return a Promise whose resolved value is equivalent to that passed to the optional callback argument.

Type
Promise<RequestStorageAccessResult>

# Constants

# IOS_FILE_PROTECTION_COMPLETE

Availability
4.1.0
9.2.0
IOS_FILE_PROTECTION_COMPLETE :String

Constant used to set protection key to NSFileProtectionComplete in file attributes.

File is stored in an encrypted format on disk. Cannot be read from or written to while the device is locked or booting.


# IOS_FILE_PROTECTION_COMPLETE_UNLESS_OPEN

Availability
4.1.0
9.2.0
IOS_FILE_PROTECTION_COMPLETE_UNLESS_OPEN :String

Constant used to set protection key to NSFileProtectionCompleteUnlessOpen in file attributes.

File is stored in an encrypted format on disk. Can be created while the device is locked, but once closed, cannot be opened again until the device is unlocked. If the file is opened when unlocked, you may continue to access the file normally, even if the user locks the device.


# IOS_FILE_PROTECTION_COMPLETE_UNTIL_FIRST_USER_AUTHENTICATION

Availability
4.1.0
9.2.0
IOS_FILE_PROTECTION_COMPLETE_UNTIL_FIRST_USER_AUTHENTICATION :String

Constant used to set protection key to NSFileProtectionCompleteUntilFirstUserAuthentication in file attributes.

File is stored in an encrypted format on disk. Cannot be accessed until after the device has booted. After the user unlocks the device for the first time, your app can access the file and continue to access it even if the user subsequently locks the device.


# IOS_FILE_PROTECTION_NONE

Availability
4.1.0
9.2.0
IOS_FILE_PROTECTION_NONE :String

Constant used to set protection key to NSFileProtectionNone in file attributes.

File will have no special protection associated with it. Can be read from or written to at any time.


# MODE_APPEND

Availability
0.8
0.8
9.2.0
4.1.0
MODE_APPEND :Number

Constant for append mode for file operations.


# MODE_READ

Availability
0.8
0.8
9.2.0
4.1.0
MODE_READ :Number

Constant for read mode for file operations.


# MODE_WRITE

Availability
0.8
0.8
9.2.0
4.1.0
MODE_WRITE :Number

Constant for write mode for file operations.