openfl.net.URLStream - OpenFL API Reference

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 OpenFL 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: 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 OpenFL 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 Haxe code. 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 Haxe code. 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 Haxe code. 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 Haxe code. 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 Haxe code. 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 Haxe code. 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.

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 Haxe code. 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 Haxe code. 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 Haxe code. 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 Haxe code. 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 Haxe code. 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 Haxe code. 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 Haxe code. 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.

class URLStream

package openfl.net

extends EventDispatcher

implements IDataInput

Constructor

`new()`

Variables

`read onlybytesAvailable:UInt`

`read onlyconnected:Bool`

`endian:Endian`

`objectEncoding:ObjectEncoding`

Methods

`close():Void`

`load(request:URLRequest):Void`

`readBoolean():Bool`

`readByte():Int`

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

`readDouble():Float`

`readFloat():Float`

`readInt():Int`

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

`readObject():Dynamic`

`readShort():Int`

`readUTF():String`

`readUTFBytes(length:UInt):String`

`readUnsignedByte():UInt`

`readUnsignedInt():UInt`

`readUnsignedShort():UInt`

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`

`dispatchEvent(event:Event):Bool`

`hasEventListener(type:String):Bool`

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

`toString():String`

`willTrigger(type:String):Bool`