Titanium.Filesystem
The top level filesystem module, used to access files and directories on the device.
For examples of using the Filesystem APIs, refer to the Filesystem Access and Storage guide as well as the other Filesystem submodule API documentation.
Extends: Titanium.Module · Since: 0.1
Properties #
apiName#
Type: String
The name of the API that this proxy corresponds to.
The value of this property is the fully qualified name of the API. For example, Button
returns Ti.UI.Button.
applicationCacheDirectory#
Type: 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#
Type: 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.
applicationSupportDirectory#
Type: 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.
bubbleParent#
Type: Boolean
Indicates 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.
externalCacheDirectory#
Type: 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#
Type: 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.
IOS_FILE_PROTECTION_COMPLETE#
Type: 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#
Type: 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#
Type: 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#
Type: 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.
lifecycleContainer#
Type: Titanium.UI.Window, Titanium.UI.TabGroup
The 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#
Type: 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#
Type: 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.
tempDirectory#
Type: 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 #
addEventListener #
Adds the specified callback as an event listener for the named event.
| Name | Type | Summary | Optional |
|---|---|---|---|
name | String | Name of the event. | No |
callback | Callback<Titanium.Event> | Callback function to invoke when the event is fired. | No |
applyProperties #
Applies 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.
| Name | Type | Summary | Optional |
|---|---|---|---|
props | Dictionary | A dictionary of properties to apply. | No |
createTempDirectory #
Creates a temporary directory and returns a File object representing the new directory.
Returns: Titanium.Filesystem.File
createTempFile #
Creates a temporary file and returns a File object representing the new file.
Returns: Titanium.Filesystem.File
directoryForSuite #
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.
| Name | Type | Summary | Optional |
|---|---|---|---|
suiteName | String | The name of the suite. | No |
Returns: String
fireEvent #
Fires a synthesized event to any registered listeners.
| Name | Type | Summary | Optional |
|---|---|---|---|
name | String | Name of the event. | No |
event | Dictionary | A dictionary of keys and values to add to the Titanium.Event object sent to the listeners. | Yes |
getAsset #
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.
| Name | Type | Summary | Optional |
|---|---|---|---|
path | String | One or more path components. Path arguments are joined together using the platform specific path separator to form the full path. | No |
Returns: Titanium.Blob
getFile #
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 iOS 9, 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.
| Name | Type | Summary | Optional |
|---|---|---|---|
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. | No |
Returns: Titanium.Filesystem.File
isExternalStoragePresent #
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: Boolean
openStream #
Opens file using the Titanium.IOStream interface.
| Name | Type | Summary | Optional |
|---|---|---|---|
mode | Number | Access mode. | No |
path | String | One or more path components. Path arguments are joined together using the platform-specific path separator to form the full path. | No |
Returns: Titanium.Filesystem.FileStream
removeEventListener #
Removes 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);
| Name | Type | Summary | Optional |
|---|---|---|---|
name | String | Name of the event. | No |
callback | Callback<Titanium.Event> | Callback function to remove. Must be the same function passed to addEventListener. | No |
requestStoragePermissions #
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 Titanium.Android.requestPermissions.
| Name | Type | Summary | Optional |
|---|---|---|---|
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. | Yes |
Returns: Promise<RequestStorageAccessResult> — On SDK 10+, this method will return a `Promise` whose resolved value is equivalent to that passed to the optional callback argument.
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!');