window.runtime 属性window.runtime.flash.net.URLStream
继承URLStream Inheritance EventDispatcher Inheritance Object
运行时版本:  1.0

URLStream 类提供对下载 URL 的低级访问。数据一下载,便可随即为应用程序使用,这和使用 URLLoader 时需要等到整个文件下载完不同。并且 URLStream 类还允许在完成下载前关闭流。已下载文件的内容将作为原始二进制数据提供。

在 URLStream 中的读取操作是非阻塞模式的。这意味着您在读取数据之前必须使用 bytesAvailable 属性来确定是否能够获得足够的数据。如果不能获得足够的数据,将引发 EOFError 异常。

在默认情况下,所有二进制数据都是以 Big-endian 格式编码的,并且最高位字节于第一位。

适用于通过 URLStream 类进行 URL 下载的安全规则与适用于 URLLoader 对象的规则相同。如有需要也可以下载策略文件。将强制执行本地文件安全规则,并根据需要发出安全警告。

查看示例

另请参见

URLLoader
URLRequest


属性
 属性定义方
  bytesAvailable : uint
[只读 (read-only)] 返回可在输入缓冲区中读取的数据的字节数。
URLStream
  connected : Boolean
[只读 (read-only)] 指示此 URLStream 对象目前是否已连接。
URLStream
 Inheritedconstructor : Object
对类对象或给定对象实例的构造函数的引用。
Object
  endian : String
指示数据的字节顺序。
URLStream
  objectEncoding : uint
在写入或读取对象时,控制所使用的 Action Message Format (AMF) 的版本。
URLStream
 Inheritedprototype : Object
[静态] 对类或函数对象的原型对象的引用。
Object
公共方法
 方法定义方
 Inherited
addEventListener(type:String, listener:Function, useCapture:Boolean = false, priority:int = 0, useWeakReference:Boolean = false):void
使用 EventDispatcher 对象注册事件侦听器对象,以使侦听器能够接收事件通知。
EventDispatcher
  
close():void
立即关闭该流并取消下载操作。
URLStream
 Inherited
将事件调度到事件流中。
EventDispatcher
 Inherited
检查 EventDispatcher 对象是否为特定事件类型注册了任何侦听器。
EventDispatcher
 Inherited
hasOwnProperty(name:String):Boolean
指示对象是否已经定义了指定的属性。
Object
 Inherited
isPrototypeOf(theClass:Object):Boolean
指示 Object 类的实例是否在指定为参数的对象的原型链中。
Object
  
load(request:URLRequest):void
开始下载 request 参数中指定的 URL。
URLStream
 Inherited
propertyIsEnumerable(name:String):Boolean
指示指定的属性是否存在、是否可枚举。
Object
  
从该流读取一个布尔值。
URLStream
  
从该流读取一个带符号字节。
URLStream
  
readBytes(bytes:ByteArray, offset:uint = 0, length:uint = 0):void
从该流读取 length 字节的数据。
URLStream
  
从该流读取一个 IEEE 754 双精度浮点数。
URLStream
  
从该流读取一个 IEEE 754 单精度浮点数。
URLStream
  
从该流读取一个带符号的 32 位整数。
URLStream
  
readMultiByte(length:uint, charSet:String):String
使用指定的字符集从字节流中读取指定长度的多字节字符串。
URLStream
  
从以 Action Message Format (AMF) 编码的套接字读取一个对象。
URLStream
  
从该流读取一个带符号的 16 位整数。
URLStream
  
从该流读取一个无符号字节。
URLStream
  
从该流读取一个无符号的 32 位整数。
URLStream
  
从该流读取一个无符号的 16 位整数。
URLStream
  
从该流读取一个 UTF-8 字符串。
URLStream
  
从该流读取长度为 length 的 UTF-8 字节序列,并返回一个字符串。
URLStream
 Inherited
removeEventListener(type:String, listener:Function, useCapture:Boolean = false):void
从 EventDispatcher 对象中删除侦听器。
EventDispatcher
 Inherited
setPropertyIsEnumerable(name:String, isEnum:Boolean = true):void
设置循环操作动态属性的可用性。
Object
 Inherited
toString():String
返回指定对象的字符串表示形式。
Object
 Inherited
valueOf():Object
返回指定对象的原始值。
Object
 Inherited
检查是否用此 EventDispatcher 对象或其任何始祖为指定事件类型注册了事件侦听器。
EventDispatcher
事件
 事件 摘要 定义方
 Inherited[广播事件] Flash Player 或 AIR 应用程序获得操作系统焦点并变为活动状态时将调度此事件。EventDispatcher
  成功加载数据后调度。URLStream
 Inherited[广播事件] Flash Player 或 AIR 应用程序失去操作系统焦点并变为非活动状态时将调度此事件。EventDispatcher
  在 URLStream.load() 方法调用尝试通过 HTTP 访问数据,并且 Adobe AIR 可以检测并返回请求的状态代码时调度。URLStream
  在 URLStream.load() 调用尝试通过 HTTP 访问数据,并且 Flash Player 或 Adobe AIR 可以检测并返回请求的状态代码时调度。URLStream
  在出现输入/输出错误并由此导致加载操作失败时调度。URLStream
  在加载操作开始时调度。URLStream
  在下载操作过程中收到数据时调度。URLStream
  若对 URLStream.load() 的调用尝试从安全沙箱外部的服务器加载数据,则进行调度。URLStream
属性详细信息
bytesAvailable属性
bytesAvailable:uint  [只读 (read-only)]
运行时版本:  1.0

返回可在输入缓冲区中读取的数据的字节数。您的代码必须调用 bytesAvailable 属性,以确保尝试使用其中一种 read 方法读取前有足够可用的数据。

connected属性 
connected:Boolean  [只读 (read-only)]
运行时版本:  1.0

指示此 URLStream 对象目前是否已连接。如果已连接 URLStream 对象,则调用该属性会返回值 true,否则会返回值 false

endian属性 
endian:String
运行时版本:  1.0

指示数据的字节顺序。可能的值为 Endian.BIG_ENDIANEndian.LITTLE_ENDIAN

默认值为 Endian.BIG_ENDIAN.

另请参见

objectEncoding属性 
objectEncoding:uint
运行时版本:  1.0

在写入或读取对象时,控制所使用的 Action Message Format (AMF) 的版本。

另请参见

方法详细信息
close()方法
function close():void
运行时版本:  1.0

立即关闭该流并取消下载操作。无法在调用 close() 方法后从该流中读取数据。


引发
IOError — 无法关闭该流,或者该流未打开。
load()方法 
function load(request:URLRequest):void
运行时版本:  1.0

开始下载 request 参数中指定的 URL。

注意:如果要加载的文件包含非 ASCII 字符(在许多非英语的语言中出现),则建议使用 UTF-8 或 UTF-16 编码(而不是 ASCII 等非 Unicode 格式)来保存文件。

如果加载操作很快失败,将引发描述失败情况的 IOError 或 SecurityError(包括本地文件安全错误)异常。否则,如果 URL 下载开始成功下载,将调度 open 事件;如果发生错误,将调度错误事件。

默认情况下,执行调用的 SWF 文件和加载的 URL 必须在同一域中。例如,位于 www.adobe.com 的 SWF 文件只能从同样位于 www.adobe.com 的源中加载数据。若要从不同的域中加载数据,请在承载数据的服务器上放置一个 URL 策略文件。

在 AIR 中,URLRequest 对象可以注册 httpResponse 状态事件。与 httpStatus 事件不同,httpResponseStatus 事件在传送任何响应数据之前传送。此外,httpResponseStatus 事件还包括 responseHeadersresponseURL 属性的值(对于 httpStatus,这些属性未定义)。请注意,在发送任何 completeerror 事件之前还将发送 httpResponseStatus(如果有)。

如果 httpResponseStatus 事件侦听器,则始终 将发送响应消息的正文;而 HTTP 状态代码响应始终将产生 complete 事件。无论 HTTP 响应状态代码指示成功还是错误,这种情况都适用。

如果没有 httpResponseStatus 事件侦听器,则行为因 AIR 版本而异:

参数

request:URLRequest — 一个 URLRequest 对象,指定要下载的 URL。如果此参数的值或所传递的 URLRequest 对象的 URLRequest.url 属性为 null,则应用程序会引发空指针错误。


事件
complete:Event — 在成功加载数据后调度。如果有 httpResponseStatus 事件侦听器,则 URLRequest 对象还会调度一个 complete 事件,无论 HTTP 响应状态代码指示成功还是 错误。
 
httpStatus:HTTPStatusEvent — 如果通过 HTTP 进行访问,并且当前环境支持获取状态代码,则除了 completeerror 事件之外,还可以接收这些事件。
 
httpResponseStatus:HTTPStatusEvent — 在 load() 方法调用尝试通过 HTTP 访问数据,并且 Adobe AIR 可以检测并返回请求的状态代码时调度。
 
ioError:IOErrorEvent — 无法完成加载操作。
 
open:Event — 在加载操作开始时调度。
 
securityError:SecurityErrorEvent — 加载操作尝试从调用方安全沙箱外部的服务器检索数据。可以通过在服务器上使用策略文件来解决此问题。

引发
ArgumentError URLRequest.requestHeader 对象不能包含某些被禁用的 HTTP 请求标头。有关详细信息,请参阅 URLRequestHeader 类的描述。
 
MemoryError — 此错误可能由以下原因引起:
  1. Flash Player 或 Adobe AIR 无法将 URLRequest.data 参数从 UTF8 转换为 MBCS。若传递给 load() 的 URLRequest 对象设置为执行 GET 操作并且 System.useCodePage 设置为 true,就会发生该错误。
  2. Flash Player 或 Adobe AIR 无法为 POST 数据分配内存。如果传递给 load 的 URLRequest 对象设置为执行 POST 操作,将发生该错误。
 
SecurityError — 本地不受信任的 SWF 文件可能无法与 Internet 进行通信。可通过将此 SWF 文件重新分类为只能与远程内容交互或受信任来解决此问题。
 
SecurityError — 如果尝试连接到常用的保留端口。有关已阻止的端口的完整列表,请参阅《ActionScript 3.0 编程》一书的“安全性”一章中的“限制网络 API”。
readBoolean()方法 
function readBoolean():Boolean
运行时版本:  1.0

从该流读取一个布尔值。读取单个字节,如果字节非零,则返回 true,否则返回 false

返回
Boolean — 如果字节不为零,则返回 True;否则返回 false

引发
EOFError 此错误适用于 SWF 内容,AIR 中运行的 JavaScript 代码中不会发生此错误。
 
IOError — 该流发生了 I/O 错误,或者该流未打开。
readByte()方法 
function readByte():int
运行时版本:  1.0

从该流读取一个带符号字节。

返回值在 -128...127 之间。

返回
int — 值的范围为 -128...127。

引发
EOFError 此错误适用于 SWF 内容,AIR 中运行的 JavaScript 代码中不会发生此错误。
 
IOError — 该流发生了 I/O 错误,或者该流未打开。
readBytes()方法 
function readBytes(bytes:ByteArray, offset:uint = 0, length:uint = 0):void
运行时版本:  1.0

从该流读取 length 字节的数据。这些字节会被读取到由 bytes 指定的 ByteArray 对象中,其起始位置是在 ByteArray 对象中偏移 offset 字节处。

参数

bytes:ByteArray — 要将数据读入的 ByteArray 对象。
 
offset:uint (default = 0) — 在 bytes 中的偏移量,即数据读取的起始位置。默认值为 0。
 
length:uint (default = 0) — 要读取的字节数。默认值 0 将导致读取所有可用的数据。


引发
EOFError 此错误适用于 SWF 内容,AIR 中运行的 JavaScript 代码中不会发生此错误。
 
IOError — 该流发生了 I/O 错误,或者该流未打开。
readDouble()方法 
function readDouble():Number
运行时版本:  1.0

从该流读取一个 IEEE 754 双精度浮点数。

返回
Number — 流中的一个 IEEE 754 双精度浮点数。

引发
EOFError 此错误适用于 SWF 内容,AIR 中运行的 JavaScript 代码中不会发生此错误。
 
IOError — 该流发生了 I/O 错误,或者该流未打开。
readFloat()方法 
function readFloat():Number
运行时版本:  1.0

从该流读取一个 IEEE 754 单精度浮点数。

返回
Number — 流中的一个 IEEE 754 单精度浮点数。

引发
EOFError 此错误适用于 SWF 内容,AIR 中运行的 JavaScript 代码中不会发生此错误。
 
IOError — 该流发生了 I/O 错误,或者该流未打开。
readInt()方法 
function readInt():int
运行时版本:  1.0

从该流读取一个带符号的 32 位整数。

返回值在 -2147483648...2147483647 之间。

返回
int — 值的范围为 -2147483648...2147483647。

引发
EOFError 此错误适用于 SWF 内容,AIR 中运行的 JavaScript 代码中不会发生此错误。
 
IOError — 该流发生了 I/O 错误,或者该流未打开。
readMultiByte()方法 
function readMultiByte(length:uint, charSet:String):String
运行时版本:  1.0

使用指定的字符集从字节流中读取指定长度的多字节字符串。

参数

length:uint — 要从字节流中读取的字节数。
 
charSet:String — 表示用于解释字节的字符集的字符串。可能的字符集字符串包括 "shift_jis""CN-GB""iso-8859-1"”等。有关完整列表,请参阅Supported Character

注意:如果当前系统无法识别 charSet 参数的值,则应用程序将使用系统的默认代码页作为字符集。例如,charSet 参数的值(如在使用 01 而不是 1myTest.readMultiByte(22, "iso-8859-01") 中)可能在您的开发计算机上起作用,但在其它计算机上可能不起作用。在其他计算机上,应用程序将使用系统的默认代码页。

返回
String — UTF-8 编码的字符串。

引发
EOFError 此错误适用于 SWF 内容,AIR 中运行的 JavaScript 代码中不会发生此错误。
readObject()方法 
function readObject():*
运行时版本:  1.0

从以 Action Message Format (AMF) 编码的套接字读取一个对象。

返回
* — 反序列化的对象。

引发
EOFError — 可读取的数据不足。若本地 SWF 文件触发了安全警告,则 Flash Player 会阻止将 URLStream 数据用于 ActionScript。当发生这种情况时,即使收到了数据,bytesAvailable 属性也将返回 0,而且任何读方法都将引发 EOFError 异常。
 
IOError — 该流发生了 I/O 错误,或者该流未打开。

另请参见

readShort()方法 
function readShort():int
运行时版本:  1.0

从该流读取一个带符号的 16 位整数。

返回值在 -32768...32767 之间。

返回
int — 值的范围为 -32768...32767。

引发
EOFError 此错误适用于 SWF 内容,AIR 中运行的 JavaScript 代码中不会发生此错误。
 
IOError — 该流发生了 I/O 错误,或者该流未打开。
readUnsignedByte()方法 
function readUnsignedByte():uint
运行时版本:  1.0

从该流读取一个无符号字节。

返回值在 0...255 之间。

返回
uint — 值的范围为 0...255。

引发
EOFError 此错误适用于 SWF 内容,AIR 中运行的 JavaScript 代码中不会发生此错误。
 
IOError — 该流发生了 I/O 错误,或者该流未打开。
readUnsignedInt()方法 
function readUnsignedInt():uint
运行时版本:  1.0

从该流读取一个无符号的 32 位整数。

返回值在 0...4294967295 之间。

返回
uint — 值的范围为 0...4294967295。

引发
EOFError 此错误适用于 SWF 内容,AIR 中运行的 JavaScript 代码中不会发生此错误。
 
IOError — 该流发生了 I/O 错误,或者该流未打开。
readUnsignedShort()方法 
function readUnsignedShort():uint
运行时版本:  1.0

从该流读取一个无符号的 16 位整数。

返回值在 0...65535 之间。

返回
uint — 值的范围为 0...65535。

引发
EOFError 此错误适用于 SWF 内容,AIR 中运行的 JavaScript 代码中不会发生此错误。
 
IOError — 该流发生了 I/O 错误,或者该流未打开。
readUTF()方法 
function readUTF():String
运行时版本:  1.0

从该流读取一个 UTF-8 字符串。假定字符串的前缀是无符号的短整型(以字节表示长度)。

返回
String — UTF-8 字符串。

引发
EOFError 此错误适用于 SWF 内容,AIR 中运行的 JavaScript 代码中不会发生此错误。
 
IOError — 该流发生了 I/O 错误,或者该流未打开。
readUTFBytes()方法 
function readUTFBytes(length:uint):String
运行时版本:  1.0

从该流读取长度为 length 的 UTF-8 字节序列,并返回一个字符串。

参数

length:uint — 一个 UTF-8 字节序列。

返回
String — 由指定长度字符的字节表示形式生成的 UTF-8 字符串。

引发
EOFError 此错误适用于 SWF 内容,AIR 中运行的 JavaScript 代码中不会发生此错误。
 
IOError — 该流发生了 I/O 错误,或者该流未打开。
事件详细信息
complete 事件
事件对象类型: flash.events.Event
属性 Event.type = flash.events.Event.COMPLETE
运行时版本:  1.0

成功加载数据后调度。

Event.COMPLETE 常量定义 complete 事件对象的 type 属性值。

此事件具有以下属性:

属性
bubblesfalse
cancelablefalse;没有要取消的默认行为。
currentTarget当前正在使用某个事件侦听器处理 Event 对象的对象。
target已完成加载的网络对象。
httpResponseStatus 事件  
事件对象类型: flash.events.HTTPStatusEvent
属性 HTTPStatusEvent.type = flash.events.HTTPStatusEvent.HTTP_RESPONSE_STATUS
运行时版本:  1.0 1.0

URLStream.load() 方法调用尝试通过 HTTP 访问数据,并且 Adobe AIR 可以检测并返回请求的状态代码时调度。

如果为 httpStatusEvent 事件注册了 URLStream 对象,则在传输错误响应时会将其视为内容。因此,在将错误数据加载到 URLStream 中时,URLStream 将调度 progresscomplete 事件,而不调度 ioError 事件。

httpStatus 事件不同,httpResponseStatus 事件在传送任何响应数据之前传送。此外,httpResponseStatus 事件还包括 responseHeadersresponseURL 属性的值(对于 httpStatus,这些属性未定义)。请注意,在发送任何 completeerror 事件之前还将发送 httpResponseStatus(如果有)。

HTTPStatusEvent.HTTP_RESPONSE_STATUS 常量定义 httpResponseStatus 事件对象的 type 属性值。

此事件具有以下属性:

属性
bubblesfalse
cancelablefalse;没有要取消的默认行为。
currentTarget当前正在使用某个事件侦听器处理 Event 对象的对象。
responseURL从中返回响应的 URL。
responseHeaders响应以 URLRequestHeader 对象的数组形式返回的响应标头。
status由服务器返回的 HTTP 状态代码。
target接收 HTTP 状态代码的网络对象。

另请参见

httpStatus 事件  
事件对象类型: flash.events.HTTPStatusEvent
属性 HTTPStatusEvent.type = flash.events.HTTPStatusEvent.HTTP_STATUS
运行时版本:  1.0

URLStream.load() 调用尝试通过 HTTP 访问数据,并且 Adobe AIR 可以检测并返回请求的状态代码时调度。(有些浏览器环境可能无法提供此信息。) 请注意,在发送任何 completeerror 事件之前还将发送 httpStatus(如果有)。

HTTPStatusEvent.HTTP_STATUS 常量定义 httpStatus 事件对象的 type 属性值。

此事件具有以下属性:

属性
bubblesfalse
cancelablefalse;没有要取消的默认行为。
currentTarget当前正在使用某个事件侦听器处理 Event 对象的对象。
status由服务器返回的 HTTP 状态代码。
target接收 HTTP 状态代码的网络对象。

另请参见

ioError 事件  
事件对象类型: flash.events.IOErrorEvent
属性 IOErrorEvent.type = flash.events.IOErrorEvent.IO_ERROR
运行时版本:  1.0

在出现输入/输出错误并由此导致加载操作失败时调度。

定义 ioError 事件对象的 type 属性值。

此事件具有以下属性:

属性
bubblesfalse
cancelablefalse;没有要取消的默认行为。
currentTarget当前正在使用某个事件侦听器处理 Event 对象的对象。
errorID与特定错误关联的引用编号(仅限 AIR)。
target发生输入/输出错误的网络对象。
text要显示为错误消息的文本。

另请参见

open 事件  
事件对象类型: flash.events.Event
属性 Event.type = flash.events.Event.OPEN
运行时版本:  1.0

在加载操作开始时调度。

Event.OPEN 常量用于定义 open 事件对象的 type 属性值。

此事件具有以下属性:

属性
bubblesfalse
cancelablefalse;没有要取消的默认行为。
currentTarget当前正在使用某个事件侦听器处理 Event 对象的对象。
target已打开连接的网络对象。

另请参见

progress 事件  
事件对象类型: flash.events.ProgressEvent
属性 ProgressEvent.type = flash.events.ProgressEvent.PROGRESS
运行时版本:  1.0

在下载操作过程中收到数据时调度。可以使用 URLStream 类方法立即读取已接收的数据。

定义 progress 事件对象的 type 属性值。

此事件具有以下属性:

属性
bubblesfalse
bytesLoaded在侦听器处理事件时加载的项数或字节数。
bytesTotal如果加载进程成功,最终将加载的项目或字节总数。
cancelablefalse;没有要取消的默认行为。
currentTarget当前正在使用某个事件侦听器处理 Event 对象的对象。
target报告进度的对象。

另请参见

securityError 事件  
事件对象类型: flash.events.SecurityErrorEvent
属性 SecurityErrorEvent.type = flash.events.SecurityErrorEvent.SECURITY_ERROR
运行时版本:  1.0

若对 URLStream.load() 的调用尝试从安全沙箱外部的服务器加载数据,则进行调度。

SecurityErrorEvent.SECURITY_ERROR 常量定义 securityError 事件对象的 type 属性值。

此事件具有以下属性:

属性
bubblesfalse
cancelablefalse;没有要取消的默认行为。
currentTarget当前正在使用某个事件侦听器处理 Event 对象的对象。
target报告安全错误的网络对象。
text要显示为错误消息的文本。

另请参见

示例
URLStreamExample.as

下例加载一个 SWF 文件,并解析其标头的开始部分以指明压缩和版本号信息。

注意:要测试此示例,请执行以下操作:

  1. 将 AIRAliases.js 文件添加到项目目录。
  2. 将一个名为 URLStreamExample.zip 的文件放在项目目录中
  3. 为该项目创建应用程序描述符文件,并使用 ADL 测试该项目。

<html>
    <head>
      <script src="AIRAliases.js" />
      <script>
        function init() {
            stream = new air.URLStream();
            var request = new air.URLRequest("URLStreamExample.zip");
            configureListeners(stream);
            try {
                stream.load(request);
            } catch (error) {
                air.trace("Unable to load requested URL.");
            }
        }

        function configureListeners(dispatcher) {
            dispatcher.addEventListener(air.Event.COMPLETE, completeHandler);
            dispatcher.addEventListener(air.HTTPStatusEvent.HTTP_STATUS, httpStatusHandler);
            dispatcher.addEventListener(air.IOErrorEvent.IO_ERROR, ioErrorHandler);
            dispatcher.addEventListener(air.Event.OPEN, openHandler);
            dispatcher.addEventListener(air.ProgressEvent.PROGRESS, progressHandler);
            dispatcher.addEventListener(air.SecurityErrorEvent.SECURITY_ERROR, securityErrorHandler);
        }

        function parseHeader() {
            air.trace("parseHeader");
            air.trace("isCompressed: " + isCompressed());
            air.trace("version: " + stream.readByte());
        }

        function isCompressed() {
            return stream.readUTFBytes(3) == air.CompressionAlgorithm.ZLIB ;
        }

        function completeHandler(event) {
            air.trace("completeHandler: " + event);
            parseHeader();
        }

        function openHandler(event) {
            air.trace("openHandler: " + event);
        }

        function progressHandler(event) {
            air.trace("progressHandler: " + event);
        }

        function securityErrorHandler(event) {
            air.trace("securityErrorHandler: " + event);
        }

        function httpStatusHandler(event) {
            air.trace("httpStatusHandler: " + event);
        }

        function ioErrorHandler(event) {
            air.trace("ioErrorHandler: " + event);
        }
      </script>
    </head>
    <body onload='init()'>
    </body>
</html>