Of the various networking-related classes you’ll use in an AIR application, URLRequest will be used the most. A URLRequest object only provides a reference to the resource to which your application should connect, so it doesn’t do much but will be needed by the classes that do.

When you create a URLRequest object, you can provide it with the URL the application will use:

var url = new air.URLRequest ('http://www.example.com'),

A URLRequest object can use many different URL schemes: http, https, file, app, and app-storage. The last two, which point to items found within the application and application storage directories, can only be used in code running within the application security sandbox (see Chapter 15, “Security Techniques,” if you don’t understand what application security sandbox means). And although this chapter will use URLRequest objects to interact with other computers, they can be used in conjunction with File, Sound, and other object types.

As I said, the actual URLRequest object doesn’t do much, so as an example of how it can be used, I’ll turn to the URLMonitor class. It is defined in the servicemonitor.swf file that comes with the AIR SDK. The URLMonitor class can be used to literally monitor a URL—to see if this application on this computer can access a Web site.

When you create a URLMonitor object, you provide it with a URLRequest instance:

var monitor = new air.URLMonitor(url);

To the monitor you want to add an event listener that watches for status changes:

monitor.addEventListener(air.StatusEvent.STATUS, statusChange);

Finally, start the monitor:

monitor.start();

You can find the status of the resource being monitored by referring to the monitor object’s available property:

function statusChange(e) {
    alert(monitor.available);
}

If monitor.available has a value of true, the application can access that URL.

Let’s run through all this again in a simple, sample application.

var url = new air.URLRequest('http://www.example.com'),
air.navigateToURL(url);

The first example in this chapter shows how easy it is to connect to a URL. That code can also confirm two things: that the user has a live network connection and that the named Web site is available. But you’ll almost always want your applications to do more than just this; normally, they should either retrieve data from that URL or send data to it.

To retrieve data, start by creating the URLRequest object:

var url = new air.URLRequest ('http://www.example.com/page.txt'),

From there, instead of using a URLMonitor object, which can only monitor the status of a URL, create an object of type URLLoader

var loader = new air.URLLoader();

This class is used to handle the data returned by a resource. The data the server sends back will not be available until all of it has been received, so the URLLoader needs an event listener for the load completion:

loader.addEventListener(air.Event.COMPLETE, loadComplete);

Finally, start the loading by invoking the load() method, passing it the URLRequest object:

loader.load(url);

The function that handles the COMPLETE event should be written to accept an event argument:

function loadComplete(e) {
}

Within the function, you can access the retrieved data by either referring to the event’s target attribute or the original loader variable, if it’s global. For either, refer to the data property:

alert(e.target.data);

or

alert(loader.data);

To see how this works in a real example, this next application will fetch a stock quote stored in an online text file.

The previous example quickly demonstrated how simple it can be to retrieve content from an online resource and use it in a desktop application. Such functionality will often be at the heart of an Adobe AIR application, but the same concept can be used to better ends. In that example, one string of text was being read in; what if you wanted to retrieve more discrete bits of data? For example, what if instead of containing just a single stock price, the online file has the stock name, symbol, price, number of traded shares, and so forth?

One solution would be to store the information in XML format. That data could then be retrieved using a standard XMLHttpRequest. You could also still retrieve the content using the previous method, in which case, after retrieving the text string, you’d need to create a DOMParser object to turn the text into usable XML.

A simpler alternative to using XML is to represent the data as a series of name=value pairs like so: name=Adobe%20Systems%20Inc.&symbol=ADBE&price=34.45...

Each name=value pair is separated by an ampersand. The only trick to this format is that it needs to be properly URL-encoded: Spaces must be represented by %20 (as in the above), ampersands by %26, the equals sign by %3D, and so forth. (You’ll often see this in URLs in your Web browser; search the Web for more information.)

Once you have data in this format, you can tell the URLLoader object to expect it. By default, a URLLoader expects to receive plain text. It can also treat the received response as either binary data or as a URLVariables object. You don’t actually need to know anything else about this object right now, except to understand that it will automatically parse the names and values out of the text string, making them easier to refer to.

To tell the URLLoader object what to expect, assign the appropriate constant to its data attribute:

var loader = new air.URLLoader();
loader.dataFormat = air.URLLoaderDataFormat.VARIABLES;

The other two constants are air.URLLoaderDataFormat.TEXT (the default) and air.URLLoaderDataFormat.BINARY.

In the function that’s called when the load is complete, loader.data, will now be an object of type URLVariables. Assuming the example line of name=value pairs, the function could refer to loader.data.name, loader.data.symbol, loader.data.price, and so on.

To test this out, let’s create a new application, similar to the previous example, that retrieves more information from a different resource.

The previous two examples show how you can read data from a network resource into an Adobe AIR application, but data transfers can work the other way, too. AIR applications with access to a network connection can transmit data from the client to the server. An application might need to do this to request to update an online database, to submit user feedback, or to fetch more specific results from the server (for example, to indicate for which stock the price and other information should be returned).

To send data to a server, two URLRequest attributes are involved. The first is method. This property indicates the method used to request the URL page. The two most common methods are GET and POST, which are represented by the constants air.URLRequestMethod.GET and air.URLRequestMethod.POST (GET is the default value). If you’re not familiar with these terms, you may be best served by doing a quick search online (e.g., the Wikipedia entry is helpful). In simplest terms, a GET request is the most common type made: When you load a bookmarked URL in your Web browser or click on a link in a page, that’s GET. Such requests are normally used just to retrieve information from a server. POST requests are commonly used to provide information to a server, for example, when you submit a form.

To change the request type, do this:

var url = new air.URLRequest ('http://www.example.com/page.jsp'),
url.method = air.URLRequestMethod.POST;

The second attribute of the URLRequest object that you’ll use is data. To this property you can assign a string of text, a ByteArray, or a URLVariables object. To use this last option, create a URLVariables object:

var appData = new air.URLVariables();

Then add name=value pairs to the object by treating the name as an attribute of the object:

appData.make = 'Toyota';
appData.model = 'Sienna';
appData.year = 2004;

Those lines add three name=value pairs to the appData object.

The final step in sending data to a server is to associate the data with the URLRequest object, and then load the resource:

url.data = data;
loader.load(url);

The data will be sent to the server when the request is performed through the URLLoader object.

To help you conceptualize this process using the above code, think of it as being similar to having a form on a Web site with inputs named make, model, and year. When the form is submitted, it would send the user-entered values—Toyota, Sienna, and 2004—to www.example.com/page.jsp, which would handle the form data. This brings me to the last step in the process: The server resource needs to be written to accept data submission and respond in some way. You can do this using PHP, JSP (Java Server Pages), Ruby on Rails, ASP.NET, ColdFusion, and many other technologies.

For a real-world example of this concept, the next application will handle the entering of the application’s license code. This process normally works as follows:

The following application will focus on steps 2 and 3 of this process.

Another way that a desktop application might interact with a server (besides accessing pages and reading in the response) is to download a file from it. The concept is the same, but the amount of data and what the application does with that data is different.

Start, of course, with a URLRequest object:

var url = new air.URLRequest ('http://www.example.com/somefile'),

From there, you could use the URLLoader class to download the file data, reading in the response as binary data. However, if you know you’ll be handling binary data, the URLStream class provides a more basic tool for the job:

var urlStream = new air.URLStream();

To download small files, add an event listener that will be called when the download (aka, the server response) is complete:

urlStream.addEventListener(air.Event.COMPLETE, saveFile);

(The next section discusses alternative code for downloading large files.)

To begin the download, call the load() method of the URLStream object:

urlStream.load(url);

When all of the file data has been downloaded, it’s stored in the urlStream object. To turn that into a file on the user’s computer, you’ll need to read it into a ByteArray object (see Chapter 10, “Working with File Content”), and then write the ByteArray object to a file:

var data = new air.ByteArray();
urlStream.readBytes(data, 0, urlStream.bytesAvailable);
var file = air.File.desktopDirectory.resolvePath('somefile'),
var fileStream = new air.FileStream();
fileStream.open(file, air.FileMode.WRITE);
fileStream.writeBytes(data, 0, data.length);
fileStream.close();

This next script will implement all of this code, downloading a file from a server (after the user clicks a button, Figure 13.8) and saving that file on the user’s desktop.

Figure 13.8. When the user clicks this button, a file from a server will be downloaded.

One of the benefits of using URLStream instead of URLLoader to download files is that the URLStream object can access the returned data incrementally (a URLLoader object can only use the full response). When downloading large files, you’ll want to take advantage of this feature so as not to max out the computer’s RAM (because the downloaded data is stored in the application’s memory until its written to a file). To handle the download incrementally, add an event listener that responds to the download progress:

urlStream.addEventListener(air.ProgressEvent.PROGRESS, writeToFile);

Downloading a file incrementally really means writing the downloaded data to the file on the user’s computer incrementally. So, start by opening the file outside of the writeToFile() function (because the file should only be opened once and the writeToFile() function will be called repeatedly):

var file = air.File.desktopDirectory.resolvePath('largeFile'),
var fileStream = new air.FileStream();
fileStream.open(file, air.FileMode.WRITE);

The writeToFile() function will still read the downloaded data into a ByteArray, and then write that ByteArray to the file:

var data = new air.ByteArray();
urlStream.readBytes(data, 0, urlStream.bytesAvailable);
fileStream.writeBytes(data, 0, data.length);

Here’s how the writeToFile() function will work differently than the saveFile() function in Script 13.4: When the downloading begins, some of the online file’s data will be placed into the URLStream object, and then the writeToFile() function will be called because progress has been made. The function will write all the data that’s been downloaded thus far to the File object. Then that data will be automatically removed from the urlStream object and more will be downloaded into it, thus calling the writeToFile() function again. This loop will continue until all the data has been downloaded.

Let’s modify the previous example to handle the download in this manner.

The last topic to be covered in this chapter is how to upload a file to a server. There are a few different ways you could do this. One option would be to use the Socket class to FTP the document to a server. This is an excellent way to go, provided you know how to set up and use an FTP server.

A second method would be to read the file into a ByteArray, assign that to the URLRequest object’s data attribute, and then use a URLLoader to request a page on the server, thereby sending it the file as well. This is similar to Script 13.4 but uses a ByteArray instead of a URLVariables object.

The third option, and the one I’ll use here, is based upon the File class. The File class defines a method called upload(). This method performs an upload of the file to a server, as if the user had selected the file in a standard HTML form and then submitted that form. What’s nice about using this method is that the file upload is performed asynchronously, meaning that the upload will happen in the background while the user can continue to perform other tasks within the application.

Assuming you have a File object that already refers to a file on the user’s computer (for example, one the user has selected), the next steps would be to add event listeners to that object. The pertinent events are air.ProgressEvent.PROGRESS and air.Event.COMPLETE:

file.addEventListener(air.ProgressEvent.PROGRESS, uploadProgress);
file.addEventListener(air.Event.COMPLETE, uploadComplete).

The complete event is triggered once the file has been completely uploaded. The progress event is frequently triggered while the upload is happening. Within that handling function, you can refer to the event’s bytesLoaded attribute to see how much of the file has been uploaded. The event’s bytesTotal attribute reflects the total file size (as does the File object’s size attribute).

To call the upload() method, you need to provide it with a URLRequest object. That object should refer to the URL to which the file should be sent:

var url = new air.URLRequest ('http://www.example.com/upload.php'),
file.upload(url, 'aFile'),

The second argument in this method is the name associated with the uploaded file. This isn’t the file’s actual name from the user’s computer, but rather like the name given to a file input in an HTML form. This value provides the handling script with a reference to the uploaded file.

Handling file uploads using a server-side script is beyond the scope of this book, but this next example will demonstrate the AIR application code involved.