File

The File object provides functions for interacting with the file system.

See also blackberry.io.dir


Supported Platform(s)

- BlackBerry OS 5.0+
- BlackBerry PlayBook 1.0+
- Ripple Emulator
View Supported Platform Table

Configuration Document Settings

To use all of the API described for this object, you must ensure the following settings are in your configuration document:

You must declare the feature element(s) below in your configuration document:

Feature IDBB5.0BB6.0BB7.0PB1.0PB2.0BB10Ripple
<feature id="blackberry.io.file" /> Y Y Y Y Y  Y

Permission Elements (PlayBook and BlackBerry 10+)
Declaring the permission element(s) below in your configuration document is optional.
- <rim:permit>access_shared</rim:permit>
Any references to files/directories under "shared" folder (e.g. music) requires this permission to be set.

Functions

static void blackberry.io.file.copy (sourcePath : String, targetPath : String)


Copy a file to a given destination.


Supported Platforms
 - BlackBerry OS 5.0+
 - BlackBerry PlayBook 1.0+
 - Ripple Emulator


Parameters
sourcePath local storage file path to the file to be copied
targetPath local storage file path to the new copied file. The name of the copied file should be specified at the end of the targetPath.

static void blackberry.io.file.deleteFile (path : String)


Delete a given file.


Supported Platforms
 - BlackBerry OS 5.0+
 - BlackBerry PlayBook 1.0+
 - Ripple Emulator


Parameters
path local storage file path to the file to be deleted

static Boolean blackberry.io.file.exists (path : String)


Check whether or not a given file exists.


Supported Platforms
 - BlackBerry OS 5.0+
 - BlackBerry PlayBook 1.0+
 - Ripple Emulator


Parameters
path local storage file path to the file

static blackberry.io.file.FileProperties blackberry.io.file.getFileProperties (path : String)


Get the FileProperties object for a given file.


Supported Platforms
 - BlackBerry OS 5.0+
 - BlackBerry PlayBook 1.0+
 - Ripple Emulator


Parameters
path local storage file path to the file

static Boolean blackberry.io.file.open (path : String)


Open the specified file with the registered content handler.


Supported Platforms
 - BlackBerry OS 5.0+
 - BlackBerry PlayBook 1.0+
 - Ripple Emulator


Parameters
path file path to the file to be opened.

static void blackberry.io.file.readFile (path : String, onFileOpened: function(fullPath : String, blobData : Blob), [async : Boolean])


Reads in a file from the local file system.


Supported Platforms
 - BlackBerry OS 5.0+
 - BlackBerry PlayBook 1.0+
 - Ripple Emulator


Parameters
path local storage file path to the file to be opened into a Blob
onFileOpened callback function to call on completion of loading the file from the file system.

fullPath: full path of the file that was just opened
blobData: blob that contains the file's contents
async a flag specifying if the call to read should be asynchronous or synchronous. If this parameter is not supplied the default of true will be used.

static void blackberry.io.file.rename (path : String, newFileName : String)


Rename a given file.


Supported Platforms
 - BlackBerry OS 5.0+
 - BlackBerry PlayBook 1.0+
 - Ripple Emulator


Parameters
path local storage file path to the file
newFileName the new file name.

static void blackberry.io.file.saveFile (path : String, data : Blob)


Save a Blob to the local file system.


Supported Platforms
 - BlackBerry OS 5.0+
 - BlackBerry PlayBook 1.0+
 - Ripple Emulator


Parameters
path Local storage file path to the file that is going to store the data
data The Blob to be saved.

Code Example: 
<script type="text/javascript">
  var xmlString = "<test>IO functions</test>";
  var filePath = "file:///store/home/user/sample.xml";
  var parser = new DOMParser();
  var doc = parser.parseFromString(xmlString, "text/xml");
  var blob_data = blackberry.utils.documentToBlob(doc);
     
  blackberry.io.file.saveFile(filePath, blob_data);
                
  if (blackberry.io.file.exists(filePath)) {
    blackberry.io.file.copy(filePath, "file:///SDCard/myxmlfile2.xml");
    blackberry.io.file.readFile(filePath,handleOpenedFile);
  }
     
  function handleOpenedFile(fullPath, blobData) {
    alert("file opened was: " + fullPath + " which contained " + blobData.length + " bytes");
  }
</script>

URI Functions

http://localhost:8472/blackberry/io/file/copy


Copy a file to a given destination.


Supported Platforms
 - BlackBerry PlayBook 1.0+


Parameters
path path to the file to be copied, specified in the form of file:/// URL
targetPath path to the newly copied file, the name of the copied file should be specified at the end of the targetPath, in the form of file:/// URL

Return: 
 {
  "data" : {
    "path" : "<path that was passed>",
    "targetPath" : "<targetPath that was passed>"
  }
}

http://localhost:8472/blackberry/io/file/delete


Delete the specified file.


Supported Platforms
 - BlackBerry PlayBook 1.0+


Parameters
path path to the file to be deleted, specified in the form of file:/// URL

Return: 
 {
  "data" : {
    "path" : "<path that was passed>"
  }
}

http://localhost:8472/blackberry/io/file/exists


Determine whether a given file exists or not.


Supported Platforms
 - BlackBerry PlayBook 1.0+


Parameters
path path of the file, specified in the form of file:/// URL

Return: 
 {
  "data" : {
    "path": "<path that was passed>",
    "exists" : true if the path exists and points to a file, false otherwise
  }
}

http://localhost:8472/blackberry/io/file/get


Get properties for a given file.


Supported Platforms
 - BlackBerry PlayBook 1.0+


Parameters
path path to the file, specified in the form of file:/// URL

Return: 
 {
  "data" : {
    "path" : "<path that was passed>",
    "dateCreated" : "<file creation date, in number of milliseconds since UTC>", // only defined if "code" is 0
    "dateModified" : "<file modification date, in number of milliseconds since UTC>", // only defined if "code" is 0
    "directory" : "<path of directory that contains this file>", // only defined if "code" is 0
    "fileExtension" : "<file extension>", // only defined if "code" is 0
    "isHidden" : true (if file is hidden) or false (if file is not hidden), // only defined if "code" is 0
    "size" : <file size in bytes> // only defined if "code" is 0
  }
}


Code Example: 
<script type="text/javascript" src="js/jquery-1.4.2.js"></script>
<script type="text/javascript">
  var filePath = encodeURI(blackberry.io.dir.appDirs.app.storage.path + '/myfile.txt'); 
  var reviverFn = function(key, value) {
     // construct JS Date object from number of milliseconds since UTC
     if (key.toLowerCase().indexOf('date') != -1) {
        return new Date(value);
     } else {
        return value;
     }
  };

  // inspect properties for this file
  $.ajax({
     url: "http://localhost:8472/blackberry/io/file/get?path=" + filePath,
     success: function(result, textStatus, jqXHR){
       try {
          var resultObj = JSON.parse(result, reviverFn);
          alert("code=" + resultObj.code + " msg=" + resultObj.msg);

          for (var f in resultObj.data) {
             alert(f + ':' + resultObj.data[f]);
          }
       } catch (e) {
          alert('e.message = ' + e.message);
       }                
     }
  });
</script>

http://localhost:8472/blackberry/io/file/open


Open the specified file with the registered content handler.


Supported Platforms
 - BlackBerry PlayBook 1.0+


Parameters
path path to the file to be opened, specified in the form of file:/// URL

Return: 
 {
  "data" : {
    "path" : "<path that was passed>"
  }
}

http://localhost:8472/blackberry/io/file/rename


Rename a given file.


Supported Platforms
 - BlackBerry PlayBook 1.0+


Parameters
path path to the file, specified in the form of file:/// URL
newFileName new file name

Return: 
 {
  "data" : {
    "path" : "<path that was passed>",
    "newFileName" : "<newFileName that was passed>"
  }
}

Documentation generated by JsDoc Toolkit 2.4.0 on Sun Dec 30 2012 18:15:37 GMT-0500 (EST)