The URLStream class provides low-level access to downloading URLs. Data is made available to application code immediately as it is downloaded, instead of waiting until the entire file is complete as with URLLoader. The URLStream class also lets you close a stream before it finishes downloading. The contents of the downloaded file are made available as raw binary data. The read operations in URLStream are nonblocking. This means that you must use the bytesAvailable property to determine whether sufficient data is available before reading it. An EOFError exception is thrown if insufficient data is available.

All binary data is encoded by default in big-endian format, with the most significant byte first.

The security rules that apply to URL downloading with the URLStream class are identical to the rules applied to URLLoader objects. Policy files may be downloaded as needed. Local file security rules are enforced, and security warnings are raised as needed.

Events:

complete

Dispatched when data has loaded successfully.

httpResponseStatus

Dispatched if a call to the URLStream.load() method attempts to access data over HTTP and Adobe AIR is able to detect and return the status code for the request. If a URLStream object registers for an httpStatusEvent event, error responses are delivered as though they are content. So instead of dispatching an ioError event, the URLStream dispatches progress and complete events as the error data is loaded into the URLStream.

httpStatus

Dispatched if a call to URLStream.load() attempts to access data over HTTP, and Flash Player or Adobe AIR 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 (if any) will be sent before (and in addition to) any complete or error event.

ioError

Dispatched when an input/output error occurs that causes a load operation to fail.

open

Dispatched when a load operation starts.

progress

Dispatched when data is received as the download operation progresses. Data that has been received can be read immediately using the methods of the URLStream class.

securityError

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

Constructor

new()

Variables

read onlybytesAvailable:UInt

Returns the number of bytes of data available for reading in the input buffer. Your code must call the bytesAvailable property to ensure that sufficient data is available before you try to read it with one of the read methods.

read onlyconnected:Bool

Indicates whether this URLStream object is currently connected. A call to this property returns a value of true if the URLStream object is connected, or false otherwise.

endian:Endian

Indicates the byte order for the data. Possible values are Endian.BIG_ENDIAN or Endian.LITTLE_ENDIAN.

objectEncoding:ObjectEncoding

Controls the version of Action Message Format (AMF) used when writing or reading an object.

Methods

close():Void

Immediately closes the stream and cancels the download operation. No data can be read from the stream after the close() method is called.

Throws:

IOError

The stream could not be closed, or the stream was not open.

load(request:URLRequest):Void

Begins downloading the URL specified in the request parameter. 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.

If the loading operation fails immediately, an IOError or SecurityError (including the local file security error) exception is thrown describing the failure. Otherwise, an open event is dispatched if the URL download starts downloading successfully, or an error event is dispatched if an error occurs.

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.

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

In Flash Player 10 and later, and in AIR 1.5 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.

These rules also apply to AIR content in non-application sandboxes. However, in Adobe AIR, content in the application sandbox (content installed with the AIR application) are not restricted by these security limitations.

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

In AIR, a URLRequest object can register for the httpResponse status event. Unlike the httpStatus event, the httpResponseStatus event is delivered before any response data. Also, the httpResponseStatus event includes values for the responseHeaders and responseURL properties (which are undefined for an httpStatus event. Note that the httpResponseStatus event (if any) will be sent before (and in addition to) any complete or error event.

If there is an httpResponseStatus event listener, the body of the response message is always sent; and HTTP status code responses always results in a complete event. This is true in spite of whether the HTTP response status code indicates a success or an error.

In AIR, if there is no httpResponseStatus event listener, the behavior differs based on the SWF version:

  • For SWF 9 content, the body of the HTTP response message is sent only if the HTTP response status code indicates success. Otherwise (if there is an error), no body is sent and the URLRequest object dispatches an IOError event.
  • For SWF 10 content, the body of the HTTP response message is always sent. If there is an error, the URLRequest object dispatches an IOError event.

Parameters:

request

A URLRequest object specifying the URL to download. If the value of this parameter or the URLRequest.url property of the URLRequest object passed are null, the application throws a null pointer error.

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 or Adobe AIR 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 or Adobe AIR 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.

SecurityError

You are trying to connect to a commonly reserved port. For a complete list of blocked ports, see "Restricting Networking APIs" in the ActionScript 3.0 Developer's Guide.

Events:

complete

Dispatched after data has loaded successfully. If there is a httpResponseStatus event listener, the URLRequest object also dispatches a complete event whether the HTTP response status code indicates a success or an error.

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.

httpStatus

If access is by HTTP and the current environment supports obtaining status codes, you may receive these events in addition to any complete or error event.

ioError

The load operation could not be completed.

open

Dispatched when a load operation starts.

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.

readBoolean():Bool

Reads a Boolean value from the stream. A single byte is read, and true is returned if the byte is nonzero, false otherwise.

Returns:

True is returned if the byte is nonzero, false otherwise.

Throws:

EOFError

There is insufficient data available to read. If a local SWF file triggers a security warning, Flash Player prevents the URLStream data from being available to ActionScript. When this happens, the bytesAvailable property returns 0 even if data has been received, and any of the read methods throws an EOFError exception.

IOError

An I/O error occurred on the stream, or the stream is not open.

readByte():Int

Reads a signed byte from the stream. The returned value is in the range -128...127.

Returns:

Value in the range -128...127.

Throws:

EOFError

There is insufficient data available to read. If a local SWF file triggers a security warning, Flash Player prevents the URLStream data from being available to ActionScript. When this happens, the bytesAvailable property returns 0 even if data has been received, and any of the read methods throws an EOFError exception.

IOError

An I/O error occurred on the stream, or the stream is not open.

@:value({ length : 0, offset : 0 })readBytes(bytes:ByteArray, offset:UInt = 0, length:Int = 0):Void

Reads length bytes of data from the stream. The bytes are read into the ByteArray object specified by bytes, starting offset bytes into the ByteArray object.

Parameters:

bytes

The ByteArray object to read data into.

offset

The offset into bytes at which data read should begin. Defaults to 0.

length

The number of bytes to read. The default value of 0 will cause all available data to be read.

Throws:

EOFError

There is insufficient data available to read. If a local SWF file triggers a security warning, Flash Player prevents the URLStream data from being available to ActionScript. When this happens, the bytesAvailable property returns 0 even if data has been received, and any of the read methods throws an EOFError exception.

IOError

An I/O error occurred on the stream, or the stream is not open.

readDouble():Float

Reads an IEEE 754 double-precision floating-point number from the stream.

Returns:

An IEEE 754 double-precision floating-point number from the stream.

Throws:

EOFError

There is insufficient data available to read. If a local SWF file triggers a security warning, Flash Player prevents the URLStream data from being available to ActionScript. When this happens, the bytesAvailable property returns 0 even if data has been received, and any of the read methods throws an EOFError exception.

IOError

An I/O error occurred on the stream, or the stream is not open.

readFloat():Float

Reads an IEEE 754 single-precision floating-point number from the stream.

Returns:

An IEEE 754 single-precision floating-point number from the stream.

Throws:

EOFError

There is insufficient data available to read. If a local SWF file triggers a security warning, Flash Player prevents the URLStream data from being available to ActionScript. When this happens, the bytesAvailable property returns 0 even if data has been received, and any of the read methods throws an EOFError exception.

IOError

An I/O error occurred on the stream, or the stream is not open.

readInt():Int

Reads a signed 32-bit integer from the stream. The returned value is in the range -2147483648...2147483647.

Returns:

Value in the range -2147483648...2147483647.

Throws:

EOFError

There is insufficient data available to read. If a local SWF file triggers a security warning, Flash Player prevents the URLStream data from being available to ActionScript. When this happens, the bytesAvailable property returns 0 even if data has been received, and any of the read methods throws an EOFError exception.

IOError

An I/O error occurred on the stream, or the stream is not open.

readMultiByte(length:UInt, charSet:String):String

Reads a multibyte string of specified length from the byte stream using the specified character set.

Parameters:

length

The number of bytes from the byte stream to read.

charSet

The string denoting the character set to use to interpret the bytes. Possible character set strings include "shift_jis", "CN-GB", "iso-8859-1", and others. For a complete list, see <a href="../../charset-codes.html">Supported Character Sets. Note: If the value for the charSet parameter is not recognized by the current system, the application uses the system's default code page as the character set. For example, a value for the charSet parameter, as in myTest.readMultiByte(22, "iso-8859-01") that uses 01 instead of 1 might work on your development machine, but not on another machine. On the other machine, the application will use the system's default code page.

Returns:

UTF-8 encoded string.

Throws:

EOFError

There is insufficient data available to read. If a local SWF file triggers a security warning, Flash Player prevents the URLStream data from being available to ActionScript. When this happens, the bytesAvailable property returns 0 even if data has been received, and any of the read methods throws an EOFError exception.

readObject():Dynamic

Reads an object from the socket, encoded in Action Message Format (AMF).

Returns:

The deserialized object.

Throws:

EOFError

There is insufficient data available to read. If a local SWF file triggers a security warning, Flash Player prevents the URLStream data from being available to ActionScript. When this happens, the bytesAvailable property returns 0 even if data has been received, and any of the read methods throws an EOFError exception.

IOError

An I/O error occurred on the stream, or the stream is not open.

readShort():Int

Reads a signed 16-bit integer from the stream. The returned value is in the range -32768...32767.

Returns:

Value in the range -32768...32767.

Throws:

EOFError

There is insufficient data available to read. If a local SWF file triggers a security warning, Flash Player prevents the URLStream data from being available to ActionScript. When this happens, the bytesAvailable property returns 0 even if data has been received, and any of the read methods throws an EOFError exception.

IOError

An I/O error occurred on the stream, or the stream is not open.

readUTF():String

Reads a UTF-8 string from the stream. The string is assumed to be prefixed with an unsigned short indicating the length in bytes.

Returns:

A UTF-8 string.

Throws:

EOFError

There is insufficient data available to read. If a local SWF file triggers a security warning, Flash Player prevents the URLStream data from being available to ActionScript. When this happens, the bytesAvailable property returns 0 even if data has been received, and any of the read methods throws an EOFError exception.

IOError

An I/O error occurred on the stream, or the stream is not open.

readUTFBytes(length:UInt):String

Reads a sequence of length UTF-8 bytes from the stream, and returns a string.

Parameters:

length

A sequence of UTF-8 bytes.

Returns:

A UTF-8 string produced by the byte representation of characters of specified length.

Throws:

EOFError

There is insufficient data available to read. If a local SWF file triggers a security warning, Flash Player prevents the URLStream data from being available to ActionScript. When this happens, the bytesAvailable property returns 0 even if data has been received, and any of the read methods throws an EOFError exception.

IOError

An I/O error occurred on the stream, or the stream is not open.

readUnsignedByte():UInt

Reads an unsigned byte from the stream. The returned value is in the range 0...255.

Returns:

Value in the range 0...255.

Throws:

EOFError

There is insufficient data available to read. If a local SWF file triggers a security warning, Flash Player prevents the URLStream data from being available to ActionScript. When this happens, the bytesAvailable property returns 0 even if data has been received, and any of the read methods throws an EOFError exception.

IOError

An I/O error occurred on the stream, or the stream is not open.

readUnsignedInt():UInt

Reads an unsigned 32-bit integer from the stream. The returned value is in the range 0...4294967295.

Returns:

Value in the range 0...4294967295.

Throws:

EOFError

There is insufficient data available to read. If a local SWF file triggers a security warning, Flash Player prevents the URLStream data from being available to ActionScript. When this happens, the bytesAvailable property returns 0 even if data has been received, and any of the read methods throws an EOFError exception.

IOError

An I/O error occurred on the stream, or the stream is not open.

readUnsignedShort():UInt

Reads an unsigned 16-bit integer from the stream. The returned value is in the range 0...65535.

Returns:

Value in the range 0...65535.

Throws:

EOFError

There is insufficient data available to read. If a local SWF file triggers a security warning, Flash Player prevents the URLStream data from being available to ActionScript. When this happens, the bytesAvailable property returns 0 even if data has been received, and any of the read methods throws an EOFError exception.

IOError

An I/O error occurred on the stream, or the stream is not open.

Inherited Variables

Inherited Methods

Defined by EventDispatcher

@:value({ useWeakReference : false, priority : 0, useCapture : false })addEventListener<T>(type:EventType<T>, listener:T ‑> Void, useCapture:Bool = false, priority:Int = 0, useWeakReference:Bool = false):Void

Registers an event listener object with an EventDispatcher object so that the listener receives notification of an event. You can register event listeners on all nodes in the display list for a specific type of event, phase, and priority.

After you successfully register an event listener, you cannot change its priority through additional calls to addEventListener(). To change a listener's priority, you must first call removeListener(). Then you can register the listener again with the new priority level.

Keep in mind that after the listener is registered, subsequent calls to addEventListener() with a different type or useCapture value result in the creation of a separate listener registration. For example, if you first register a listener with useCapture set to true, it listens only during the capture phase. If you call addEventListener() again using the same listener object, but with useCapture set to false, you have two separate listeners: one that listens during the capture phase and another that listens during the target and bubbling phases.

You cannot register an event listener for only the target phase or the bubbling phase. Those phases are coupled during registration because bubbling applies only to the ancestors of the target node.

If you no longer need an event listener, remove it by calling removeEventListener(), or memory problems could result. Event listeners are not automatically removed from memory because the garbage collector does not remove the listener as long as the dispatching object exists(unless the useWeakReference parameter is set to true).

Copying an EventDispatcher instance does not copy the event listeners attached to it.(If your newly created node needs an event listener, you must attach the listener after creating the node.) However, if you move an EventDispatcher instance, the event listeners attached to it move along with it.

If the event listener is being registered on a node while an event is being processed on this node, the event listener is not triggered during the current phase but can be triggered during a later phase in the event flow, such as the bubbling phase.

If an event listener is removed from a node while an event is being processed on the node, it is still triggered by the current actions. After it is removed, the event listener is never invoked again(unless registered again for future processing).

Parameters:

type

The type of event.

useCapture

Determines whether the listener works in the capture phase or the target and bubbling phases. If useCapture is set to true, the listener processes the event only during the capture phase and not in the target or bubbling phase. If useCapture is false, the listener processes the event only during the target or bubbling phase. To listen for the event in all three phases, call addEventListener twice, once with useCapture set to true, then again with useCapture set to false.

priority

The priority level of the event listener. The priority is designated by a signed 32-bit integer. The higher the number, the higher the priority. All listeners with priority n are processed before listeners of priority n-1. If two or more listeners share the same priority, they are processed in the order in which they were added. The default priority is 0.

useWeakReference

Determines whether the reference to the listener is strong or weak. A strong reference(the default) prevents your listener from being garbage-collected. A weak reference does not.

Class-level member functions are not subject to garbage collection, so you can set useWeakReference to true for class-level member functions without subjecting them to garbage collection. If you set useWeakReference to true for a listener that is a nested inner function, the function will be garbage-collected and no longer persistent. If you create references to the inner function(save it in another variable) then it is not garbage-collected and stays persistent.

Weak references are supported on some OpenFL targets only, including html5, cpp, and flash/air. On other targets, this parameter is ignored, and the reference will be strong instead.

Throws:

ArgumentError

The listener specified is not a function.

dispatchEvent(event:Event):Bool

Dispatches an event into the event flow. The event target is the EventDispatcher object upon which the dispatchEvent() method is called.

Parameters:

event

The Event object that is dispatched into the event flow. If the event is being redispatched, a clone of the event is created automatically. After an event is dispatched, its target property cannot be changed, so you must create a new copy of the event for redispatching to work.

Returns:

A value of true if the event was successfully dispatched. A value of false indicates failure or that preventDefault() was called on the event.

Throws:

Error

The event dispatch recursion limit has been reached.

hasEventListener(type:String):Bool

Checks whether the EventDispatcher object has any listeners registered for a specific type of event. This allows you to determine where an EventDispatcher object has altered handling of an event type in the event flow hierarchy. To determine whether a specific event type actually triggers an event listener, use willTrigger().

The difference between hasEventListener() and willTrigger() is that hasEventListener() examines only the object to which it belongs, whereas willTrigger() examines the entire event flow for the event specified by the type parameter.

When hasEventListener() is called from a LoaderInfo object, only the listeners that the caller can access are considered.

Parameters:

type

The type of event.

Returns:

A value of true if a listener of the specified type is registered; false otherwise.

@:value({ useCapture : false })removeEventListener<T>(type:EventType<T>, listener:T ‑> Void, useCapture:Bool = false):Void

Removes a listener from the EventDispatcher object. If there is no matching listener registered with the EventDispatcher object, a call to this method has no effect.

Parameters:

type

The type of event.

useCapture

Specifies whether the listener was registered for the capture phase or the target and bubbling phases. If the listener was registered for both the capture phase and the target and bubbling phases, two calls to removeEventListener() are required to remove both, one call with useCapture() set to true, and another call with useCapture() set to false.

toString():String

willTrigger(type:String):Bool

Checks whether an event listener is registered with this EventDispatcher object or any of its ancestors for the specified event type. This method returns true if an event listener is triggered during any phase of the event flow when an event of the specified type is dispatched to this EventDispatcher object or any of its descendants.

The difference between the hasEventListener() and the willTrigger() methods is that hasEventListener() examines only the object to which it belongs, whereas the willTrigger() method examines the entire event flow for the event specified by the type parameter.

When willTrigger() is called from a LoaderInfo object, only the listeners that the caller can access are considered.

Parameters:

type

The type of event.

Returns:

A value of true if a listener of the specified type will be triggered; false otherwise.