Adobe AIR Development

[#1]

Here is an overview of the BlackBerry® PlayBook™ application sandbox file system layout for the latest release 0.9.2 

Applications will be run in the directory we call "sandbox". Name of this directory is irrelevant and cannot be relied on.  An application should not attempt to access any files outside of this directory. Sandbox is the default "working directory".

The structure is

•   app
•   data
•   tmp
•   logs
•   shared

All except shared are app's private directories, only the app can read/write files there.

The "app" directory is the link to where application files are installed (what was packaged in the bar file), these files are read only. For Adobe® AIR®, application files will be in subdirectory "air" (i.e. app/air/your_file).

The private data directory is "data". Application has full access to this directory (read/write). The $HOME env var is set to this directory. To initiate the sandbox app may copy files from "app" to "data" (for example user modifiable config files) on the first run.

The "tmp" directory can be used to create temporary files, application should take care of cleaning these files, but system may remove them at any time app is not running - so it cannot be used to persist data, only "data" directory should be used for this.

The "logs" is used for development, application stdin and stdout is redirected to logs/log file, as well as "core" files will be created there if app crashes.

The "shared" is link to common location where all apps share files. It has the following structure:

• photos
• bookmarks
• misc
• books
• documents
• voice
• downloads
• music
• videos

These directories map to the File class as:

Alias	Path
File.applicationDirectory	(appname)/app/air
File.applicationStorageDirectory	(appname)/data
File.desktopDirectory	(appname)/shared/documents
File.documentsDirectory	(appname)/shared/documents
File.userDirectory	(appname)/

Users must grant your application access to the above folders within the shared directory. To request access, you will need to include the following snippet in your blackberry-tablet.xml file. 

 <qnx>

    <action>access_shared</action>

 </qnx>

More info in regards to gaining access to APIs that have limited functionaliy, please see Accessing restricted functionality

Best practices for application data storage

Even though the file structure within the application's sandbox is predefined, it does have implications on the application's data when it is uninstalled from the device. Data that is stored in any sandbox subdirectories by the application is deleted when the application is uninstalled, with the exception of data stored within the shared directory. Moreover. if data is stored in the shared directory with a '.' prefixed to the name, the OS treats the data as a hidden file. Also, the chance of filename collisions increase among applications that write to the same shared file space.

It is recommended that applications persist data in their own application storage directory (i.e. data or tmp subdirectory), instead of storing the data within the shared subdirectory. Note that the data does not get removed within the application's data directory when the application is upgraded to a newer version.

[#2]

As I noted in this post some of this info has changed in 0.9.3, though it's unclear whether that represents the direction things are going, a temporary glitch in that release, or something else.  Of note, the values assigned to desktopDirectory and userDirectory have basically been swapped.  Neither the values in 0.9.2 nor the ones in 0.9.3 make any sense for that, so I'd advise people to avoid either for now.  If you want to use other subdirectories of the shared folder, the best bet might be a relative path as in File.documentsDirectory.resolvePath('../voice').

Also note that /shared/photos should be included in the above list.

[#3]

Article will be updated shorty with the current shared paths.

[#4]

Please note that the documentation is still incorrect as of 2011 April 13.  The fix I described in my earlier comment has not been applied yet.  The incorrect information comes from my original post, where I seem to have reversed userDirectory and desktopDirectory.

The correct information for any version from 0.9.2 through 0.9.4, and for 1.0, is listed in the post I linked to in my earlier comment.  I'll reproduce it here:

Alias	Path
File.applicationDirectory	/accounts/1000/appdata/(appdir)/app/air
File.applicationStorageDirectory	/accounts/1000/appdata/(appdir)/data
File.desktopDirectory	/accounts/1000/appdata/(appdir)/shared/documents
File.documentsDirectory	/accounts/1000/appdata/(appdir)/shared/documents
File.userDirectory	/accounts/1000/appdata/(appdir)

In that list, the (appdir) folder (which refers to a folder named for your app's Package Name and Package Id joined with a dot, as in "Foo.QXBwRXZlbnRzICAgICAgICA") is not writable by your app.  The app has read/execute permission only, and only root can write to it.

It should also be noted in this document that any attempt to read or write anything under the shared/ folder requires the access_shared permission to be specified in the blackberry-tablet.xml file.

[#5]

It's v1.0.2 of the docs, and still this incorrect info is there. Please fix the docs ASAP.

// chall3ng3r //

[#6]

@chall3ng3r, can you provide a link?  The documentation looks correct as far as I can tell.

Note that the link in the article is currently broken.  The page moved and is now here: http://docs.blackberry.com/en/developers/deliverables/23959/Accessing_secure_APIs_1524628_11.jsp

[#7]

peter9477, thanks for pointing out the broken link.  I'll have that fixed right away.

[#8]

The passage about prefixing the filename with a period is incorrect. It only hides the file from file dialogs. It can still be deleted or modified by any app, or by the user via Wi-fi.