Directory

API Summary

createNewDir

Supported Platform(s)

Description

Create an empty directory.

deleteDirectory

Supported Platform(s)

Description

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

exists

Supported Platform(s)

Description

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

getFreeSpaceForRoot

Supported Platform(s)

Description

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

Returns

getParentDirectory

Supported Platform(s)

Description

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

getRootDirs

Supported Platform(s)

Description

Get a list of root directories.

Code Example(s)

<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>

listDirectories

Supported Platform(s)

Description

List all the directories that reside in a given directory.

listFiles

Supported Platform(s)

Description

List all the files that reside in a given directory.

rename

Supported Platform(s)

Description

Rename a given directory.

Properties:

Code Example(s)

<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>

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

Supported Platform(s)

Description

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

Returns

{
  "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

Supported Platform(s)

Description

Create an empty directory.

Returns

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

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

Supported Platform(s)

Description

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

Returns

{
  "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

Supported Platform(s)

Description

Determine whether a given directory exists or not.

Returns

{
  "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

Supported Platform(s)

Description

Get properties for a given directory.

Returns

{
  "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

Supported Platform(s)

Description

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

Returns

{
  "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(s)

<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

Supported Platform(s)

Description

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

Returns

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

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

Supported Platform(s)

Description

Rename a given directory.

Returns

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