Language Version : | ActionScript 3.0 |
Player Version : | Flash Player 9 |
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.
View the examples
bytesAvailable:uint
[read-only]
Language Version : | ActionScript 3.0 |
Player Version : | Flash Player 9 |
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.
Implementation
public function get bytesAvailable():uint
connected:Boolean
[read-only]
Language Version : | ActionScript 3.0 |
Player Version : | Flash Player 9 |
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.
Implementation
public function get connected():Boolean
endian:String
[read-write]
Language Version : | ActionScript 3.0 |
Player Version : | Flash Player 9 |
Indicates the byte order for the data. Possible values are
Endian.BIG_ENDIAN
or Endian.LITTLE_ENDIAN
.
The default value is Endian.BIG_ENDIAN
.
Implementation
public function get endian():String
public function set endian(value:String):void
See also
objectEncoding:uint
[read-write]
Language Version : | ActionScript 3.0 |
Player Version : | Flash Player 9 |
Controls the version of Action Message Format (AMF) used when writing or reading an object.
Implementation
public function get objectEncoding():uint
public function set objectEncoding(value:uint):void
See also
public function close():void
Language Version : | ActionScript 3.0 |
Player Version : | Flash Player 9 |
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.
|
public function load(request:URLRequest):void
Language Version : | ActionScript 3.0 |
Player Version : | Flash Player 9 |
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.
When using this method, consider the Adobe® Flash® Player security model:
- Data loading is not allowed if the calling SWF file is in the
local-with-file-system sandbox and the target resource is from a network sandbox.
- Data loading is also not allowed if the calling SWF file is from a network sandbox and
the target resource is local.
- By default, the URL you load must be in exactly the same domain as the calling SWF
file. 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, put a
cross-domain policy file on the server hosting the data.
- You can prevent a SWF file running in Flash Player 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.
However, in Adobe AIR, content in the application
security sandbox (content
installed with the AIR application) are not restricted by these security limitations.
For more information, see the following:
- The security chapter
in the Programming ActionScript 3.0 book and the latest comments on LiveDocs
- The "Understanding AIR Security" section of the "Getting started with Adobe AIR" chapter
in the Developing AIR Applications book.
- The Flash Player 9 Security white paper
Parameters
| request:URLRequest — 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.
|
Events
| complete:Event — Dispatched after data has loaded successfully. |
|
| httpStatus:HTTPStatusEvent — 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. |
|
| httpResponseStatus:HTTPStatusEvent — 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. |
|
| ioError:IOErrorEvent — The load operation could not be
completed. |
|
| open:Event — Dispatched when a load operation starts. |
|
| 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. |
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:
- 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 .
- 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 files may not communicate with
the Internet. This may be worked around by reclassifying this file
as local-with-networking or trusted.
|
See also
public function readBoolean():Boolean
Language Version : | ActionScript 3.0 |
Player Version : | Flash Player 9 |
Reads a Boolean value from the stream. A single byte is read,
and true
is returned if the byte is nonzero,
false
otherwise.
Returns
| Boolean —
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.
|
public function readByte():int
Language Version : | ActionScript 3.0 |
Player Version : | Flash Player 9 |
Reads a signed byte from the stream.
The returned value is in the range -128...127.
Returns
| int — 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.
|
public function readBytes(bytes:ByteArray, offset:uint = 0, length:uint = 0):void
Language Version : | ActionScript 3.0 |
Player Version : | Flash Player 9 |
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:ByteArray — The ByteArray object to read
data into.
|
|
| offset:uint (default = 0 ) — The offset into bytes at which data
read should begin. Defaults to 0.
|
|
| length:uint (default = 0 ) — 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.
|
public function readDouble():Number
Language Version : | ActionScript 3.0 |
Player Version : | Flash Player 9 |
Reads an IEEE 754 double-precision floating-point number from the stream.
Returns
| Number — 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.
|
public function readFloat():Number
Language Version : | ActionScript 3.0 |
Player Version : | Flash Player 9 |
Reads an IEEE 754 single-precision floating-point number from the stream.
Returns
| Number — 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.
|
public function readInt():int
Language Version : | ActionScript 3.0 |
Player Version : | Flash Player 9 |
Reads a signed 32-bit integer from the stream.
The returned value is in the range -2147483648...2147483647.
Returns
| int — 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.
|
public function readMultiByte(length:uint, charSet:String):String
Language Version : | ActionScript 3.0 |
Player Version : | Flash Player 9 |
Reads a multibyte string of specified length from the byte stream using the
specified character set.
Parameters
| length:uint — The number of bytes from the byte stream to read.
|
|
| charSet:String — 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 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
| String — 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.
|
public function readObject():*
Language Version : | ActionScript 3.0 |
Player Version : | Flash Player 9 |
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.
|
See also
public function readShort():int
Language Version : | ActionScript 3.0 |
Player Version : | Flash Player 9 |
Reads a signed 16-bit integer from the stream.
The returned value is in the range -32768...32767.
Returns
| int — 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.
|
public function readUnsignedByte():uint
Language Version : | ActionScript 3.0 |
Player Version : | Flash Player 9 |
Reads an unsigned byte from the stream.
The returned value is in the range 0...255.
Returns
| uint — 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.
|
public function readUnsignedInt():uint
Language Version : | ActionScript 3.0 |
Player Version : | Flash Player 9 |
Reads an unsigned 32-bit integer from the stream.
The returned value is in the range 0...4294967295.
Returns
| uint — 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.
|
public function readUnsignedShort():uint
Language Version : | ActionScript 3.0 |
Player Version : | Flash Player 9 |
Reads an unsigned 16-bit integer from the stream.
The returned value is in the range 0...65535.
Returns
| uint — 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.
|
public function readUTF():String
Language Version : | ActionScript 3.0 |
Player Version : | Flash Player 9 |
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
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.
|
public function readUTFBytes(length:uint):String
Language Version : | ActionScript 3.0 |
Player Version : | Flash Player 9 |
Reads a sequence of length
UTF-8
bytes from the stream, and returns a string.
Parameters
| length:uint — A sequence of UTF-8 bytes.
|
Returns
| String — 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.
|
Event Object Type: flash.events.Event
Event.type property = flash.events.Event.COMPLETE
Language Version : | ActionScript 3.0 |
Player Version : | Flash Player 9 |
Dispatched when data has loaded successfully.
The
Event.COMPLETE
constant 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.
|
Event Object Type: flash.events.HTTPStatusEvent
HTTPStatusEvent.type property = flash.events.HTTPStatusEvent.HTTP_RESPONSE_STATUS
Language Version : | ActionScript 3.0 |
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.
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.
The HTTPStatusEvent.HTTP_RESPONSE_STATUS
constant defines the value of the
type
property of a httpResponseStatus
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. |
responseURL | The URL from which the response was returned. |
responseHeaders | The response headers that the response returned,
as an array of URLRequestHeader objects. |
status | The HTTP status code returned by the server. |
target | The network object receiving an HTTP status code. |
See also
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 URLStream.load()
attempts to access data over HTTP, and Flash Player or 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.
The
HTTPStatusEvent.HTTP_STATUS
constant 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
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 when an input/output error occurs that causes a load operation to fail.
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. |
errorID | A reference number associated with the specific error. |
target | The network object experiencing the input/output error. |
text | Text to be displayed as an error message. |
See also
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 a load operation starts.
The
Event.OPEN
constant 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
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.
Data that has been received can be read immediately using the methods of the URLStream class.
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 object reporting progress. |
See also
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 URLStream.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
The following example loads a SWF file and parses the beginning of its header to indicate
compression and version number information.
To run the example, place a file named URLStreamExample.swf in the same directory as your SWF file.
package {
import flash.display.Sprite;
import flash.errors.*;
import flash.events.*;
import flash.net.URLRequest;
import flash.net.URLStream;
public class URLStreamExample extends Sprite {
private static const ZLIB_CODE:String = "CWS";
private var stream:URLStream;
public function URLStreamExample() {
stream = new URLStream();
var request:URLRequest = new URLRequest("URLStreamExample.swf");
configureListeners(stream);
try {
stream.load(request);
} catch (error:Error) {
trace("Unable to load requested URL.");
}
}
private function configureListeners(dispatcher:EventDispatcher):void {
dispatcher.addEventListener(Event.COMPLETE, completeHandler);
dispatcher.addEventListener(HTTPStatusEvent.HTTP_STATUS, httpStatusHandler);
dispatcher.addEventListener(IOErrorEvent.IO_ERROR, ioErrorHandler);
dispatcher.addEventListener(Event.OPEN, openHandler);
dispatcher.addEventListener(ProgressEvent.PROGRESS, progressHandler);
dispatcher.addEventListener(SecurityErrorEvent.SECURITY_ERROR, securityErrorHandler);
}
private function parseHeader():void {
trace("parseHeader");
trace("isCompressed: " + isCompressed());
trace("version: " + stream.readByte());
}
private function isCompressed():Boolean {
return (stream.readUTFBytes(3) == ZLIB_CODE);
}
private function completeHandler(event:Event):void {
trace("completeHandler: " + event);
parseHeader();
}
private function openHandler(event:Event):void {
trace("openHandler: " + event);
}
private function progressHandler(event:Event):void {
trace("progressHandler: " + event);
}
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);
}
}
}
© 2004-2007 Adobe Systems Incorporated. All rights reserved.
Tue Mar 18 2008, 12:59 PM GMT-07:00