ActionScript 3.0 Language and Components Reference | All Packages | All Classes | Language Elements | Index | Appendixes | Conventions | Frames No Frames |
URLRequest

Package | flash.net
Class | public final class URLRequest
Inheritance | URLRequest Object

Language Version : | ActionScript 3.0

Player Version : | 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 URLStream, URLLoader, Loader and 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:

- `http` and `https`
- `file`
- `app-storage`
- `app`

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:

- The security chapter in the Programming ActionScript 3.0 book and the latest comments on LiveDocs
- The "Understanding AIR Security" section of the "Getting started with Adobe AIR" chapter in the Developing AIR Applications book.
- The Flash Player Developer Center Topic: Security

View the examples

See also

URLRequestHeader
URLLoader
URLStream
FileReference
Working with external data

Public Properties
Hide Inherited Public Properties
Show Inherited Public Properties

| Property | Defined By
--- | --- | ---
|  | constructor : Object A reference to the class object or constructor function for a given object instance. | Object
|  | contentType : String The MIME content type of any POST data. | 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
|  | method : String Controls whether the HTTP form submission method is a GET or POST operation. | URLRequest
|  | prototype : 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

Public Methods
Hide Inherited Public Methods
Show Inherited Public Methods

| Method | Defined By
--- | --- | ---
|  | URLRequest(url:String = null) Creates a URLRequest object. | URLRequest
|  | hasOwnProperty(name:String):Boolean Indicates whether an object has a specified property defined. | Object
|  | 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
|  | propertyIsEnumerable(name:String):Boolean Indicates whether the specified property exists and is enumerable. | Object
|  | setPropertyIsEnumerable(name:String, isEnum:Boolean = true):void Sets the availability of a dynamic property for loop operations. | Object
|  | toString():String Returns the string representation of the specified object. | Object
|  | valueOf():Object Returns the primitive value of the specified object. | Object

Property Detail

contentType | property

`contentType:String` [read-write]

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9

The MIME content type of any `POST` data.

Note:The `FileReference.upload()` and `FileReference.download()` methods do not support the `URLRequest.contentType` parameter.

Note: When sending a POST request, the values of the `contentType` and `data` properties must correspond properly. The value of the `contentType` property instructs servers on how to interpret the value of the `data` property. If the value of the `data` property is an URLVariables object, the value of `contentType` must be `application/x-www-form-urlencoded`. If the value of the `data` property is any other type, the value of `contentType` should indicate the type of the POST data that will be sent (which is the binary or string data contained in the value of the `data` property). For `FileReference.upload()`, the Content-Type of the request is set automatically to `multipart/form-data`, and the value of the `contentType` property is ignored.

The default value is `application/x-www-form-urlencoded`.

Implementation
`public function get contentType():String`
`public function set contentType(value:String):void`

data | property |

`data:Object` [read-write]

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9

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

This property is used with the `method` property. If the value of `URLRequest.method` is `POST`, the data is transmitted with the URLRequest object with the HTTP `POST` method.

If the value of `URLRequest.method` is `GET`, the data defines variables to be sent with the URLRequest object with the HTTP `GET` method.

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

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

- If the object is a ByteArray object, the binary data of the ByteArray object is used as `POST` data. For `GET`, data of ByteArray type is not supported. Also, data of ByteArray type is not supported for `FileReference.upload()` and `FileReference.download()`.
- If the object is a URLVariables object and the method is `POST`, the variables are encoded using x-www-form-urlencoded format and the resulting string is used as `POST` data. An exception is a call to `FileReference.upload()`, in which the variables are sent as separate fields in a `multipart/form-data` post.
- If the object is a URLVariables object and the method is `GET`, the URLVariables object defines variables to be sent with the URLRequest object.
- Otherwise, the object is converted to a string, and the string is used as the `POST` or `GET` data.

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

Implementation
`public function get data():Object`
`public function set data(value:Object):void`

See also

URLRequest.method
URLRequestMethod
URLVariables
flash.utils.ByteArray
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.

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 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 Flash Player in the URLVariables object.

    package {
        import flash.display.Sprite;
        import flash.net.navigateToURL;
        import flash.net.URLRequest;
        import flash.net.URLVariables;

        public class URLVariablesExample extends Sprite {

            public function URLVariablesExample() {
                var url:String = "http://www.[yourDomain].com/application.jsp";
                var request:URLRequest = new URLRequest(url);
                var variables:URLVariables = new URLVariables();
                variables.exampleSessionId = new Date().getTime();
                variables.exampleUserLabel = "guest";
                request.data = variables;
                navigateToURL(request);
            }
        }
    }

digest | property |

`digest:String` [read-write]

Language Version : | ActionScript 3.0

Player Version : | 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. A digest corresponds to a single cached file; if you change the file in any way, its digest will change in an unpredictable way. By using a digest, you can verify the cached file across multiple domains. Two files with the same digest are the same file, and two files with different digests are not the same file. A file cannot (practically) be created to "spoof" a digest and pretend to be another digest.

The digest is based on an SHA-256 message digest algorithm (64 characters long in hexadecimal format).

Implementation
`public function get digest():String`
`public function set digest(value:String):void`
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.

Example
The following example loads a remote file into the cache. At the end of the load, the byte array contains the actual file (not the signed file). The example completes the load operation by calling `loadBytes()`:

    var myURLReq:URLRequest = new URLRequest();
    myURLReq.url = "http://yourdomain/users/jdoe/test01/_rsc/Automated/AssetCaching_rsc/test01/rsl.swz";
    myURLReq.digest = "3B0AA28C7A990385E044D80F5637FB036317BB41E044D80F5637FB036317BB41";
    var myURLLoader:URLLoader = new URLLoader();
    myURLLoader.dataFormat = URLLoaderDataFormat.BINARY;
    myURLLoader.addEventListener("complete", onC);

    myURLLoad.load(myURLReq);

    function onC(e) {
        var someLoader:Loader = new Loader();
        addChild(someLoader);
        someLoader.loadBytes((ByteArray)(myURLLoad.data));
    }

method | property |

`method:String` [read-write]

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9

Controls whether the HTTP form submission method is a `GET` or `POST` operation. Valid values are `URLRequestMethod.GET` or `URLRequestMethod.POST`.

Note: If the referenced form has no body, Flash Player automatically uses a `GET` operation even if the method is set to `URLRequestMethod.POST`. For this reason, it is recommended to always include a dummy body to ensure that the correct `method` is used.

The default value is `URLRequestMethod.GET`.

Implementation
`public function get method():String`
`public function set method(value:String):void`
Throws

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

See also

URLRequestMethod class
Working with external data
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 Flash Player in the URLVariables object.

    package {
        import flash.display.Sprite;
        import flash.net.navigateToURL;
        import flash.net.URLRequest;
        import flash.net.URLRequestMethod;
        import flash.net.URLVariables;

        public class URLRequest_method extends Sprite {

            public function URLRequest_method() {
                var url:String = "http://www.[yourDomain].com/application.jsp";
                var request:URLRequest = new URLRequest(url);

                var variables:URLVariables = new URLVariables();
                variables.exampleSessionId = new Date().getTime();
                variables.exampleUserLabel = "guest";
                request.data = variables;
                request.method = URLRequestMethod.POST;

                navigateToURL(request);
            }
        }
    }

requestHeaders | property |

`requestHeaders:Array` [read-write]

Language Version : | ActionScript 3.0

Player Version : | 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"));

Flash Player 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.

Implementation
`public function get requestHeaders():Array`
`public function set requestHeaders(value:Array):void`

See also

URLRequestHeader

url | property |

`url:String` [read-write]

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9

The URL to be requested. By default, the URL must be in exactly the same domain as the calling SWF file, including subdomains. For example, SWF files at www.adobe.com and store.adobe.com are in different domains. To load data from a different domain, put a cross-domain policy file on the server that is hosting the data. For more information, see the security documentation described in the URLRequest class description.

Note: Flash Player 9.0.115.0 and later versions supports IPv6 (Internet Protocol version 6). 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:

         rtmp://[2001:db8:ccc3:ffff:0:444d:555e:666f]:1935/test

Implementation
`public function get url():String`
`public function set url(value:String):void`
Constructor Detail

URLRequest | () | Constructor

`public function URLRequest(url:String = null)`

Language Version : | ActionScript 3.0

Player Version : | 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

flash.system.System.useCodePage
Examples How to use 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 a file named XMLFile.xml in the same directory as your SWF file.

    package {
        import flash.display.Sprite;
        import flash.events.*;
        import flash.net.*;

        public class URLRequestExample extends Sprite {

            public function URLRequestExample() {
                var loader:URLLoader = new URLLoader();
                configureListeners(loader);

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

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

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

            private function openHandler(event:Event):void {
                trace("openHandler: " + event);
            }

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

            private function securityErrorHandler(event:SecurityErrorEvent):void {
                trace("securityErrorHandler: " + event);
            }

            private function httpStatusHandler(event:HTTPStatusEvent):void {
                trace("httpStatusHandler: " + event);
            }

            private function ioErrorHandler(event:IOErrorEvent):void {
                trace("ioErrorHandler: " + event);
            }
        }
    }

Submit Feedback on LiveDocs
© 2004-2008 Adobe Systems Incorporated. All rights reserved.
Tue May 20 2008, 04:02 AM -07:00