Titanium SDK

# Titanium.Filesystem.File

Object representing a path to a file or directory in the device's persistent storage.

Availability
0.8
0.8
9.2.0
Extends
Titanium.Proxy

# Overview

Use the Titanium.Filesystem.getFile method to get a handle to a File object, which represents a given path. There does not need to be an existing file or directory does not need to exist before getFile is called. If the file doesn't exist, and the file path identifies a file in a writable directory, writing to the file creates the file implicitly.

See Titanium.Filesystem for constants identifying commonly-used device directories.

Use the Titanium.Filesystem.File.exists method to test whether the file exists.

A file object can point to an ordinary file, a directory or a symbolic link. Use Titanium.Filesystem.File.createDirectory to create a directory. Use the Titanium.Filesystem.File.getDirectoryListing method to retrieve a list of the directory's contents.

The File object doesn't provide methods for random access into the file. The read method reads the file's entire contents into a Blob object. The write method can either overwrite the entire file or append to an existing file.

For random access to a file, such as accessing a small portion of a larger file, you can open a file as a Titanium.Filesystem.FileStream object. Use the Titanium.Filesystem.File.open method to get a FileStream for an existing File object, or use the Titanium.Filesystem.openStream method to get a FileStream directly without calling getFile first.

The Titanium.Filesystem module defines a number of properties and methods related to filesystem access, including properties that specify paths for application-specific directories, and methods for creating temporary files and directories.

On Android, files may be stored on external storage (that is, removable media such as SD Cards).

Note that once created with getFile, the path associated with a file object is immutable. If you move the underlying file using Titanium.Filesystem.File.move or Titanium.Filesystem.File.rename, you can no longer access it with the original File object. You must use getFile to get a handle to the new path.

# Resource Files

The Resources directory and all the files in it are read-only. On Android, resource files are stored in the resource bundle and do not have all of the properties of normal files. In particular, they do not have creation or modification timestamps.

# Examples

# Reading a File

Data files shipped with the application are stored in the resources directory.

This example reads string data from a text file.

// resourcesDirectory is actually the default location, so the first
// argument could be omitted here.
file = Ti.Filesystem.getFile(Ti.Filesystem.resourcesDirectory, "textfile.txt");
var blob = file.read();
var readText = blob.text;
// dispose of file handle & blob.
file = null;
blob = null;

# Creating a Subdirectory

Files that the application writes to need to be stored outside of the resources directory, since that directory is read-only.

This example creates a subdirectory to store downloaded images. The example assumes that two variables are defined elsewhere in the code: myImageID, a string containing some kind of ID for the downloaded image, and myImageData, a Blob containing JPEG image data.

var imageDir = Ti.Filesystem.getFile(Ti.Filesystem.applicationDataDirectory,
    'downloaded_images');
if (! imageDir.exists()) {
    imageDir.createDirectory();
}

// .resolve() provides the resolved native path for the directory.
var imageFile  = Ti.Filesystem.getFile(imageDir.resolve(), myImageID + '.jpg');
Ti.API.info("ImageFile path is: " + imageFile.resolve());
if (imageFile.write(myImageData)===false) {
    // handle write error
}
// dispose of file handles
imageFile = null;
imageDir = null;

# Properties

# apiName READONLY

Availability
3.2.0
3.2.0
9.2.0
apiName :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, Titanium.UI.Button returns Ti.UI.Button.

# bubbleParent

Availability
3.0.0
3.0.0
9.2.0
bubbleParent :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.

Default: true

# executable READONLY

Availability
0.8
0.8
9.2.0
executable :Boolean

true if the file is executable.

On iOS, this property exists but is always false.

# hidden

Availability
0.8
0.8
9.2.0
hidden :Boolean

Set to true if the file is hidden.

On iOS, this property exists but is always false.

# lifecycleContainer

Availability
3.6.0
lifecycleContainer :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.

# name READONLY

Availability
0.8
0.8
9.2.0
name :String

Name of the file.

# nativePath READONLY

Availability
0.8
0.8
9.2.0
nativePath :String

Native path associated with this file object, as a file URL.

On iOS, use the resolve method to obtain a plain file path for use with native modules.

# parent READONLY

Availability
0.8
parent :Titanium.Filesystem.File

A File object representing the parent directory of the file identified by this object.

iOS platform-note: Prior to Titanium SDK 7.0.0, this method returned the path of the parent directory as a String. Since Titanium SDK 7.0.0 it returnes a Titanium.Filesystem.File reference for parity wih Android and Windows.

# readonly READONLY

Availability
0.8
readonly :Boolean

true if the file identified by this object is read-only.

# remoteBackup

Availability
1.8.0
9.2.0
remoteBackup :Boolean

Value indicating whether or not to back up to a cloud service.

Some apps may be rejected by Apple for backing up specific files; if this is the case, ensure that this value is set to false for them. This value should only need to be set once by your app, but setting it multiple times will not cause problems. For files distributed with your app, this will need to be set on boot. This flag will only affect iOS versions 5.0.1 and later, but is safe to set on earlier versions.

Note that setting this property to false will also prevent the file identified by this object from being backed up to iTunes.

Default: true

# size READONLY

Availability
0.8
0.8
9.2.0
size :Number

Size, in bytes, of the file identified by this object.

symbolicLink :Boolean

true if the file identified by this object is a symbolic link.

# writable READONLY

Availability
0.8
0.8
9.2.0
writable :Boolean

true if the file identified by this object is writable.

# Methods

# addEventListener

Availability
0.8
0.8
9.2.0
addEventListener(name, callback) → void

Adds 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

# append

Availability
7.3.0
0.9.0
9.2.0
append(data) → Boolean

Appends data to the file identified by this file object.

Data to append can be specified as a String, Blob, or File.

If the data argument is a File object, the file's contents are appended to this file.

Returns true if the operation succeeds.

Parameters

Name Type Description
data String | Titanium.Blob | Titanium.Filesystem.File

Data to append.

Returns

Type
Boolean

# applyProperties

Availability
3.0.0
3.0.0
9.2.0
applyProperties(props) → void

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.

Parameters

Name Type Description
props Dictionary

A dictionary of properties to apply.

Returns

Type
void

# copy

Availability
0.9.0
7.3.0
9.2.0
copy(destinationPath) → Boolean

Copies the file identified by this file object to a new path.

Returns true if the copy succeeds.

Parameters

Name Type Description
destinationPath String

Destination path to copy to.

Returns

Type
Boolean

# createdAt

Availability
7.3.0
7.3.0
9.2.0
createdAt() → Date

Returns the creation Date for the file identified by this file object.

On Android, returns a Date whose getTime() value is 0 for resource files.

Important: When developing for the Apple ecosystem, using this API requires the NSPrivacyAccessedAPICategoryFileTimestamp property set in the privacy manifest that was introduced in iOS 17. You can learn more about it here.

Returns

Type
Date

# createDirectory

Availability
0.8
0.8
9.2.0
createDirectory([recursive]) → Boolean

Creates a directory at the path identified by this file object.

Returns true if the directory was created successfully.

Parameters

Name Type Description
recursive Boolean

Toggles whether to recursively create the directory structure (like mkdir -p). Pass false to avoid recursively creating the directory. Defaults to true on SDK 7.3.0+, defaults to false on older SDK versions.

Returns

Type
Boolean

# createFile

Availability
6.1.0
0.9.0
9.2.0
createFile() → Boolean

Creates a file at the path identified by this file object.

Note that if you write to a file that doesn't exist, the file is created automatically, so it is not necessary to call this method unless you want to explicitly create the file (for example, to create an empty file).

Returns true if the file was created successfully. Returns false if the file already exists, or if the file couldn't be created for some other reason.

Returns

Type
Boolean

# createTimestamp DEPRECATED

Availability
0.8
0.8
9.2.0
createTimestamp() → Number

DEPRECATED SINCE 7.3.0

Use createdAt instead.

Returns the creation timestamp for the file identified by this file object.

On Android, returns 0 for resource files.

Returns

Type
Number

# deleteDirectory

Availability
0.8
0.8
9.2.0
deleteDirectory([recursive]) → Boolean

Deletes the directory identified by this file object.

Returns true if the operation was successful. Does nothing if the file object does not identify a directory.

Parameters

Name Type Description
recursive Boolean

Pass true to recursively delete any directory contents.

Returns

Type
Boolean

# deleteFile

Availability
0.8
0.8
9.2.0
deleteFile() → Boolean

Deletes the file identified by this file object.

Returns true if the operation was successful.

Returns

Type
Boolean

# exists

Availability
0.8
0.8
9.2.0
exists() → Boolean

Returns true if the file or directory identified by this file object exists on the device.

Returns

Type
Boolean

# extension

Availability
0.8
0.8
9.2.0
extension() → String

Returns the extension for the file identified by this file object.

Returns

Type
String

# fireEvent

Availability
0.8
0.8
9.2.0
fireEvent(name[, event]) → void

Fires 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

# getDirectoryListing

Availability
0.8
0.8
9.2.0
getDirectoryListing() → Array<String>

Returns a listing of the directory identified by this file object, or null if this object doesn't identify a directory.

Returns

Type
Array<String>

# getParent DEPRECATED

Availability
0.8
0.8
9.2.0
getParent() → String | Titanium.Filesystem.File

DEPRECATED SINCE 7.0.0

Use the parent property to receive a File reference instead. If you wish to receive the path, use the nativePath property of that reference instead.

Returns the path of the parent directory holding the file identified by this file object, as a String (deprecated) or as a File object.

Prior to Titanium SDK 7.0.0, on iOS this method returned the path of the parent directory as a String. Since Titanium SDK 7.0.0, this method has been deprecated in favor of the parent property and will return a Titanium.Filesystem.File reference in the future as well.

Returns

Returns a String on iOS, a Titanium.Filesystem.File on Android

Type
String | Titanium.Filesystem.File

# getProtectionKey

Availability
4.1.0
9.2.0
getProtectionKey() → String

Returns the protection key value of this file object. Returns null if there's an error.

Returns

Type
String

# isDirectory

Availability
0.8
3.1.0
9.2.0
isDirectory() → Boolean

Returns true if this file object represents a directory.

Returns

Type
Boolean

# isFile

Availability
0.8
3.1.0
9.2.0
isFile() → Boolean

Returns true if this file object represents an ordinary file.

Returns

Type
Boolean

# modificationTimestamp DEPRECATED

Availability
0.8
0.8
9.2.0
modificationTimestamp() → Number

DEPRECATED SINCE 7.3.0

Use modifiedAt instead.

Returns the last modification time for this file.

On Android, returns 0 for resource files.

Returns

Type
Number

# modifiedAt

Availability
7.3.0
7.3.0
9.2.0
modifiedAt() → Date

Returns the last modification Date for the file identified by this file object.

On Android, returns a Date whose getTime() value is 0 for resource files.

Important: When developing for the Apple ecosystem, using this API requires the NSPrivacyAccessedAPICategoryFileTimestamp property set in the privacy manifest that was introduced in iOS 17. You can learn more about it here.

Returns

Type
Date

# move

Availability
0.8
0.8
9.2.0
move(newpath) → Boolean

Moves the file identified by this file object to another path.

Note that this method moves the stored file, but doesn't update this file object to point to the new path. To access the file after moving it, you must call getFile using the destination path to obtain a new file handle.

Parameters

Name Type Description
newpath String

New location for the file.

Returns

Type
Boolean

# open

Availability
0.8
0.8
9.2.0
open(mode) → Titanium.Filesystem.FileStream

Opens the file identified by this file object for random access.

You can open the file for reading, writing, or appending by specifying one of the MODE constants from Titanium.Filesystem: MODE_READ, MODE_WRITE, or MODE_APPEND.

The FileStream object returned by this call can be used to read from, write to, or append to the file, depending on what mode the file is opened in.

Parameters

Name Type Description
mode Number

Mode to open the file in: MODE_READ, MODE_WRITE, or MODE_APPEND.

Returns

Type
Titanium.Filesystem.FileStream

# read

Availability
0.8
0.8
9.2.0
read() → Titanium.Blob

Returns the contents of the file identified by this file object as a Blob.

Returns

Type
Titanium.Blob

# removeEventListener

Availability
0.8
0.8
9.2.0
removeEventListener(name, callback) → void

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);

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 addEventListener.

Returns

Type
void

# rename

Availability
0.8
0.8
9.2.0
rename(newname) → Boolean

Renames the file identified by this file object.

Returns true if the file was successfully renamed.

Fails if the destination is in a different directory than the current file. Use move to move a file to a different directory.

Note that this method renames the stored file, but doesn't update this file object to point to the new path. To access the file after renaming it, you must call getFile using the destination path to obtain a new file handle.

Parameters

Name Type Description
newname String

New name for the file.

Returns

Type
Boolean

# resolve

Availability
0.8
0.8
9.2.0
resolve() → String

Returns the fully-resolved native path associated with this file object.

On iOS, the path returned by this method is a plain file path, not a URL. It is suitable for use in native modules that need to access the file using native APIs.

On Android, the return value of resolve is a file:// URL, identical to the nativePath property.

Returns

Type
String

# setProtectionKey

Availability
4.1.0
9.2.0
setProtectionKey(fileProtectionType) → Boolean

Sets the protection key as an attribute to the file identified by this file object.

Returns true if successfully set. Returns false if failed.

Parameters

Name Type Description
fileProtectionType String

File protection type.

Returns

Type
Boolean

# spaceAvailable

Availability
0.8
0.8
9.2.0
spaceAvailable() → Number

Returns the amount of free space available on the device where the file identified by this file object is stored.

Free space is returned in bytes.

Important: When developing for the Apple ecosystem, using this API requires the NSPrivacyAccessedAPICategoryDiskSpace property set in the privacy manifest that was introduced in iOS 17. You can learn more about it here.

Returns

Type
Number

# write

Availability
0.8
0.8
9.2.0
write(data[, append]) → Boolean

Writes the specified data to the file identified by this file object.

If the append parameter is false or not specified, any existing data in the file is overwritten.

If append is true, the specified data is appended to the end of the file.

Parameters

Name Type Description
data String | Titanium.Filesystem.File | Titanium.Blob

Data to write, as a String, Blob or File object.

append Boolean

If true, append the data to the end of the file.

Returns

Type
Boolean

Contents