# Titanium.Filesystem.File
Object representing a path to a file or directory in the device's persistent storage.
# 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
# executable READONLY
true
if the file is executable.
On iOS, this property exists but is always false
.
# hidden
Set to true
if the file is hidden.
On iOS, this property exists but is always false
.
# nativePath READONLY
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
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.
# remoteBackup
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
# symbolicLink READONLY
true
if the file identified by this object is a symbolic link.
# Methods
# append
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
# copy
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
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.
Returns
- Type
- Date
# createDirectory
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 |
Returns
- Type
- Boolean
# createFile
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
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
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 |
Returns
- Type
- Boolean
# deleteFile
Deletes the file identified by this file object.
Returns true
if the operation was successful.
Returns
- Type
- Boolean
# exists
Returns true
if the file or directory identified by this file object exists on the device.
Returns
- Type
- Boolean
# extension
Returns the extension for the file identified by this file object.
Returns
- Type
- String
# getDirectoryListing
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
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
Returns the protection key value of this file object.
Returns null
if there's an error.
Returns
- Type
- String
# isDirectory
Returns true
if this file object represents a directory.
Returns
- Type
- Boolean
# isFile
Returns true
if this file object represents an ordinary file.
Returns
- Type
- Boolean
# modificationTimestamp DEPRECATED
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
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.
Returns
- Type
- Date
# move
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
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: |
Returns
# read
Returns the contents of the file identified by this file object as a Blob
.
Returns
- Type
- Titanium.Blob
# rename
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
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
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
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.
Returns
- Type
- Number
# write
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, |
append | Boolean | If |
Returns
- Type
- Boolean