Titanium SDK # Titanium.Filesystem
The top level filesystem module, used to access files and directories on the device.
0.8
0.8
9.2.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
# apiName READONLY
3.2.0 3.2.0 9.2.0The name of the API that this proxy corresponds to.
The value of this property is the fully qualified name of the API. For example, Titanium.UI.Button
returns Ti.UI.Button.
# applicationCacheDirectory READONLY
1.8.3 1.8.3 9.2.0Path 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
0.8 0.8 9.2.0Path 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
0.8 9.2.0Path to the iOS application directory.
# applicationSupportDirectory READONLY
0.8 9.2.0Path 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.
# bubbleParent
3.0.0 3.0.0 9.2.0Indicates if the proxy will bubble an event to its parent.
Some proxies (most commonly views) have a relationship to other proxies, often established by the add() method. For example, for a button added to a window, a click event on the button would bubble up to the window. Other common parents are table sections to their rows, table views to their sections, and scrollable views to their views. Set this property to false to disable the bubbling to the proxy's parent.
Default: true
# externalCacheDirectory READONLY
9.3.0Path 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
0.8Path 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.
# lifecycleContainer
3.6.0The Window or TabGroup whose Activity lifecycle should be triggered on the proxy.
If this property is set to a Window or TabGroup, then the corresponding Activity lifecycle event callbacks will also be called on the proxy. Proxies that require the activity lifecycle will need this property set to the appropriate containing Window or TabGroup.
# resourcesDirectory READONLY
0.8 0.8 9.2.0Path 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
3.0.2Path 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.
# tempDirectory READONLY
0.8 0.8 9.2.0Path 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
# addEventListener
0.8 0.8 9.2.0Adds the specified callback as an event listener for the named event.
Parameters
| Name | Type | Description |
|---|---|---|
name | String | Name of the event. |
callback | Callback<Titanium.Event> | Callback function to invoke when the event is fired. |
Returns
- Type
- void
# applyProperties
3.0.0 3.0.0 9.2.0Applies the properties to the proxy.
Properties are supplied as a dictionary. Each key-value pair in the object is applied to the proxy such that myproxy[key] = value.
Parameters
| Name | Type | Description |
|---|---|---|
props | Dictionary | A dictionary of properties to apply. |
Returns
- Type
- void
# createTempDirectory
0.8 0.8 9.2.0Creates a temporary directory and returns a Titanium.Filesystem.File object representing the new directory.
Returns
# createTempFile
0.8 0.8 9.2.0Creates a temporary file and returns a Titanium.Filesystem.File object representing the new file.
Returns
# directoryForSuite
4.0.0 9.2.0Returns 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
# fireEvent
0.8 0.8 9.2.0Fires a synthesized event to any registered listeners.
Parameters
| Name | Type | Description |
|---|---|---|
name | String | Name of the event. |
event | Dictionary | A dictionary of keys and values to add to the Titanium.Event object sent to the listeners. |
Returns
- Type
- void
# getAsset
5.4.0 9.2.0Returns 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
- Type
- Titanium.Blob
# getFile
0.8 0.8 9.2.0Returns 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
5.4.0Returns true if the app has storage permissions.
Returns
- Type
- Boolean
# isExternalStoragePresent
0.8 0.8 9.2.0Returns 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
0.8 0.8 9.2.0Opens 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
# removeEventListener
0.8 0.8 9.2.0Removes the specified callback as an event listener for the named event.
Multiple listeners can be registered for the same event, so the
callback parameter is used to determine which listener to remove.
When adding a listener, you must save a reference to the callback function in order to remove the listener later:
var listener = function() { Ti.API.info("Event listener called."); }
window.addEventListener('click', listener);
To remove the listener, pass in a reference to the callback function:
window.removeEventListener('click', listener);
Parameters
| Name | Type | Description |
|---|---|---|
name | String | Name of the event. |
callback | Callback<Titanium.Event> | Callback function to remove. Must be the same function passed to |
Returns
- Type
- void
# requestStoragePermissions
5.4.0Requests 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 |
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
4.1.0 9.2.0Constant 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
4.1.0 9.2.0Constant 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
4.1.0 9.2.0Constant 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
4.1.0 9.2.0Constant 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.