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

Package | flash.net
Class | public class URLLoader
Inheritance | URLLoader EventDispatcher Object

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9

The URLLoader class downloads data from a URL as text, binary data, or URL-encoded variables. It is useful for downloading text files, XML, or other information to be used in a dynamic, data-driven application.

A URLLoader object downloads all of the data from a URL before making it available to ActionScript. It sends out notifications about the progress of the download, which you can monitor through the `bytesLoaded` and `bytesTotal` properties, as well as through dispatched events.

When using this object, consider the Flash Player security model:

- A SWF file in the local-with-filesystem sandbox may not load data from, or provide data to, a resource that is in the network sandbox.
- By default, the calling SWF file and the URL you load must be in exactly the same domain. For example, a SWF file at www.adobe.com can load data only from sources that are also at www.adobe.com. To load data from a different domain, place a URL policy file on the server hosting the data.

For more information related to security, see the following:

- The security chapter in the Programming ActionScript 3.0 book and the latest comments on LiveDocs
- The Flash Player Developer Center Topic: Security

View the examples

See also

URLRequest
URLVariables
URLStream
Reading external XML documents
Working with external data

Public Properties
Hide Inherited Public Properties
Show Inherited Public Properties

| Property | Defined By
--- | --- | ---
|  | bytesLoaded : uint = 0 Indicates the number of bytes that have been loaded thus far during the load operation. | URLLoader
|  | bytesTotal : uint = 0 Indicates the total number of bytes in the downloaded data. | URLLoader
|  | constructor : Object A reference to the class object or constructor function for a given object instance. | Object
|  | data : * The data received from the load operation. | URLLoader
|  | dataFormat : String = "text" Controls whether the downloaded data is received as text (URLLoaderDataFormat.TEXT), raw binary data (URLLoaderDataFormat.BINARY), or URL-encoded variables (URLLoaderDataFormat.VARIABLES). | URLLoader
|  | prototype : Object [static] A reference to the prototype object of a class or function object. | Object

Public Methods
Hide Inherited Public Methods
Show Inherited Public Methods

| Method | Defined By
--- | --- | ---
|  | URLLoader(request:URLRequest = null) Creates a URLLoader object. | URLLoader
|  | addEventListener(type:String, listener:Function, useCapture:Boolean = false, priority:int = 0, useWeakReference:Boolean = false):void Registers an event listener object with an EventDispatcher object so that the listener receives notification of an event. | EventDispatcher
|  | close():void Closes the load operation in progress. | URLLoader
|  | dispatchEvent(event:Event):Boolean Dispatches an event into the event flow. | EventDispatcher
|  | hasEventListener(type:String):Boolean Checks whether the EventDispatcher object has any listeners registered for a specific type of event. | EventDispatcher
|  | 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
|  | load(request:URLRequest):void Sends and loads data from the specified URL. | URLLoader
|  | propertyIsEnumerable(name:String):Boolean Indicates whether the specified property exists and is enumerable. | Object
|  | removeEventListener(type:String, listener:Function, useCapture:Boolean = false):void Removes a listener from the EventDispatcher object. | EventDispatcher
|  | 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
|  | willTrigger(type:String):Boolean Checks whether an event listener is registered with this EventDispatcher object or any of its ancestors for the specified event type. | EventDispatcher

Events
Hide Inherited Events
Show Inherited Events

| Event | Summary | Defined By
--- | --- | --- | ---
|  | activate | Dispatched when Flash Player gains operating system focus and becomes active. | EventDispatcher
|  | complete | Dispatched after all the received data is decoded and placed in the data property of the URLLoader object. | URLLoader
|  | deactivate | Dispatched when Flash Player loses operating system focus and is becoming inactive. | EventDispatcher
|  | httpStatus | Dispatched if a call to URLLoader.load() attempts to access data over HTTP and the current Flash Player environment is able to detect and return the status code for the request. | URLLoader
|  | ioError | Dispatched if a call to URLLoader.load() results in a fatal error that terminates the download. | URLLoader
|  | open | Dispatched when the download operation commences following a call to the URLLoader.load() method. | URLLoader
|  | progress | Dispatched when data is received as the download operation progresses. | URLLoader
|  | securityError | Dispatched if a call to URLLoader.load() attempts to load data from a server outside the security sandbox. | URLLoader

Property Detail

bytesLoaded | property

`public var bytesLoaded:uint = 0`

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9

Indicates the number of bytes that have been loaded thus far during the load operation.

bytesTotal | property |

`public var bytesTotal:uint = 0`

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9

Indicates the total number of bytes in the downloaded data. This property contains 0 while the load operation is in progress and is populated when the operation is complete. Also, a missing Content-Length header will result in bytesTotal being indeterminate.

data | property |

`public var data:*`

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9

The data received from the load operation. This property is populated only when the load operation is complete. The format of the data depends on the setting of the `dataFormat` property:

If the `dataFormat` property is `URLLoaderDataFormat.TEXT`, the received data is a string containing the text of the loaded file.

If the `dataFormat` property is `URLLoaderDataFormat.BINARY`, the received data is a ByteArray object containing the raw binary data.

If the `dataFormat` property is `URLLoaderDataFormat.VARIABLES`, the received data is a URLVariables object containing the URL-encoded variables.

See also

URLLoaderDataFormat
URLLoader.dataFormat

dataFormat | property |

`public var dataFormat:String = "text"`

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9

Controls whether the downloaded data is received as text (`URLLoaderDataFormat.TEXT`), raw binary data (`URLLoaderDataFormat.BINARY`), or URL-encoded variables (`URLLoaderDataFormat.VARIABLES`).

If the value of the `dataFormat` property is `URLLoaderDataFormat.TEXT`, the received data is a string containing the text of the loaded file.

If the value of the `dataFormat` property is `URLLoaderDataFormat.BINARY`, the received data is a ByteArray object containing the raw binary data.

If the value of the `dataFormat` property is `URLLoaderDataFormat.VARIABLES`, the received data is a URLVariables object containing the URL-encoded variables.

The default value is `URLLoaderDataFormat.TEXT`.

See also

URLLoaderDataFormat
Constructor Detail

URLLoader | () | Constructor

`public function URLLoader(request:URLRequest = null)`

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9

Creates a URLLoader object.

Parameters

| `request:URLRequest` (default = `null`)`` — A URLRequest object specifying the URL to download. If this parameter is omitted, no load operation begins. If specified, the load operation begins immediately (see the `load` entry for more information).

See also

URLLoader.load()
Method Detail

close | () | method

`public function close():void`

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9

Closes the load operation in progress. Any load operation in progress is immediately terminated. If no URL is currently being streamed, an invalid stream error is thrown.

load | () | method |

`public function load(request:URLRequest):void`

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9

Sends and loads data from the specified URL. The data can be received as text, raw binary data, or URL-encoded variables, depending on the value you set for the `dataFormat` property. Note that the default value of the `dataFormat` property is text. If you want to send data to the specified URL, you can set the `data` property in the URLRequest object.

Note: If a file being loaded contains non-ASCII characters (as found in many non-English languages), it is recommended that you save the file with UTF-8 or UTF-16 encoding as opposed to a non-Unicode format like ASCII.

A SWF file in the local-with-filesystem sandbox may not load data from, or provide data to, a resource that is in the network sandbox.

By default, the calling SWF file and the URL you load must be in exactly the same domain. For example, a SWF file at www.adobe.com can load data only from sources that are also at www.adobe.com. To load data from a different domain, place a URL policy file on the server hosting the data.

You can prevent a SWF file from using this method by setting the `allowNetworking` parameter of the the `object` and `embed` tags in the HTML page that contains the SWF content.

For more information related to security, see the following:

- The security chapter in the Programming ActionScript 3.0 book and the latest comments on LiveDocs
- The Flash Player Developer Center Topic: Security

Parameters

| `request:URLRequest` — A URLRequest object specifying the URL to download.

Events

| `complete:`Event`` — Dispatched after data has loaded successfully.
| `httpStatus:`HTTPStatusEvent`` — If access is over HTTP, and the current Flash Player environment supports obtaining status codes, you may receive these events in addition to any `complete` or `error` event.
| `ioError:`IOErrorEvent`` — The load operation could not be completed.
| `progress:`ProgressEvent`` — Dispatched when data is received as the download operation progresses.
| `securityError:`SecurityErrorEvent`` — A load operation attempted to retrieve data from a server outside the caller's security sandbox. This may be worked around using a policy file on the server.
| `open:`Event`` — Dispatched when a load operation commences.

Throws

| `ArgumentError` — `URLRequest.requestHeader` objects may not contain certain prohibited HTTP request headers. For more information, see the URLRequestHeader class description.
| `MemoryError` — This error can occur for the following reasons: 1) Flash Player cannot convert the `URLRequest.data` parameter from UTF8 to MBCS. This error is applicable if the URLRequest object passed to `load()` is set to perform a `GET` operation and if `System.useCodePage` is set to `true`. 2) Flash Player cannot allocate memory for the `POST` data. This error is applicable if the URLRequest object passed to `load` is set to perform a `POST` operation.
| `SecurityError` — Local untrusted SWF files may not communicate with the Internet. This may be worked around by reclassifying this SWF file as local-with-networking or trusted.
| `TypeError` — The value of the request parameter or the `URLRequest.url` property of the URLRequest object passed are `null`.

See also

URLRequestHeader
URLRequest.requestHeaders
URLRequest.data
Working with external data
Flash Player security
Example
In the following example, an XML files is loaded and the content of its elements' first arguments are displayed in a text field.

A `URLRequest` object is created to identify the location of the XML file, which for this example is in the same directory as the SWF file. The file is loaded in a `try...catch` block in order to catch any error that may occur. (Here we catch the `SecurityError` errors.) If an `IO_ERROR` event occurs, the `errorHandler()` method is invoked, which writes an error message in the `xmlTextField` text field. Once the XML file data is received and place in the data property of the `loader` URLLoader object, the `Event.COMPLETE` event is dispatched and the `loaderCompleteHandler()` method is invoked.

In the `loaderCompleteHandler()` method, a `try...catch` block is used to catch any parsing error that may occur while converting the loaded data from the file into an XML object. The `readNodes()` method then recursively goes through all the elements in the nodes of the XML document and appends the `xmlTextField` text field with a list of the first attributes of all the elements.

    package {
        import flash.display.Sprite;
        import flash.events.Event;
        import flash.net.URLLoader;
        import flash.net.URLRequest;
        import flash.text.TextField;
        import flash.text.TextFieldAutoSize;
        import flash.xml.*;
        import flash.events.IOErrorEvent;

        public class URLLoader_loadExample extends Sprite {
            private var xmlTextField:TextField = new TextField();
            private var externalXML:XML;
            private var loader:URLLoader;

            public function URLLoader_loadExample() {
                var request:URLRequest = new URLRequest("xmlFile.xml");

                loader = new URLLoader();

                try {
                    loader.load(request);
                }
                catch (error:SecurityError)
                {
                    trace("A SecurityError has occurred.");
                }

                 loader.addEventListener(IOErrorEvent.IO_ERROR, errorHandler);
                loader.addEventListener(Event.COMPLETE, loaderCompleteHandler);

                xmlTextField.x = 10;
                xmlTextField.y = 10;
                xmlTextField.background = true;
                xmlTextField.autoSize = TextFieldAutoSize.LEFT;

                addChild(xmlTextField);
            }

            private function loaderCompleteHandler(event:Event):void {

                    try {
                        externalXML = new XML(loader.data);
                        readNodes(externalXML);
                    } catch (e:TypeError) {
                        trace("Could not parse the XML file.");
                    }
            }

            private function readNodes(node:XML):void {

                    for each (var element:XML in node.elements()) {
                        xmlTextField.appendText(element.attributes()[0] + "\n");

                        readNodes(element);
                    }
            }

            private function errorHandler(e:IOErrorEvent):void {
                xmlTextField.text = "Had problem loading the XML File.";
            }
        }
    }

Event Detail

complete | Event

Event Object Type: `flash.events.Event`
Event.type property = `flash.events.Event.COMPLETE`

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9

Dispatched after all the received data is decoded and placed in the `data` property of the URLLoader object. The received data may be accessed once this event has been dispatched.

Defines the value of the `type` property of a `complete` event object.

This event has the following properties:

Property | Value
--- | ---
`bubbles` | `false`
`cancelable` | `false`; there is no default behavior to cancel.
`currentTarget` | The object that is actively processing the Event object with an event listener.
`target` | The network object that has completed loading.

See also

URLLoader.load()

httpStatus | Event |

Event Object Type: `flash.events.HTTPStatusEvent`
HTTPStatusEvent.type property = `flash.events.HTTPStatusEvent.HTTP_STATUS`

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9

Dispatched if a call to `URLLoader.load()` attempts to access data over HTTP and the current Flash Player environment is able to detect and return the status code for the request. (Some browser environments may not be able to provide this information.) Note that the `httpStatus` event (if any) is sent before (and in addition to) any `complete` or `error` event.

Defines the value of the `type` property of a `httpStatus` event object.

This event has the following properties:

Property | Value
--- | ---
`bubbles` | `false`
`cancelable` | `false`; there is no default behavior to cancel.
`currentTarget` | The object that is actively processing the Event object with an event listener.
`status` | The HTTP status code returned by the server.
`target` | The network object receiving an HTTP status code.

See also

URLLoader.load()

ioError | Event |

Event Object Type: `flash.events.IOErrorEvent`
IOErrorEvent.type property = `flash.events.IOErrorEvent.IO_ERROR`

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9

Dispatched if a call to `URLLoader.load()` results in a fatal error that terminates the download.

Defines the value of the `type` property of an `ioError` event object.

This event has the following properties:

Property | Value
--- | ---
`bubbles` | `false`
`cancelable` | `false`; there is no default behavior to cancel.
`currentTarget` | The object that is actively processing the Event object with an event listener.
`target` | The network object experiencing the input/output error.
`text` | Text to be displayed as an error message.

See also

URLLoader.load()

open | Event |

Event Object Type: `flash.events.Event`
Event.type property = `flash.events.Event.OPEN`

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9

Dispatched when the download operation commences following a call to the `URLLoader.load()` method.

Defines the value of the `type` property of an `open` event object.

This event has the following properties:

Property | Value
--- | ---
`bubbles` | `false`
`cancelable` | `false`; there is no default behavior to cancel.
`currentTarget` | The object that is actively processing the Event object with an event listener.
`target` | The network object that has opened a connection.

See also

URLLoader.load()

progress | Event |

Event Object Type: `flash.events.ProgressEvent`
ProgressEvent.type property = `flash.events.ProgressEvent.PROGRESS`

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9

Dispatched when data is received as the download operation progresses.

Note that with a URLLoader object, it is not possible to access the data until it has been received completely. So, the progress event only serves as a notification of how far the download has progressed. To access the data before it's entirely downloaded, use a URLStream object.

Defines the value of the `type` property of a `progress` event object.

This event has the following properties:

Property | Value
--- | ---
`bubbles` | `false`
`bytesLoaded` | The number of items or bytes loaded at the time the listener processes the event.
`bytesTotal` | The total number of items or bytes that ultimately will be loaded if the loading process succeeds.
`cancelable` | `false`; there is no default behavior to cancel.
`currentTarget` | The object that is actively processing the Event object with an event listener.
`target` | The network object reporting progress.

See also

URLLoader.load()

securityError | Event |

Event Object Type: `flash.events.SecurityErrorEvent`
SecurityErrorEvent.type property = `flash.events.SecurityErrorEvent.SECURITY_ERROR`

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9

Dispatched if a call to `URLLoader.load()` attempts to load data from a server outside the security sandbox.

The `SecurityErrorEvent.SECURITY_ERROR` constant defines the value of the `type` property of a `securityError` event object.

This event has the following properties:

Property | Value
--- | ---
`bubbles` | `false`
`cancelable` | `false`; there is no default behavior to cancel.
`currentTarget` | The object that is actively processing the Event object with an event listener.
`target` | The network object reporting the security error.
`text` | Text to be displayed as an error message.

See also

URLLoader.load()
Flash Player security
Examples How to use examples
URLLoaderExample.as
The following example loads and displays the data found in a local text file. It also traces event handling information.

Note: To run this example, put a file named urlLoaderExample.txt in the same directory as your SWF file. That file should only contain the following line of text: `answer=42&question=unknown`

The example code does the following:

1. The constructor function creates a URLLoader instance named `loader` and a URLRequest instance named `request`, which contains the location and name of the file to be loaded.
2. The `loader` object is passed to the `configureListeners()` method, which adds listeners for each of the supported URLLoader events.
3. The `request` object is then passed to `loader.load()`, which loads the text file.
4. When the URLLoader has finished loading the text file the `Event.COMPLETE event` fires, triggering the `completeHandler()` method. The `completeHandler()` method creates a URLVariables object from the text loaded from the file. The URLVariables object converts URL-encoded name/value pairs into ActionScript properties to make it easier to manipulate the loaded data.

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

        public class URLLoaderExample extends Sprite {
            public function URLLoaderExample() {
                var loader:URLLoader = new URLLoader();
                configureListeners(loader);

                var request:URLRequest = new URLRequest("urlLoaderExample.txt");
                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);

                var vars:URLVariables = new URLVariables(loader.data);
                trace("The answer is " + vars.answer);
            }

            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