Filesystem access in an AIR for TV app

If you are writing or planning to write apps for AIR 2.5 for TV, you’ve probably already been looking at the documents and tutorials on http://www.adobe.com/devnet/devices/flash_platform_tv.html.

More docs are in the works, but in the meantime I thought I’d use this blog to present some of that content.

AIR for TV apps can access the device’s filesystem, but on a “living room” device it is critically important that an app cannot access the device’s system files or the files of other applications installed on the device. Users of TVs and associated devices do not expect or tolerate any device failures — they are watching TV, after all.

Therefore, an AIR for TV application has a limited view of the device’s filesystem. Using ActionScript 3.0, your app can access only the following directories (and their subdirectories). But realize that these names are not the actual directory names on the device. This extra layer protects AIR for TV  applications from maliciously or inadvertently accessing local files that do not belong to them.

  • /app/ is the read-only application directory for the running AIR application.
  • /app-storage/ is the read-write application storage directory for the running AIR application.
  • /home/ is the read-write user directory.
  • /tmp/ is the read-write temporary directory for the running AIR application.
  • /volumes/ is the read-only directory containing zero or more read-write subdirectories that represent mounted volumes.

If an app tries to access any other directory, the runtime throws an exception that the ActionScript code can catch.

As with AIR applications targeting other devices, it’s a best practice to use the following File class properties rather than a directory name:

  • File.applicationDirectory maps to the application’s application-specific directory.  The File.nativePath value of File.applicationDirectory  is /app/ in AIR for TV.
  • File.applicationStorageDirectory maps to an application-specific directory within a user-specific directory.  Its File.nativePath value is /app-storage/ in AIR for TV.
  • File.desktopDirectory maps to an application-specific directory within a user-specific directory.  Its File.nativePath value is /home/ in AIR for TV.
  • File.userDirectory maps to an application-specific directory within a user-specific directory. Its File.nativePath value is /home/ in AIR for TV.
  • File.documentsDirectory maps to an application-specific directory within a user-specific directory. Its File.nativePath value is /home/ in AIR for TV.

Note that File.desktopDirectory, File.userDirectory, and File.documentsDirectory all map to the same directory, which has the File.nativePath value  /home/.

Also consider the behavior of the following methods on AIR for TV devices:

  • File.createTempDirectory() creates a directory with the File.nativePath value /tmp/. AIR for TV maps /tmp/ to a temporary directory on the device. AIR for TV deletes this directory and its contents when the AIR application exits.
  • File.createTempFile() creates a file in the /tmp/ directory.
  • File.getRootDirectories()returns an array with one File object. The File object’s nativePath property has the value /. This root directory contains the directories app, app-storage, home and tmp.
  • StorageVolumeInfo.storageVolumeInfo.getStorageVolumes() returns a Vector of StorageVolume objects. Each StorageVolume object’s rootDirectory property is a File object. The File object’s nativePath value begins with /volumes/. All applications and users have access to the /volumes/ directory.