FileTransfer API

This module allows you to upload and download files.

Original documentation: Cordova FileTransfer

Remark: Usage of cordova API needs http://tizen.org/privilege/filesystem.read privilege.

Remark: In order to access files, a proper privilege has to be defined additionally:

Since: 3.0

Table of Contents

Summary of Interfaces and Methods

Interface Method
FileUploadOptions
FileUploadResult
FileTransferError
FileTransfer
void upload (DOMString fileURL, DOMString server, optional FileUploadSuccessCallback? successCallback, optional FileTransferErrorCallback? errorCallback, optional FileUploadOptions? options, optional boolean? trustAllHosts)
void download (DOMString source, DOMString target, optional FileDownloadSuccessCallback? successCallback, optional FileTransferErrorCallback? errorCallback, optional boolean? trustAllHosts, optional FileDownloadOptions? options)
void abort ()
FileUploadSuccessCallback
FileDownloadSuccessCallback
void onsuccess (FileEntry file)
FileTransferErrorCallback

1. Type Definitions

1.1. FileUploadParams

A set of additional upload HTTP request parameters. 
  typedef object FileUploadParams;

Since: 3.0

The key / value type to pass in the HTTP request.

1.2. HeaderFields

A set of HTTP header fields. 
  typedef object HeaderFields;

Since: 3.0

The key / value type of each HTTP header field should be DOMString.

1.3. FileDownloadOptions

A set of download options. 
  typedef object FileDownloadOptions;

Since: 3.0

The key / value type of download options values. Currently only supports headers (such as Authorization (Basic Authentication), etc).

2. Interfaces

2.1. FileUploadOptions

A FileUploadOptions object can be passed to the FileTransfer objects upload method in order to specify additional parameters to the upload script 
  [Constructor(DOMString fileKey, DOMString fileName, DOMString mimeType, FileUploadParams params, HeaderFields headers,
               DOMString httpMethod)]
  interface FileUploadOptions {
    attribute DOMString fileKey;
    attribute DOMString fileName;
    attribute DOMString httpMethod;
    attribute DOMString mimeType;
    attribute FileUploadParams params;
    attribute boolean chunkedMode;
    attribute HeaderFields headers;
  };

Since: 3.0

Privilege level: public

Privilege: http://tizen.org/privilege/filesystem.read

Code example:

var fileURL;  /* Assume the variable fileURL contains a valid URL to a text file on the device. */

var win = function(r)
{
  console.log("Code = " + r.responseCode);
  console.log("Response = " + r.response);
  console.log("Sent = " + r.bytesSent);
};

var fail = function(error)
{
  alert("An error has occurred: Code = " + error.code);
  console.log("Upload error source " + error.source);
  console.log("Upload error target " + error.target);
};

var options = new FileUploadOptions();
options.fileKey = "file";
options.fileName = fileURL.substr(fileURL.lastIndexOf("/") + 1);
options.mimeType = "text/plain";

var params = {};
params.value1 = "test";
params.value2 = "param";

options.params = params;

var ft = new FileTransfer();
ft.upload(fileURL, encodeURI("http://some.server.com/upload.php"), win, fail, options);

Output example:

Code = 200
Response = OK
Sent = 1024

Constructors

Constructor (DOMString, DOMString, DOMString, FileUploadParams, HeaderFields, DOMString) 
FileUploadOptions(DOMString fileKey, DOMString fileName, DOMString mimeType, FileUploadParams params, HeaderFields headers,
                  DOMString httpMethod);

Since: 3.0

Code example:

/* Creates a FileUploadOptions objects */
var options = new FileUploadOptions("file", "doc.txt", "text/plain", null, null, "POST");

Attributes

  • DOMString fileKey
    The name of the form element. Defaults to file

    Since: 3.0

    Privilege level: public

    Privilege: http://tizen.org/privilege/filesystem.read

  • DOMString fileName
    The file name to use when saving the file on the server. Defaults to image.jpg.

    Since: 3.0

    Privilege level: public

    Privilege: http://tizen.org/privilege/filesystem.read

  • DOMString httpMethod
    The HTTP method to use - either PUT or POST. Defaults to POST.

    Since: 3.0

    Privilege level: public

    Privilege: http://tizen.org/privilege/filesystem.read

  • DOMString mimeType
    The mime type of the data to upload. Defaults to image/jpeg.

    Since: 3.0

    Privilege level: public

    Privilege: http://tizen.org/privilege/filesystem.read

  • FileUploadParams params
    A set of optional key/value pairs to pass in the HTTP request.

    Since: 3.0

    Privilege level: public

    Privilege: http://tizen.org/privilege/filesystem.read

  • boolean chunkedMode
    Whether to upload the data in chunked streaming mode. Defaults to true.

    Since: 3.0

    Privilege level: public

    Privilege: http://tizen.org/privilege/filesystem.read

  • HeaderFields headers
    A map of header name/header values. Use an array to specify more than one value.

    Since: 3.0

    Privilege level: public

    Privilege: http://tizen.org/privilege/filesystem.read

2.2. FileUploadResult

A FileUploadResult object is passed to the success callback of the FileTransfer object's upload() method. 
  [NoInterfaceObject] interface FileUploadResult {
    attribute long bytesSent;
    attribute long responseCode;
    attribute DOMString response;
    attribute HeaderFields headers;
  };

Since: 3.0

Privilege level: public

Privilege: http://tizen.org/privilege/filesystem.read

Attributes

  • long bytesSent
    The number of bytes sent to the server as part of the upload.

    Since: 3.0

    Privilege level: public

    Privilege: http://tizen.org/privilege/filesystem.read

  • long responseCode
    The HTTP response code returned by the server.

    Since: 3.0

    Privilege level: public

    Privilege: http://tizen.org/privilege/filesystem.read

  • DOMString response
    The HTTP response returned by the server.

    Since: 3.0

    Privilege level: public

    Privilege: http://tizen.org/privilege/filesystem.read

  • HeaderFields headers
    The HTTP response headers by the server.

    Since: 3.0

    Privilege level: public

    Privilege: http://tizen.org/privilege/filesystem.read

2.3. FileTransferError

A FileTransferError object is passed to an error callback when an error occurs. 
  interface FileTransferError {
    const short FILE_NOT_FOUND_ERR = 1;
    const short INVALID_URL_ERR = 2;
    const short CONNECTION_ERR = 3;
    const short ABORT_ERR = 4;
    const short NOT_MODIFIED_ERR = 5;
    attribute short code;
    attribute DOMString source;
    attribute DOMString target;
    attribute long http_status;
    attribute DOMString body;
    attribute DOMString _exception;
  };

Since: 3.0

Privilege level: public

Privilege: http://tizen.org/privilege/filesystem.read

Constants

  • FILE_NOT_FOUND_ERR
    File Not Found error.

    Since: 3.0



  • INVALID_URL_ERR
    Invalid URL error.

    Since: 3.0



  • CONNECTION_ERR
    Connection error.

    Since: 3.0



  • ABORT_ERR
    Abort error.

    Since: 3.0



  • NOT_MODIFIED_ERR
    Not Modified error.

    Since: 3.0



    • Attributes

    • short code
      One of the predefined error codes listed above.

      Since: 3.0

      Privilege level: public

      Privilege: http://tizen.org/privilege/filesystem.read

    • DOMString source
      URL to the source.

      Since: 3.0

      Privilege level: public

      Privilege: http://tizen.org/privilege/filesystem.read

    • DOMString target
      URL to the target.

      Since: 3.0

      Privilege level: public

      Privilege: http://tizen.org/privilege/filesystem.read

    • long http_status
      HTTP status code. This attribute is only available when a response code is received from the HTTP connection.

      Since: 3.0

      Privilege level: public

      Privilege: http://tizen.org/privilege/filesystem.read

    • DOMString body
      Response body. This attribute is only available when a response is received from the HTTP connection.

      Since: 3.0

      Privilege level: public

      Privilege: http://tizen.org/privilege/filesystem.read

    • DOMString _exception
      Either e.getMessage or e.toString

      Since: 3.0

      Privilege level: public

      Privilege: http://tizen.org/privilege/filesystem.read

    2.4. FileTransfer

    The FileTransfer object provides a way to upload files using an HTTP multi-part POST or PUT request, and to download files as well. 
      [Constructor()]
  interface FileTransfer {
    [TreatNonCallableAsNull] attribute ProgressCallback? onprogress;
    void upload(DOMString fileURL, DOMString server, optional FileUploadSuccessCallback? successCallback,
                optional FileTransferErrorCallback? errorCallback, optional FileUploadOptions? options,
                optional boolean? trustAllHosts);
    void download(DOMString source, DOMString target, optional FileDownloadSuccessCallback? successCallback,
                  optional FileTransferErrorCallback? errorCallback, optional boolean? trustAllHosts,
                  optional FileDownloadOptions? options);
    void abort();
  };

    Since: 3.0

    Privilege level: public

    Privilege: http://tizen.org/privilege/filesystem.read

    Constructors

    Constructor () 
    FileTransfer();

    Since: 3.0

    Code example:

    /* Creates a FileTransfer object. */
var file_transfer = new FileTransfer();

    Attributes

    • ProgressCallback onprogress [nullable]
      Called with a ProgressEvent whenever a new chunk of data is transferred.

      Since: 3.0

      Privilege level: public

      Privilege: http://tizen.org/privilege/filesystem.read

      Code example:

      var fileURL;  /* Must be a valid url, such as cdvfile://localhost/persistent/path/to/file.txt. */

var win = function(r)
{
  console.log("Success. File uploaded");
};

var fail = function(error)
{
  /* error.code == FileTransferError.ABORT_ERR */
  alert("An error has occurred: Code = " + error.code);
  console.log("Upload error source " + error.source);
  console.log("Upload error target " + error.target);
};

var ft = new FileTransfer();

ft.onprogress = function(event)
{
  console.log("Uploaded: " + event.loaded);
};

ft.upload(fileURL, encodeURI("http://some.server.com/upload.php"), win, fail);

      Output example:

      Uploaded: 512
Uploaded: 1024
Success. File uploaded

    Methods

    upload
    Sends a file to a server. 
    void upload(DOMString fileURL, DOMString server, optional FileUploadSuccessCallback? successCallback,
            optional FileTransferErrorCallback? errorCallback, optional FileUploadOptions? options,
            optional boolean? trustAllHosts);

    Since: 3.0

    Privilege level: public

    Privilege: http://tizen.org/privilege/filesystem.read

    Privilege: http://tizen.org/privilege/internet

    Parameters:

    • fileURL: Filesystem URL representing the file on the device. For backwards compatibility, this can also be the full path of the file on the device.
    • server: URL of the server to receive the file, as encoded by encodeURI().
    • successCallback [optional] [nullable]: A callback that is passed a FileUploadResult object.
    • errorCallback [optional] [nullable]: : A callback that executes if an error occurs retrieving the FileUploadResult. Invoked with a FileTransferError object.
    • options [optional] [nullable]: Optional parameters.
    • trustAllHosts [optional] [nullable]: Optional parameter, defaults to false. If set to true, it accepts all security certificates.

    Code example:

    var fileURL;  /* Must be a valid url, such as cdvfile://localhost/persistent/path/to/file.txt. */

var win = function(r)
{
  console.log("Code = " + r.responseCode);
  console.log("Response = " + r.response);
  console.log("Sent = " + r.bytesSent);
};

var fail = function(error)
{
  alert("An error has occurred: Code = " + error.code);
  console.log("Upload error source " + error.source);
  console.log("Upload error target " + error.target);
};

var ft = new FileTransfer();
ft.upload(fileURL, encodeURI("http://some.server.com/upload.php"), win, fail);

    Output example:

    Code = 200
Response = OK
Sent = 1024
    download
    Downloads a file from a server. 
    void download(DOMString source, DOMString target, optional FileDownloadSuccessCallback? successCallback,
              optional FileTransferErrorCallback? errorCallback, optional boolean? trustAllHosts,
              optional FileDownloadOptions? options);

    Since: 3.0

    Privilege level: public

    Privilege: http://tizen.org/privilege/filesystem.read

    Privilege: http://tizen.org/privilege/filesystem.write

    Parameters:

    • source: URL of the server to download the file, as encoded by encodeURI().
    • target: Filesystem url representing the file on the device. For backwards compatibility, this can also be the full path of the file on the device.
    • successCallback [optional] [nullable]: A callback that is passed a FileEntry object.
    • errorCallback [optional] [nullable]: A callback that executes if an error occurs when retrieving the FileEntry. Invoked with a FileTransferError object.
    • trustAllHosts [optional] [nullable]: Optional parameter, defaults to false. If set to true, it accepts all security certificates.
    • options [optional] [nullable]: Optional parameters, currently only supports headers (such as Authorization (Basic Authentication), etc).

    Code example:

    var fileURL;  /* Must be a valid url, such as cdvfile://localhost/persistent/path/to/file.txt. */

var fileTransfer = new FileTransfer();
var uri = encodeURI("http://some.server.com/download.php");

fileTransfer.download(uri, fileURL,
    function(entry)
    {
      console.log("Download complete: " + entry.toURL());
    },
    function(error)
    {
      console.log("Download error source " + error.source);
      console.log("Download error target " + error.target);
      console.log("Upload error code" + error.code);
    },
    false, {headers: {"Authorization": "Basic dGVzdHVzZXJuYW1lOnRlc3RwYXNzd29yZA=="}});

    Output example:

    Download complete: file:///home/owner/apps_rw/Gk6hf8hjk/tmp/file.txt
    abort
    Aborts an in-progress transfer. The onerror callback is passed a FileTransferError object which has an error code of FileTransferError.ABORT_ERR. 
    void abort();

    Since: 3.0

    Privilege level: public

    Privilege: http://tizen.org/privilege/filesystem.read

    Privilege: http://tizen.org/privilege/internet

    Code example:

    var fileURL;  /* Must be a valid url, such as cdvfile://localhost/persistent/path/to/file.txt. */

var win = function(r)
{
  console.log("Should not be called");
};

var fail = function(error)
{
  /* error.code == FileTransferError.ABORT_ERR */
  alert("An error has occurred: Code = " + error.code);
  console.log("Upload error source " + error.source);
  console.log("Upload error target " + error.target);
};

var ft = new FileTransfer();
ft.upload(fileURL, encodeURI("http://some.server.com/upload.php"), win, fail);
ft.abort();

    Output example:

    An error has occurred: Code = 4
Upload error source file:///home/owner/apps_rw/Gk6hf8hjk/tmp/file.txt
Upload error target http://some.server.com/file.txt

    2.5. FileUploadSuccessCallback

    The interface that defines a callback function which is called when an upload is successfully finished. 
      [Callback=FunctionOnly, NoInterfaceObject] interface FileUploadSuccessCallback {
    void onsuccess(FileUploadResult result);
  };

    Since: 3.0

    Methods

    onsuccess
    Called when upload is successfully finished. 
    void onsuccess(FileUploadResult result);

    Since: 3.0

    Remark: See the example.

    Parameters:

    • result: A result object that defines an upload result.

    2.6. FileDownloadSuccessCallback

    The interface that defines a callback function which is called when download is successfully finished. 
      [Callback=FunctionOnly, NoInterfaceObject] interface FileDownloadSuccessCallback {
    void onsuccess(FileEntry file);
  };

    Since: 3.0

    Methods

    onsuccess
    Called when download is successfully finished. 
    void onsuccess(FileEntry file);

    Since: 3.0

    Remark: See the example.

    Parameters:

    • file: An object that defines a downloaded file.

    2.7. FileTransferErrorCallback

    The interface that defines an error callback function which is called when an error occur. 
      [Callback=FunctionOnly, NoInterfaceObject] interface FileTransferErrorCallback {
    void onerror(FileTransferError error);
  };

    Since: 3.0

    Methods

    onerror
    Called when file transfer is finished with an error 
    void onerror(FileTransferError error);

    Since: 3.0

    Remark: See the example.

    Parameters:

    • error: An object that defines details of the error.

    3. Full WebIDL

    module FileTransfer {
  typedef object FileUploadParams;
  typedef object HeaderFields;
  typedef object FileDownloadOptions;
  [Constructor(DOMString fileKey, DOMString fileName, DOMString mimeType, FileUploadParams params, HeaderFields headers,
               DOMString httpMethod)]
  interface FileUploadOptions {
    attribute DOMString fileKey;
    attribute DOMString fileName;
    attribute DOMString httpMethod;
    attribute DOMString mimeType;
    attribute FileUploadParams params;
    attribute boolean chunkedMode;
    attribute HeaderFields headers;
  };
  [NoInterfaceObject] interface FileUploadResult {
    attribute long bytesSent;
    attribute long responseCode;
    attribute DOMString response;
    attribute HeaderFields headers;
  };
  interface FileTransferError {
    const short FILE_NOT_FOUND_ERR = 1;
    const short INVALID_URL_ERR = 2;
    const short CONNECTION_ERR = 3;
    const short ABORT_ERR = 4;
    const short NOT_MODIFIED_ERR = 5;
    attribute short code;
    attribute DOMString source;
    attribute DOMString target;
    attribute long http_status;
    attribute DOMString body;
    attribute DOMString _exception;
  };
  [Constructor()]
  interface FileTransfer {
    [TreatNonCallableAsNull] attribute ProgressCallback? onprogress;
    void upload(DOMString fileURL, DOMString server, optional FileUploadSuccessCallback? successCallback,
                optional FileTransferErrorCallback? errorCallback, optional FileUploadOptions? options,
                optional boolean? trustAllHosts);
    void download(DOMString source, DOMString target, optional FileDownloadSuccessCallback? successCallback,
                  optional FileTransferErrorCallback? errorCallback, optional boolean? trustAllHosts,
                  optional FileDownloadOptions? options);
    void abort();
  };
  [Callback=FunctionOnly, NoInterfaceObject] interface FileUploadSuccessCallback {
    void onsuccess(FileUploadResult result);
  };
  [Callback=FunctionOnly, NoInterfaceObject] interface FileDownloadSuccessCallback {
    void onsuccess(FileEntry file);
  };
  [Callback=FunctionOnly, NoInterfaceObject] interface FileTransferErrorCallback {
    void onerror(FileTransferError error);
  };
};
    Except as noted, this content - excluding the Code Examples - is licensed under Creative Commons Attribution 3.0 and all of the Code Examples contained herein are licensed under BSD-3-Clause.
    For details, see the Content License.