window.runtime propertywindow.runtime.flash.net.URLRequest
InheritanceURLRequest Inheritance Object
Runtime Versions: AIR 1.0, Flash Player 9

The URLRequest class captures all of the information in a single HTTP request. URLRequest objects are passed to the load() methods of the Loader, URLStream, and URLLoader classes as well as in other loading operations to initiate URL downloads, as well as to the upload() and download() methods of the FileReference class.

For content running in Adobe AIR, files in the application security sandbox — files installed with the AIR application — can access URLs using any of the following URL schemes:

Content running in Adobe AIR that is not in the application security domain observes the same restrictions as content running in in the browser , and loading is governed by the content's domain.

For more information, see the following:

View the examples

See also

URLLoader
URLRequestHeader
URLRequestDefaults
URLStream

Properties
 PropertyDefined By
  authenticate : Boolean
Specifies whether authentication requests should be handled (true or not (false) for this request.
URLRequest
  cacheResponse : Boolean
Specifies whether successful response data should be cached for this request.
URLRequest
 Inheritedconstructor : Object
A reference to the class object or constructor function for a given object instance.
Object
  contentType : String
The MIME content type of the content in the the data property.
URLRequest
  data : Object
An object containing data to be transmitted with the URL request.
URLRequest
  digest : String
A string that uniquely identifies the signed Adobe platform component to be stored to (or retrieved from) the Flash Player cache.
URLRequest
  followRedirects : Boolean
Specifies whether redirects are to be followed (true) or not (false).
URLRequest
  manageCookies : Boolean
Specifies whether the HTTP protocol stack should manage cookies for this request.
URLRequest
  method : String
Controls the HTTP form submission method.
URLRequest
 Inheritedprototype : Object
[static] A reference to the prototype object of a class or function object.
Object
  requestHeaders : Array
The array of HTTP request headers to be appended to the HTTP request.
URLRequest
  url : String
The URL to be requested.
URLRequest
  useCache : Boolean
Specifies whether the local cache should be consulted before this URLRequest fetches data.
URLRequest
  userAgent : String
Specifies the user-agent string to be used in the HTTP request.
URLRequest
Public Methods
 MethodDefined By
  
URLRequest(url:String = null)
Creates a URLRequest object.
URLRequest
 Inherited
hasOwnProperty(name:String):Boolean
Indicates whether an object has a specified property defined.
Object
 Inherited
isPrototypeOf(theClass:Object):Boolean
Indicates whether an instance of the Object class is in the prototype chain of the object specified as the parameter.
Object
 Inherited
propertyIsEnumerable(name:String):Boolean
Indicates whether the specified property exists and is enumerable.
Object
 Inherited
setPropertyIsEnumerable(name:String, isEnum:Boolean = true):void
Sets the availability of a dynamic property for loop operations.
Object
 Inherited
toString():String
Returns the string representation of the specified object.
Object
 Inherited
valueOf():Object
Returns the primitive value of the specified object.
Object
Property Detail
authenticateproperty
authenticate:Boolean  [read-write]
Runtime Versions: AIR 1.0

Specifies whether authentication requests should be handled (true or not (false) for this request. If false, authentication challenges return an HTTP error.

The supported authentication methods are:

Note:The FileReference.upload(), FileReference.download(), and HTMLLoader.load() methods do not support the URLRequest.authenticate property.

The default value is true.


Throws
SecurityError — The caller is not in the AIR application security sandbox.

See also

URLRequestDefaults.authenticate
cacheResponseproperty 
cacheResponse:Boolean  [read-write]
Runtime Versions: AIR 1.0

Specifies whether successful response data should be cached for this request. When set to true, the AIR application uses the operating system's HTTP cache.

Note:The HTMLLoader.load() method does not support the URLRequest.cacheResponse property.

The default value is true.


Throws
SecurityError — The caller is not in the AIR application security sandbox.

See also

URLRequestDefaults.cacheResponse
contentTypeproperty 
contentType:String  [read-write]
Runtime Versions: AIR 1.0, Flash Player 9

The MIME content type of the content in the the data property.

Note:The FileReference.upload(), FileReference.download(), and HTMLLoader.load() methods do not support the URLRequest.contentType property.

See also

data
dataproperty 
data:Object  [read-write]
Runtime Versions: AIR 1.0, Flash Player 9

An object containing data to be transmitted with the URL request.

This property is used with the method property. In Adobe AIR, data is sent when any HTTP method other than GET is used.

The URLRequest API offers binary POST support and support for URL-encoded variables, as well as support for strings. The data object can be a ByteArray, URLVariables, or String object.

The way in which the data is used depends on the type of object used:

This data is not sent until a method, such as navigateToURL() or FileReference.upload(), uses the URLRequest object.

See also

URLRequest.method
URLRequestMethod
URLVariables
ByteArray
contentType
digestproperty 
digest:String  [read-write]
Runtime Versions: AIR 1.0, Flash Player 9.0.115.0

A string that uniquely identifies the signed Adobe platform component to be stored to (or retrieved from) the Flash Player cache.


Throws
ArgumentError — The digest provided does not match the digest of the file that is extracted from the downloaded signed file or the signed file loaded out of the cache. Flash Player also throws this error if the provided digest is the wrong length or contains invalid (nonhexadecimal) characters.
followRedirectsproperty 
followRedirects:Boolean  [read-write]
Runtime Versions: AIR 1.0

Specifies whether redirects are to be followed (true) or not (false).

Note:The FileReference.upload(), FileReference.download(), and HTMLLoader.load() methods do not support the URLRequest.followRedirects property.

The default value is true.


Throws
SecurityError — The caller is not in the AIR application security sandbox.

See also

URLRequestDefaults.followRedirects
manageCookiesproperty 
manageCookies:Boolean  [read-write]
Runtime Versions: AIR 1.0

Specifies whether the HTTP protocol stack should manage cookies for this request. When true, cookies are added to the request and response cookies are remembered. If false, cookies are not added to the request and response cookies are not remembered, but users can manage cookies themselves by direct header manipulation.

On Mac OS, cookies are shared with Safari. To clear cookies on Mac OS:

  1. Open Safari.
  2. Select Safari > Preferences, and click the Security panel.
  3. Click the Show Cookies button.
  4. Click the Reomove All button.

To clear cookies on Windows:

  1. Open the Internet Properties control panel, and click the General tab.
  2. Click the Delete Cookies button.

The default value is true.


Throws
SecurityError — The caller is not in the AIR application security sandbox.

See also

URLRequestDefaults.manageCookies
methodproperty 
method:String  [read-write]
Runtime Versions: AIR 1.0, Flash Player 9

Controls the HTTP form submission method.

For content running in Adobe AIR, if the content is in the application security domain, you can use any string value; otherwise (if the content is not in the AIR application security domain) you are still restricted to using GET or POST.

Note: If running in Flash Player and the referenced form has no body, Flash Player automatically uses a GET operation even if the method is set to URLRequestMethod.POST.

The default value is URLRequestMethod.GET.


Throws
ArgumentError — If the value parameter is not URLRequestMethod.GET or URLRequestMethod.POST.

See also

URLRequestMethod class

Example
The following example opens the remote application hosted at http://www.[yourDomain].com/application.jsp in a new browser window and passes data about a user session, captured in a URLVariables object, to the application. It explicitly sets the value of the URLRequest.method property to URLRequestMethod.POST.

Highlights of the example follow:

  1. The constructor function creates a URLRequest instance named request, taking the URL of the remote application as a parameter.
  2. A URLVariables object is created and two of its properties are assigned values.
  3. The URLVariables object is assigned to the data property of the URLRequest object.
  4. The value of the URLRequest.method property is set to URLRequestMethod.POST.
  5. The example calls navigateToURL, which opens a new browser window to the remote application's URL.

Note: To run the example, the remote application URL in the example must be replaced with a working URL. Additionally, you would need server code to process the information captured by the AIR application in the URLVariables object.

<html>
    <head>
      <script src="AIRAliases.js" />
      <script>
        function init() {
            var url = "http://www.[yourDomain].com/application.jsp";
            var request = new air.URLRequest(url);
            
            var variables = new air.URLVariables();
            variables.exampleSessionId = new Date().getTime();
            variables.exampleUserLabel = "guest";
            request.data = variables;
            request.method = air.URLRequestMethod.POST;
            
            air.navigateToURL(request);
        }
      </script>
    </head>
    <body onload='init()'>
    </body>
</html>
requestHeadersproperty 
requestHeaders:Array  [read-write]
Runtime Versions: AIR 1.0, Flash Player 9

The array of HTTP request headers to be appended to the HTTP request. The array is composed of URLRequestHeader objects. Each object in the array must be a URLRequestHeader object that contains a name string and a value string, as follows: 

  var rhArray:Array = new Array(new URLRequestHeader("Content-Type", "text/html"));

The AIR runtime imposes certain restrictions on request headers; for more information, see the URLRequestHeader class description.

The FileReference.upload() and FileReference.download() methods do not support the URLRequest.requestHeaders parameter.

See also

URLRequestHeader
urlproperty 
url:String  [read-write]
Runtime Versions: AIR 1.0, Flash Player 9

The URL to be requested.

For content running in Adobe AIR that is not in the application security sandbox, by default, the URL must be in exactly the same domain as the calling file, including subdomains. For example, files at www.adobe.com and store.adobe.com are in different domains.

Be sure to encode any characters that are either described as unsafe in the Uniform Resource Locator specification (see http://www.faqs.org/rfcs/rfc1738.html) or that are reserved in the URL scheme of the URLRequest object (when not used for their reserved purpose). For example, use "%25" for the percent (%) symbol and "%23" for the number sign (#), as in "http://www.example.com/orderForm.cfm?item=%23B-3&discount=50%25".

Files in the application security domain — files installed with the AIR application — can access URLs using any of the following URL schemes:

Note: IPv6 (Internet Protocol version 6) is supported. IPv6 is a version of Internet Protocol that supports 128-bit addresses (an improvement on the earlier IPv4 protocol that supports 32-bit addresses). You might need to activate IPv6 on your networking interfaces. For more information, see the Help for the operating system hosting the data. If IPv6 is supported on the hosting system, you can specify numeric IPv6 literal addresses in URLs enclosed in brackets ([]), as in the following:

useCacheproperty 
useCache:Boolean  [read-write]
Runtime Versions: AIR 1.0

Specifies whether the local cache should be consulted before this URLRequest fetches data.

Note:The HTMLLoader.load() method does not support the URLRequest.useCache property.

The default value is true.


Throws
SecurityError — The caller is not in the AIR application security sandbox.

See also

URLRequestDefaults.useCache
userAgentproperty 
userAgent:String  [read-write]
Runtime Versions: AIR 1.0

Specifies the user-agent string to be used in the HTTP request.

Note: This property does not affect the user agent string when the URLRequest object is used with the load() method of an HTMLLoader object. To set the user agent string for an HTMLLoader object, set the userAgent property of the HTMLLoader object or set the static URLRequestDefaults.userAgent property.


Throws
SecurityError — The caller is not in the AIR application security sandbox.

See also

URLRequestDefaults.userAgent
Constructor Detail
URLRequest()Constructor
function URLRequest(url:String = null)
Runtime Versions: AIR 1.0, Flash Player 9

Creates a URLRequest object. If System.useCodePage is true, the request is encoded using the system code page, rather than Unicode. If System.useCodePage is false, the request is encoded using Unicode, rather than the system code page.

Parameters
url:String (default = null) — The URL to be requested. You can set the URL later by using the url property.

See also

System.useCodePage
Examples
URLRequestExample.as

The following example creates a new Loader object and passes it a URLRequest object that contains the path to an XML file. If the loading operation is successful, a complete event is dispatched and the data in the XML file traces to the output. Additional event handlers capture other events, including error events.

To run this example, place the AIRAliases.js file and an XML file named XMLFile.xml in the same directory as the HTML file.


<html>
    <head>
      <script src="AIRAliases.js" />
      <script>
        function init() {
            var loader = new air.URLLoader();
            configureListeners(loader);

            var request = new air.URLRequest("XMLFile.xml");
            try {
                loader.load(request);
            } catch (error) {
                air.trace("Unable to load requested document.");
            }
        }

        function configureListeners(dispatcher) {
            dispatcher.addEventListener(air.Event.COMPLETE, completeHandler);
            dispatcher.addEventListener(air.Event.OPEN, openHandler);
            dispatcher.addEventListener(air.ProgressEvent.PROGRESS, progressHandler);
            dispatcher.addEventListener(air.SecurityErrorEvent.SECURITY_ERROR, securityErrorHandler);
            dispatcher.addEventListener(air.HTTPStatusEvent.HTTP_STATUS, httpStatusHandler);
            dispatcher.addEventListener(air.IOErrorEvent.IO_ERROR, ioErrorHandler);
        }

        function completeHandler(event) {
            var loader = air.URLLoader(event.target);
            air.trace("completeHandler: " + loader.data);
        }

        function openHandler(event) {
            air.trace("openHandler: " + event);
        }

        function progressHandler(event) {
            air.trace("progressHandler loaded:" + event.bytesLoaded + " total: " + event.bytesTotal);
        }

        function securityErrorHandler(event) {
            air.trace("securityErrorHandler: " + event);
        }

        function httpStatusHandler(event) {
            air.trace("httpStatusHandler: " + event);
        }

        function ioErrorHandler(event) {
            air.trace("ioErrorHandler: " + event);
        }
      </script>
    </head>
    <body onload='init()'>
    </body>
</html>



© 2004-2008 Adobe Systems Incorporated. All rights reserved.
Wed Aug 13 2008, 06:17 AM -07:00