Exploring the new file capabilities in Adobe AIR 2

One of the biggest advantages of running an AIR desktop application over a browser-based web application is the richness of functionality that comes with installing an application on your desktop. For example, AIR applications can create notifications, change the dock or system tray icon, and, of course, access the file system.

AIR 1.0 provided a very rich set of file APIs that enabled developers to read and write from the file system; move, copy, and delete files; traverse directories; open native file picker dialog boxes; and more. AIR 1.1 added the spaceAvailable property to the File class in order to enable developers to determine how much space is available on a given volume. AIR 2 expands the file APIs even further by adding the ability to:

• Open files with their default registered application.
• Flag files as "downloaded" so that some operating systems will caution users before opening them for the first time.
• Get notified of mounted and unmounted storage volumes, and query those volumes for information.

This article covers the following topics:

• Launching a file's default application
• Flagging a file as downloaded
• Listening for mounted volumes and accessing volume information
• Sample application: FileTile

Launching a file's default application

AIR 2 adds the function openWithDefaultApplication to the File class. Calling openWithDefaultApplication on a file opens whichever application the operating system associates with that file, and then activates that application. For example, if the file instance points to a Microsoft Word document, calling openWithDefaultApplication will cause Microsoft Word to open and load the referenced file, or calling openWithDefaultApplication on an image might cause that image to be opened with Photoshop or other default application for images.

You should be aware of the following caveats before using the openWithDefaultApplication function:

• You cannot open an application without referencing a file that is associated with that application.
• The openWithDefaultApplication function can only be called from code running inside the application sandbox. If it's called by code running outside the application sandbox, a security error is thrown.
• The openWithDefaultApplication function does not provide any means to communicate with the launched process after it's open. If you need to launch an external process and subsequently communicate with it, see the new NativeProcess APIs in AIR 2.
• The AIR runtime does not verify the file before it is passed to the associated application, so if the file has an incorrect extension, it's possible that the application that is launched to handle it will not be able to read it.
• It is not possible to use the openWithDefaultApplication function to launch executables directly. In order to preserve the platform-independent nature of Adobe AIR applications, you must use the new NativeProcess APIs in AIR 2, combined with a native installer, to launch executables from AIR.
• If you call openWithDefaultApplication on a file that does not have a default application associated with it, a runtime error is thrown. Be sure to catch this error in your code and handle it gracefully if your application allows for this scenario.
• If you call openWithDefaultApplication on a directory, it will open in your default file explorer application (Finder, Windows Explorer, Nautilus, and so on).

The following code shows how to open a Keynote presentation on Mac OS X:

var presentation:File = File.documentsDirectory.resolvePath("Presentations/MAX_2009.key"); presentation.openWithDefaultApplication();

openWithDefaultApplication is platform-independent as well as user-independent, since it opens files with whichever application is associated with the referenced file type. For example, calling openWithDefaultApplication on an MP3 file might open iTunes on Mac OS X, Windows Media on Windows, or VLC on Linux.

Flagging a file as downloaded

AIR 2 also adds to the File class the downloaded property, which enables AIR applications to specify whether a file was downloaded over a network. On some operating systems, setting this property to true will result in the user getting a security notification the first time he or she tries to open the file. For example, when a user opens a file that was downloaded through Safari on Mac OS X, the operating system displays a dialog box that requires the user's confirmation before the file is actually opened. When saving files in an AIR application that were downloaded over a network (for example, in an FTP client), setting this property to true is considered a best practice.

Note: Files that are downloaded through the FileReference.download method are automatically marked as downloaded.

The downloaded property only has an effect on Windows XP SP2 and later (including Vista and Windows 7), and on Mac OS 10.5 (Leopard) and later. Currently, Linux does not support this property; therefore, setting it in an application running on Linux will have no effect.

The following code shows setting the downloaded property to true on a file that was downloaded from the network and saved locally:

var loader:URLLoader = new URLLoader(); loader.dataFormat = URLLoaderDataFormat.BINARY; loader.addEventListener(Event.COMPLETE, function(e:Event):void { var air:File = File.userDirectory.resolvePath("Downloads/AdobeAIR.dmg"); var fs:FileStream = new FileStream(); fs.open(air, FileMode.WRITE); fs.writeBytes(loader.data); fs.close(); air.downloaded = true; }); var req:URLRequest = new URLRequest("http://airdownload.adobe.com/air/mac/download/latest/AdobeAIR.dmg"); loader.load(req);

Listening for mounted volumes and accessing volume information

The final addition to the file system APIs in AIR 2 provides the ability to listen for the mounting and unmounting of storage volumes, and to query storage volumes for information. For example, if your application needs to know when a USB flash drive has been plugged in, a network drive has been mounted or a digital camera has been connected, you can listen for the StorageVolumeChangeEvent and have your application react accordingly.

To be notified of the mounting and unmounting of storage volumes, add an event listener to the StorageVolumeInfo singleton instance like this:

StorageVolumeInfo.storageVolumeInfo.addEventListener(StorageVolumeChangeEvent.STORAGE_VOLUME_MOUNT, onVolumeMount); StorageVolumeInfo.storageVolumeInfo.addEventListener(StorageVolumeChangeEvent.STORAGE_VOLUME_UNMOUNT, onVolumeUnmount);

The StorageVolumeChangeEvent contains a reference to the StorageVolume that was just mounted (the storageVolume property is null if the StorageVolumeChangeEvent was fired in response to a volume being unmounted). The StorageVolume class provides several properties containing information on the storage volume such as:

• fileSystemType
• isRemovable
• isWritable
• drive
• name
• rootDirectory

Note: The drive property refers to the drive letter on Windows, and is null on Mac. The name property refers to the volume name on both Mac and Windows.

You don't always have to listen for the StorageVolumeChangeEvent to get information about mounted storage volumes; the getStorageVolumes function on the StorageVolumeInfo class returns a vector of mounted storage volumes. The following code demonstrates getting a list of all mounted storage volumes:

var volumes:Vector. = StorageVolumeInfo.storageVolumeInfo.getStorageVolumes(); for each (var volume:StorageVolume in volumes) { trace(volume.name, volume.rootDirectory.nativePath); }

FileTile: The new AIR 2 file system APIs in action

FileTile, shown in Figure 1, is a sample application I wrote to demonstrate the new AIR 2 file system APIs. It's a utility for browsing storage volumes like flash drives and digital cameras which expose themselves as storage volumes. You can install FileTile from Adobe Labs, or download the full source code from Google Code.

 

 

http://www.adobe.com/devnet/air/flex/articles/exploring_file_capabilities.html