Using the URLRequest class

Contents [Hide]

URLRequest properties
Setting URLRequest defaults
Using AIR URL schemes in URLs
- Using URL schemes in AIR
Prohibited URL schemes

Many networking-related runtime APIs use the URLRequest class to define how a network request is made. The URLRequest class lets you define more than simply the URL string. Content in the runtime can define URLs using new URL schemes (in addition to standard schemes like file and http).

URLRequest properties

The URLRequest class includes the following properties which are available to content only in the AIR application security sandbox:

Property	Description
followRedirects	Specifies whether redirects are to be followed (`true`, the default value) or not (`false`). This is only supported in the runtime.
manageCookies	Specifies whether the HTTP protocol stack should manage cookies (`true`, the default value) or not (`false`) for this request. This is only supported in the runtime.
authenticate	Specifies whether authentication requests should be handled (`true`) for this request. This is only supported in the runtime. The default is to authenticate requests—this may cause an authentication dialog box to be displayed if the server requires credentials to be shown. You can also set the user name and password—see Setting URLRequest defaults.
cacheResponse	Specifies whether successful response data should be cached for this request. This is only supported in the runtime. The default is to cache the response (`true`).
useCache	Specifies whether the local cache should be consulted before this URLRequest fetches data. This is only supported in the runtime. The default (`true`) is to use the local cached version, if available.
userAgent	Specifies the user-agent string to be used in the HTTP request.

The following properties of a URLRequest object can be set by content in any sandbox (not just the AIR application security sandbox):

Property	Description
contentType	The MIME content type of any data sent with the URL request.
data	An object containing data to be transmitted with the URL request.
digest	A secure "digest" to a cached file to track Adobe® Flash® Player cache.
method	Controls the HTTP request method, such as a GET or POST operation. (Content running in the AIR application security domain can specify strings other than `"GET"` or `"POST"` as the `method` property. Any HTTP verb is allowed and `"GET"` is the default method. See AIR security .)
requestHeaders	The array of HTTP request headers to be appended to the HTTP request.
url	Specifies the URL to be requested.

Note: The HTMLLoader class has related properties for settings pertaining to content loaded by an HTMLLoader object. For details, see About the HTMLLoader class .

Setting URLRequest defaults

The URLRequestDefaults class lets you define default settings for URLRequest objects. For example, the following code sets the default values for the manageCookies and useCache properties:

URLRequestDefaults.manageCookies = false; 
URLRequestDefaults.useCache = false; 
air.URLRequestDefaults.manageCookies = false; 
air.URLRequestDefaults.useCache = false;

The URLRequestDefaults class includes a setLoginCredentialsForHost() method that lets you specify a default user name and password to use for a specific host. The host, which is defined in the hostname parameter of the method, can be a domain, such as "www.example.com", or a domain and a port number, such as "www.example.com:80". Note that "example.com", "www.example.com", and "sales.example.com" are each considered unique hosts.

These credentials are only used if the server requires them. If the user has already authenticated (for example, by using the authentication dialog box), then you cannot change the authenticated user by calling the setLoginCredentialsForHost() method.

For example, the following code sets the default user name and password to use at www.example.com:

URLRequestDefaults.setLoginCredentialsForHost("www.example.com", "Ada", "love1816$X"); 
air.URLRequestDefaults.setLoginCredentialsForHost("www.example.com", "Ada", "love1816$X");

Each property of URLRequestDefaults settings applies to only the application domain of the content setting the property. However, the setLoginCredentialsForHost() method applies to content in all application domains within an AIR application. This way, an application can log in to a host and have all content within the application be logged in with the specified credentials.

For more information, see the URLRequestDefaults class in the Adobe AIR Language Reference for HTML Developers (http://www.adobe.com/go/learn_air_html_jslr).

Using AIR URL schemes in URLs

The standard URL schemes, such as the following, are available when defining URLs in any security sandbox in AIR:

http: and https:

Use these as you would use them in a web browser.

file:

Use this to specify a path relative to the root of the file system. For example:

file:///c:/AIR Test/test.txt

You can also use the following schemes when defining a URL for content running in the application security sandbox:

app:

Use this to specify a path relative to the root directory of the installed application (the directory that contains the application descriptor file for the installed application). For example, the following path points to a resources subdirectory of the directory of the installed application:

app:/resources

When running in the ADL application, the application resource directory is set to the directory that contains the application descriptor file.

app-storage:

Use this to specify a path relative to the application store directory. For each installed application, AIR defines a unique application store directory for each user, which is a useful place to store data specific to that application. For example, the following path points to a prefs.xml file in a settings subdirectory of the application store directory:

app-storage:/settings/prefs.xml

The application storage directory location is based on the user name, the application ID, and the publisher ID:

On Mac OS—In:

/Users/user name/Library/Preferences/applicationID.publisherID/Local Store/

For example:

/Users/babbage/Library/Preferences/com.example.TestApp.02D88EEED35F84C264A183921344EEA353A629FD.1/Local Store

On Windows—In the documents and Settings directory, in:

user name/Application Data/applicationID.publisherID/Local Store/

For example:
```
C:\Documents and Settings\babbage\Application Data\com.example.TestApp.02D88EEED35F84C264A183921344EEA353A629FD.1\Local Store
```

The URL (and url property) for a File object created with File.applicationStorageDirectory uses the app-storage URL scheme, as in the following:

var dir:File = File.applicationStorageDirectory; 
dir = dir.resolvePath("preferences"); 
trace(dir.url); // app-storage:/preferences 
var dir = air.File.applicationStorageDirectory; 
dir = dir.resolvePath("prefs.xml"); 
air.trace(dir.url); // app-storage:/preferences

Using URL schemes in AIR

You can use a URLRequest object that uses any of these URL schemes to define the URL request for a number of different objects, such as a FileStream or a Sound object. You can also use these schemes in HTML content running in AIR; for example, you can use them in the src attribute of an img tag.

However, you can only use these AIR-specific URL schemes (app: and app-storage:) in content in the application security sandbox. For more information, see AIR security.

Prohibited URL schemes

Some APIs allow you to launch content in a web browser. For security reasons, some URL schemes are prohibited when using these APIs in AIR. The list of prohibited schemes depends on the security sandbox of the code using the API. For details, see Opening a URL in the default system web browser .