Directory

The Directory object provides functions for interacting with directories on the file system.

See also blackberry.io.file


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.dir" /> 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.


Properties

Object appDirs

Functions

static void blackberry.io.dir.createNewDir (path : String)


Create an empty directory.


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


Parameters
path path location of the new directory. The name of the new directory should be included as parts of the path.

static void blackberry.io.dir.deleteDirectory (path : String, [recursive : Boolean])


Delete a given directory. The directory has to be empty unless the recursive flag is set to true.


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


Parameters
path path of the directory to be deleted.
recursive flag to decide if all contents should be deleted

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


Determine whether a given directory exists or not. Returns true if the path exists and points to a directory, false otherwise.


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


Parameters
path path location of the directory.

static Number blackberry.io.dir.getFreeSpaceForRoot (rootPath : String)


Get the amount of free space available in the specified root.


Supported Platforms
 - BlackBerry OS 5.0+
 - Ripple Emulator


Parameters
rootPath Root path location to determine free space for.

Return:

The amound of free space availalble in the specified root.


static String blackberry.io.dir.getParentDirectory (path : String)


Returns the path location of the directory that the give file or directory resides in.


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


Parameters
path Path of the directory or file.

static String[] blackberry.io.dir.getRootDirs ()


Get a list of root directories.


Supported Platforms
 - BlackBerry OS 5.0+
 - Ripple Emulator


Code Example:
<script type="text/javascript">
  var i;
  var root = blackberry.io.dir.getRootDirs();
  // Loop through all the files in the first root directory and display them
  var files = blackberry.io.dir.listFiles(root[0]);
  for (i = 0; i < files.length; i++) {
    alert(files[i]);
  }
  var roots = blackberry.io.dir.getRootDirs();
  for (i = 0; i < roots.length; i++) {
    alert("Free space on '" + roots[i] + "' is " + blackberry.io.dir.getFreeSpaceForRoot(roots[i]) + " bytes");
  }
</script>

static String[] blackberry.io.dir.listDirectories (path : String)


List all the directories that reside in a given directory.


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


Parameters
path path location of the directory.

static String[] blackberry.io.dir.listFiles (path : String)


List all the files that reside in a given directory.


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


Parameters
path Path location of the directory.

static void blackberry.io.dir.rename (path : String, newDirectoryName : String)


Rename a given directory.


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


Parameters
path path location of the directory to be renamed.
newDirectoryName the new name for the directory.

Properties

static readonly Object appDirs


Gets the full paths of application storage folder and sub-folders under "shared". Paths are in the form of file:// URL

The application storage folder is created when you first access blackberry.io.dir.appDirs. This directory is a convenient location to store application-specific data that can only be accessed by the application.

The "shared" folder is the parent directory to the sub-folders such as camera and music, which can be accessed by all applications. These sub-folders can also be accessed when the BlackBerry PlayBook has "File Sharing" turned on. The access_shared permission must be set in order to reference any files/folders under "shared".


Supported Platforms
 - BlackBerry PlayBook 1.0+
 - Ripple Emulator


Code Example:
<script type="text/javascript">
  var dirs = blackberry.io.dir.appDirs;
	
  alert('Application storage folder path:' + dirs.app.storage.path);
		
  // access_shared permission must be added in order to access shared folder
  for (var subfolder in dirs.shared) {
      alert(subfolder + '.path:' + eval('dirs.shared.' + subfolder + '.path'));
  }

  var musicDir = dirs.shared.music.path;
  alert('Music folder path:' + musicDir);
</script>

URI Functions

http://localhost:8472/blackberry/io/dir/appDirs


Gets the full paths of application storage folder and sub-folders under "shared". Paths are in the form of file:// URL

The application storage folder is created when you first invoke this call. This directory is a convenient location to store application-specific data that can only be accessed by the application.

The "shared" folder is the parent directory to the sub-folders such as camera and music, which can be accessed by all applications. These sub-folders can also be accessed when the BlackBerry PlayBook has "File Sharing" turned on. The access_shared permission must be set in order to reference any files/folders under "shared".


Supported Platforms
 - BlackBerry PlayBook 1.0+


Return:
 {
  "data" : {
    "app": {
      "storage" : {
        "path" : "file:///accounts/1000/appdata/WebWorksAppTemplate.testa3NBcHBUZW1wbGF0ZSAgICA/data"
      }
    },
    "shared": {
      "bookmarks": {
        "path" : "file:///accounts/1000/appdata/WebWorksAppTemplate.testa3NBcHBUZW1wbGF0ZSAgICA/shared/bookmarks"
      },
      "books": {
        "path" : "file:///accounts/1000/appdata/WebWorksAppTemplate.testa3NBcHBUZW1wbGF0ZSAgICA/shared/books"
      },
      "camera": {
        "path" : "file:///accounts/1000/appdata/WebWorksAppTemplate.testa3NBcHBUZW1wbGF0ZSAgICA/shared/camera"
      },
      "documents": {
        "path" : "file:///accounts/1000/appdata/WebWorksAppTemplate.testa3NBcHBUZW1wbGF0ZSAgICA/shared/documents"
      },
      "downloads": {
        "path" : "file:///accounts/1000/appdata/WebWorksAppTemplate.testa3NBcHBUZW1wbGF0ZSAgICA/shared/downloads"
      },
      "misc": {
        "path" : "file:///accounts/1000/appdata/WebWorksAppTemplate.testa3NBcHBUZW1wbGF0ZSAgICA/shared/misc"
      },
      "music": {
        "path" : "file:///accounts/1000/appdata/WebWorksAppTemplate.testa3NBcHBUZW1wbGF0ZSAgICA/shared/music"
      },
      "photos": {
        "path" : "file:///accounts/1000/appdata/WebWorksAppTemplate.testa3NBcHBUZW1wbGF0ZSAgICA/shared/photos"
      },
      "print": {
        "path" : "file:///accounts/1000/appdata/WebWorksAppTemplate.testa3NBcHBUZW1wbGF0ZSAgICA/shared/print"
      },
      "videos": {
        "path" : "file:///accounts/1000/appdata/WebWorksAppTemplate.testa3NBcHBUZW1wbGF0ZSAgICA/shared/videos"
      },
      "voice": {
        "path" : "file:///accounts/1000/appdata/WebWorksAppTemplate.testa3NBcHBUZW1wbGF0ZSAgICA/shared/voice"
      }
    }
  }
} 

http://localhost:8472/blackberry/io/dir/create


Create an empty directory.


Supported Platforms
 - BlackBerry PlayBook 1.0+


Parameters
path path of the directory to be created, the name of the new directory should be included as parts of the path, specified in the form of file:/// URL

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

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


Delete a given directory. The directory has to be empty unless the recursive flag is set to true.


Supported Platforms
 - BlackBerry PlayBook 1.0+


Parameters
path path of the directory to be deleted, specified in the form of file:/// URL
recursive flag to decide if all contents should be deleted, defaulted to false

Return:
 {
  "data" : {
    "path": "<path that was passed>",
    "recursive" : the boolean that was passed (false if "recursive" was not specified)
  }
} 

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


Determine whether a given directory exists or not.


Supported Platforms
 - BlackBerry PlayBook 1.0+


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

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

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


Get properties for a given directory.


Supported Platforms
 - BlackBerry PlayBook 1.0+


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

Return:
 {
  "data" : {
    "path": "<path that was passed>",
    "name": "<name of the directory>", // only defined if "code" is 0
    "spaceAvailable": <space available for use at this directory, in bytes>, // only defined if "code" is 0
    "isEmpty": true (if directory does not contain files or sub-directories) or false (if directory contains files or sub-directories), // only defined if "code" is 0
  }
} 

http://localhost:8472/blackberry/io/dir/list


List all the files and subdirectories that reside in a given directory.


Supported Platforms
 - BlackBerry PlayBook 1.0+


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

Return:
 {
  "data" : {
    "path": "<path that was passed>",
    "directories" : [
      "folder1",
      "folder2" ],  // only defined if "code" is 0
    "files" : [
      "5-snowflakes.swf",
      "chromeBookmarks.html",
      "test.txt ] // 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 dirPath = encodeURI(blackberry.io.dir.appDirs.app.storage.path + '/app_settings'); 
  $.ajax({
     url: "http://localhost:8472/blackberry/io/dir/list?path=" + filePath,
     success: function(result, textStatus, jqXHR){
       try {
          var resultObj = JSON.parse(result);
          alert("code=" + resultObj.code + " msg=" + resultObj.msg);

          if (resultObj.code == 0) {
             for (var i = 0; i < resultObj.data.directories.length; i++) {
                alert('Sub-directory[' + i + ']: ' + resultObj.data.directories[i]);
             }

             for (var i = 0; i < resultObj.data.files.length; i++) {
                alert('File[' + i + ']: ' + resultObj.data.files[i]);
             }
          }
       } catch (e) {
          alert('e.message = ' + e.message);
       }				
     }
  });
</script>

http://localhost:8472/blackberry/io/dir/parent


Gets the path location of the directory that the give file or directory resides in.


Supported Platforms
 - BlackBerry PlayBook 1.0+


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

Return:
 {
  "data" : {
    "path": "<path that was passed>",
    "directory" : "<parent directory>" // only defined if "code" is 0
  }
} 

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


Rename a given directory.


Supported Platforms
 - BlackBerry PlayBook 1.0+


Parameters
path path of the directory, specified in the form of file:/// URL
newDirectoryName new name for the directory

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

Documentation generated by JsDoc Toolkit 2.4.0 on Mon Feb 11 2013 14:51:06 GMT-0500 (EST)