The Adobe AIR File API

Typical browser applications cannot access the local filesystem. However, Adobe AIR applications can, giving those applications a distinct advantage. Learn how the AIR File API works and build an application that can read and write from a local disk. Someday, your browser will do the very same thing.

The idea behind Adobe AIR is to allow developers to use their existing Adobe Flash, Adobe Flex, Hypertext Markup Language (HTML), and JavaScript skills to move their applications from the Web browser onto the desktop. The ActionScript Virtual Machine (AVM) embedded in AIR makes this move possible, because it functions similar to the Java virtual machine (JVM). When users have the AVM, they can then run applications that have been compiled with the amxmlc compiler. AIR applications are installed like any other desktop application—through an installer. This installer even checks to see if the user has the runtime installed and, if not, prompts the user to install it.

In making this move to the desktop, AIR applications are granted privileges that are not available to their Web-based counterparts. One such privilege is access to the local file system. This article examines the AIR File application programming interface (API), including some of the special directories defined in the API as well as the pre-built user interface (UI) components available in Adobe Flex Builder for working with the file system. Finally, you’ll learn how to build a simple application that uses the File API to browse for and display an image file from your local hard disk.

Flex Builder makes it particularly easy to work with AIR, as it includes a wizard for making AIR projects and includes some nice UI components for working with the file system. As such, you will be using Flex Builder as the integrated development environment (IDE) for building the sample application. If you do not have Flex Builder, you can download a trial version that includes everything you need to build AIR applications.

The AIR File API

Before I begin, let me note that this article doesn’t cover the complete documentation for the AIR File API but rather highlights some of the capabilities that it affords you. The File object is located in the flash.filesystem package. The object can be conceptualized as a representation of a file or a directory—existing files or directories or those that have yet to be created. Before I get into some simple examples of how you can use the File object, however, I want to take a moment to discuss some special directories that the File class defines.

Special Directories

AIR is designed to be a cross-platform tool. As anyone who has worked on more than one operating system knows, file system structures vary greatly from system to system. Fortunately, the AVM for the particular system you’re running on takes care of handling these differences for you by defining a number of static properties in the File class that can be used to reference common directories:

  • File.applicationStorageDirectory: This directory is uniquely dedicated for each application for file storage. The application storage directory location is based on the user name, the application ID, and the publisher ID.
    • In Mac OS X, the directory resides in /Users/user_name/Library/Preferences/applicationID.publisherID/Local Store/ (for example, /Users/someUser/Library/Preferences/com.example.TestApp.02D88EEED35F84C264A183921344EEA353A629FD.1/Local Store).
    • In Windows, the directory resides in user_name\Application Data\applicationID.publisherID\Local Store\ (for example, C:\Documents and Settings\someUser\Application Data\com.example.TestApp.02D88EEED35F84C264A183921344EEA353A629FD.1\Local Store).
  • File.applicationDirectory: This directory refers to the file path in which the application and any assets are installed. This is a read-only directory (for example, C:\Program Files\AppName in Windows or /Applications in Mac OS X or wherever the user decided to install the application).
  • File.desktopDirectory: This directory contains a reference to the user’s desktop directory.
  • File.documentsDirectory: This directory contains a reference to the user’s documents directory.
  • File.userDirectory: This directory contains a reference to the user directory.

By using these static references, you can write your code so that you don’t have to worry about what system it will be running on.

Creating File References

There are two main methods of creating a reference to a file or directory. The first is to pass in the file path to the File class’s constructor:

new File("C:\Documents and Settings\someUser\My Documents\someFile.txt")

However, when using this method, your code becomes platform specific. The preferred method of creating a file reference is to use one of the aforementioned static directory references, then use the resolvePath method:

var someFile:File = File.applicationStorageDirectory;
 someFile = someFile.resolvePath("someFileName.txt");
 

The result of the above code is that the variable someFile now points to the someFileName.txt file located in the application storage directory. When you have this reference, you can access any of the following properties of the File object. (There are other properties: These are just examples of the more commonly used options. See the API reference for the full list.)

  • creationDate: The date the file was created
  • creator: The Macintosh creator type of the file (pre–Mac OS X operating systems)
  • data: A ByteArray object representing the data of the loaded file after calling the load method
  • exists: A Boolean value indicating whether the file exists on the hard disk
  • extension: The file extension name
  • isDirectory: A Boolean value indicating whether the referenced file is a directory
  • isHidden: A Boolean value indicating whether the referenced file is hidden
  • isPackage: A Boolean value indicating whether the referenced directory is a package
  • isSymbolicLink: A Boolean value indicating whether the referenced file is a symbolic link
  • modificationDate: The date on which the file was last modified
  • name: The name of the file on the local disk
  • nativePath: The full path name of the file
  • parent: The directory that contains the referenced file
  • size: The file size in bytes
  • type: The file type

Some of these properties may seem a bit odd at first, because you pass the file name to the resolvePath method. However, consider the case where you are pointing to a directory, then need to iterate through the files that it contains to find specific information for each file.

Browsing for Files

A common task for many desktop applications is allowing the user to browse the local file system for a particular file. The File class has several methods for just this purpose:

  • browseForDirectory(title:String):void: Displays a directory chooser dialog box in which the user can select a directory
  • browseForOpen(title:String, typeFilter:Array = null):void: Displays the Open File dialog box, in which the user can select a file to open
  • browseForOpenMultiple(title:String, typeFilter:Array = null):void: Displays the Open File dialog box, in which the user can select one or more files to open
  • browseForSave(title:String):void: Displays the Save File dialog box, in which the user can select a file destination

Comments on "The Adobe AIR File API"

chuckh1958

I’m not so sure that web apps accessing my local filesystem are a good thing. Sounds like a security hole just waiting to be exploited.

Reply

You need to be a part of a contest for one
of the finest websites on the internet. I am going to highly recommend this
website!

Reply

I rarely create responses, but I read a few of the comments here The Adobe AIR File API | Linux
Magazine. I actually do have some questions for you if you don’t mind.
Is it only me or does it appear like a few of these remarks
appear like they are left by brain dead individuals?
:-P And, if you are posting at additional online
sites, I would like to keep up with you. Could you list of the complete urls
of all your social community pages like your linkedin profile, Facebook page or twitter feed?

Review my web blog … Rail Photos Unlimited Gift Shop

Reply

thank you for share!

Reply

Leave a Reply

Your email address will not be published. Required fields are marked *

*

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>