Framework v4 BETA

File

This plugin implements a File API allowing read/write access to files residing on the device.

The File class implements static convenience functions to access files and directories.

Example:

import { File } from '@ionic-native/file/ngx';

constructor(private file: File) { }

...

this.file.checkDir(this.file.dataDirectory, 'mydir').then(_ => console.log('Directory exists')).catch(err =>
  console.log('Directory doesn't exist'));

This plugin is based on several specs, including : The HTML5 File API http: //www.w3.org/TR/FileAPI/ The (now-defunct) Directories and System extensions Latest: http: //www.w3.org/TR/2012/WD-file-system-api-20120417/ Although most of the plugin code was written when an earlier spec was current: http: //www.w3.org/TR/2011/WD-file-system-api-20110419/ It also implements the FileWriter spec : http: //dev.w3.org/2009/dap/file-system/file-writer.html @interfaces IFile Entry DirectoryEntry DirectoryReader FileSystem

Repo: https://github.com/apache/cordova-plugin-file

Installation

  1. Install the Cordova and Ionic Native plugins:
    shell
    $ ionic cordova plugin add cordova-plugin-file
    $ npm install --save @ionic-native/[email protected]
    
  2. Add this plugin to your app's module

Supported Platforms

  • Android
  • Browser
  • iOS
  • macOS
  • Windows

Usage

null


Instance Members

getDirectory

Get a directory

Parameters

directoryEntry

Type: DirectoryEntry
See DirectoryEntry table below

directoryName

Type: string
Directory name

flags

Type: Flags
See Flags table below


applicationDirectory

Read-only directory where the application is installed.


getFile

Get a file

Parameters

directoryEntry

Type: DirectoryEntry
See DirectoryEntry table below

fileName

Type: string
File name

flags

Type: Flags
See Flags table below


cacheDirectory

Cached files that should survive app restarts. Apps should not rely on the OS to delete files in here.


applicationStorageDirectory

Read-only directory where the application is installed.


listDir

List files and directory from a given path.

Parameters

path

Type: string
Base FileSystem. Please refer to the iOS and Android filesystems above

dirName

Type: string
Name of directory


cordovaFileError


copyFile

Copy a file in various methods. If file exists, will fail to copy.

Parameters

path

Type: string
Base FileSystem. Please refer to the iOS and Android filesystem above

fileName

Type: string
Name of file to copy

newPath

Type: string
Base FileSystem of new location

newFileName

Type: string
New name of file to copy to (leave blank to remain the same)


copyDir

Copy a directory in various methods. If destination directory exists, will fail to copy.

Parameters

path

Type: string
Base FileSystem. Please refer to the iOS and Android filesystems above

dirName

Type: string
Name of directory to copy

newPath

Type: string
Base FileSystem of new location

newDirName

Type: string
New name of directory to copy to (leave blank to remain the same)


checkFile

Check if a file exists in a certain path, directory.

Parameters

path

Type: string
Base FileSystem. Please refer to the iOS and Android filesystem above

file

Type: string
Name of file to check


checkDir

Check if a directory exists in a certain path, directory.

Parameters

path

Type: string
Base FileSystem. Please refer to the iOS and Android filesystem above

dir

Type: string
Name of directory to check


readAsArrayBuffer

Read file and return data as an ArrayBuffer.

Parameters

path

Type: string
Base FileSystem. Please refer to the iOS and Android filesystem above

file

Type: string
Name of file, relative to path.


externalApplicationStorageDirectory

Android: the application space on external storage.


dataDirectory

Where to put app-specific data files.


documentsDirectory

iOS: Files private to the app, but that are meaningful to other applications (e.g. Office files)


createFile

Creates a new file in the specific path. The replace boolean value determines whether to replace an existing file with the same name. If an existing file exists and the replace value is false, the promise will fail and return an error.

Parameters

path

Type: string
Base FileSystem. Please refer to the iOS and Android filesystem above

fileName

Type: string
Name of file to create

replace

Type: boolean
If true, replaces file with same name. If false returns error


createDir

Creates a new directory in the specific path. The replace boolean value determines whether to replace an existing directory with the same name. If an existing directory exists and the replace value is false, the promise will fail and return an error.

Parameters

path

Type: string
Base FileSystem. Please refer to the iOS and Android filesystem above

dirName

Type: string
Name of directory to create

replace

Type: boolean
If true, replaces file with same name. If false returns error


readAsText

Read the contents of a file as text.

Parameters

path

Type: string
Base FileSystem. Please refer to the iOS and Android filesystem above

file

Type: string
Name of file, relative to path.


externalDataDirectory

Android: Where to put app-specific data files on external storage.


externalCacheDirectory

Android: the application cache on external storage.


readFile

Parameters

path

Type: string
null

file

Type: string
null

readAs

null


getFreeDiskSpace

Get free disk space in Bytes


externalRootDirectory

Android: the external storage (SD card) root.


removeFile

Removes a file from a desired location.

Parameters

path

Type: string
Base FileSystem. Please refer to the iOS and Android filesystem above

fileName

Type: string
Name of file to remove


moveFile

Move a file to a given path.

Parameters

path

Type: string
Base FileSystem. Please refer to the iOS and Android filesystem above

fileName

Type: string
Name of file to move

newPath

Type: string
Base FileSystem of new location

newFileName

Type: string
New name of file to move to (leave blank to remain the same)


moveDir

Move a directory to a given path.

Parameters

path

Type: string
The source path to the directory

dirName

Type: string
The source directory name

newPath

Type: string
The destination path to the directory

newDirName

Type: string
The destination directory name


removeRecursively

Removes all files and the directory from a desired location.

Parameters

path

Type: string
Base FileSystem. Please refer to the iOS and Android filesystem above

dirName

Type: string
Name of directory


readAsDataURL

Read file and return data as a base64 encoded data url. A data url is of the form: data: [][;base64],

Parameters

path

Type: string
Base FileSystem. Please refer to the iOS and Android filesystem above

file

Type: string
Name of file, relative to path.


readAsBinaryString

Read file and return data as a binary data.

Parameters

path

Type: string
Base FileSystem. Please refer to the iOS and Android filesystem above

file

Type: string
Name of file, relative to path.


removeDir

Remove a directory at a given path.

Parameters

path

Type: string
The path to the directory

dirName

Type: string
The directory name


resolveDirectoryUrl

Resolves a local directory url

Parameters

directoryUrl

Type: string
directory system url


resolveLocalFilesystemUrl

Resolves a local file system URL

Parameters

fileUrl

Type: string
file system url


sharedDirectory

BlackBerry10: Files globally available to all apps


syncedDataDirectory

iOS: Holds app-specific files that should be synced (e.g. to iCloud).


tempDirectory

iOS: Temp directory that the OS can clear at will.


writeExistingFile

Write to an existing file.

Parameters

path

Type: string
Base FileSystem. Please refer to the iOS and Android filesystem above

fileName

Type: string
path relative to base path

text

content or blob to write


writeFile

Write a new file to the desired location.

Parameters

path

Type: string
Base FileSystem. Please refer to the iOS and Android filesystem above

fileName

Type: string
path relative to base path

text

content, blob or ArrayBuffer to write

options

Type: IWriteOptions
See IWriteOptions table below


DirectoryEntry

filesystem

Type: reference
The file system on which the entry resides.

fullPath

Type: intrinsic
The full absolute path from the root to the entry.

isDirectory

Type: intrinsic
Entry is a directory.

isFile

Type: intrinsic
Entry is a file.

name

Type: intrinsic
The name of the entry, excluding the path leading to it.

nativeURL

Type: intrinsic
an alternate URL which can be used by native webview controls, for example media players.

DirectoryReader

hasReadEntries

Type: intrinsic
undefined

localURL

Type: intrinsic
undefined

Entry

filesystem

Type: reference
The file system on which the entry resides.

fullPath

Type: intrinsic
The full absolute path from the root to the entry.

isDirectory

Type: intrinsic
Entry is a directory.

isFile

Type: intrinsic
Entry is a file.

name

Type: intrinsic
The name of the entry, excluding the path leading to it.

nativeURL

Type: intrinsic
an alternate URL which can be used by native webview controls, for example media players.

FileEntry

filesystem

Type: reference
The file system on which the entry resides.

fullPath

Type: intrinsic
The full absolute path from the root to the entry.

isDirectory

Type: intrinsic
Entry is a directory.

isFile

Type: intrinsic
Entry is a file.

name

Type: intrinsic
The name of the entry, excluding the path leading to it.

nativeURL

Type: intrinsic
an alternate URL which can be used by native webview controls, for example media players.

FileSystem

name

Type: intrinsic
This is the name of the file system. The specifics of naming filesystems is unspecified, but a name must be unique across the list of exposed file systems.

root

Type: reference
The root directory of the file system.

Flags

create

Type: intrinsic
Used to indicate that the user wants to create a file or directory if it was not previously there. optional

exclusive

Type: intrinsic
By itself, exclusive must have no effect. Used with create, it must cause getFile and getDirectory to fail if the target path already exists. optional

IFile

Blob

Type: reflection
undefined

end

Type: intrinsic
undefined

lastModified

Type: intrinsic
Last modified date

lastModifiedDate

Type: intrinsic
Last modified date

localURL

Type: intrinsic
undefined

name

Type: intrinsic
Name of the file, without path information

size

Type: intrinsic
Size in bytes

start

Type: intrinsic
undefined

type

Type: intrinsic
File mime type

IWriteOptions

append

Type: intrinsic
undefined optional

replace

Type: intrinsic
undefined optional

truncate

Type: intrinsic
undefined optional

LocalFileSystem

PERSISTENT

Type: intrinsic
Used for storage that should not be removed by the user agent without application or user permission.

TEMPORARY

Type: intrinsic
Used for storage with no guarantee of persistence.

Metadata

modificationTime

Type: reference
This is the time at which the file or directory was last modified.

size

Type: intrinsic
The size of the file, in bytes. This must return 0 for directories.

RemoveResult

fileRemoved

Type: reference
undefined

success

Type: intrinsic
undefined

Window

PERSISTENT

Type: intrinsic
Used for storage that should not be removed by the user agent without application or user permission.

TEMPORARY

Type: intrinsic
Used for storage with no guarantee of persistence.