class flash.net.URLLoader extends EventDispatcher

Available on all platforms

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 code in the applications. 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 loading very large video files, such as FLV's, out-of-memory errors * may occur.

*

When you use this class in Flash Player and in AIR application content * in security sandboxes other than then application security sandbox, * consider the following 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 Flash Player Developer * Center Topic: <a href="http://www.adobe.com/go/devnetsecurityen" * scope="external">Security.

* * @event complete 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. * @event httpResponseStatus Dispatched if a call to the load() method * attempts to access data over HTTP, and Adobe AIR * is able to detect and return the status code for * the request. * @event httpStatus Dispatched if a call to URLLoader.load() attempts * to access data over HTTP. For content running in * Flash Player, this event is only dispatched if * 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. * @event ioError Dispatched if a call to URLLoader.load() results * in a fatal error that terminates the download. * @event open Dispatched when the download operation commences * following a call to the * URLLoader.load() method. * @event progress 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.

* @event securityError Dispatched if a call to URLLoader.load() attempts * to load data from a server outside the security * sandbox. Also dispatched if a call to * URLLoader.load() attempts to load a * SWZ file and the certificate is invalid or the * digest string does not match the component.

Instance Fields

var bytesLoaded:UInt

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

var bytesTotal:UInt

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.

var data:Dynamic

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.

var dataFormat:URLLoaderDataFormat

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.

* * @default URLLoaderDataFormat.TEXT

function new(?request:URLRequest):Void

Creates a URLLoader object. * *

request

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).

function close():Void

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.

function load(request:URLRequest):Void

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 cannot connect to commonly reserved ports. For a complete list of * blocked ports, see "Restricting Networking APIs" in the ActionScript * 3.0 Developer's Guide.

*

In Flash Player 10 and later, if you use a multipart Content-Type(for * example "multipart/form-data") that contains an upload(indicated by a * "filename" parameter in a "content-disposition" header within the POST * body), the POST operation is subject to the security rules applied to * uploads:

*
    *
  • The POST operation must be performed in response to a user-initiated * action, such as a mouse click or key press.
  • *
  • If the POST operation is cross-domain(the POST target is not on the * same server as the SWF file that is sending the POST request), the target * server must provide a URL policy file that permits cross-domain * access.
  • *
*

Also, for any multipart Content-Type, the syntax must be valid * (according to the RFC2046 standards). If the syntax appears to be invalid, * the POST operation is subject to the security rules applied to * uploads.

*

For more information related to security, see the Flash Player * Developer Center Topic: <a * href="http://www.adobe.com/go/devnetsecurityen" * scope="external">Security.

* * @event complete Dispatched after data has loaded successfully. * @event httpResponseStatus Dispatched if a call to the load() * method attempts to access data over HTTP and * Adobe AIR is able to detect and return the * status code for the request. * @event httpStatus 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. * @event ioError The load operation could not be completed. * @event open Dispatched when a load operation commences. * @event progress Dispatched when data is received as the download * operation progresses. * @event securityError 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. * @event securityError A load operation attempted to load a SWZ file(a * Adobe platform component), but the certificate * is invalid or the digest does not match the * component.

request

A URLRequest object specifying the URL to download. *