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.
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 If the dataFormat
property:
* 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
* ( If the value of the URLLoaderDataFormat.TEXT
), raw binary data
* (URLLoaderDataFormat.BINARY
), or URL-encoded variables
* (URLLoaderDataFormat.VARIABLES
).
* 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.
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
* |
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 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.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.
*
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 theload()
* 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. * |