WebSocket

From HTML5 Chinese Interest Group Wiki
Jump to: navigation, search

(暂放)

原文链接 http://www.w3.org/TR/websockets/

本文档开放给所有人编辑,希望参与贡献请移步下面地址注册: http://www.w3.org/Help/Account/Request/Public

摘要

本节不具规范性

本规程定义了一个API接口,允许Web页面利用WebSocket协议与远程主机进行双向通信。


注:本接口不允许到底层网络的原始访问。举例说明,本接口不能被用于实现一个不通过自定义服务器代理发送消息的IRC(网间实时聊天,Internet Relay Chat)客户端。

规范要求

本規範的所有圖表、範例、備註皆沒有規範性,直接標示無規範性的章節也是如此。本規範其餘的部份具有規範性。

在具有規範性的部份裡,關鍵詞「必須(MUST)」、「必不可(MUST NOT)」、「本規範要求…(REQUIRED)」、「應該(SHOULD)」、「不應(SHOULD NOT)」、「本規範建議…(RECOMMENDED)」、「可(MAY)」、「可以選擇(OPTIONAL)」 按照 RFC2119 的敘述解讀。[RFC2119]

作為演算法一部分指令的要求(例如:「剝離所有前頭空白字符」、「回傳假值並退出這些步驟」)以呼叫演算法所用關鍵字(「必須」、「應該」、「可」等等)的意義解讀。

某些规范要求作用与属性、方法或对象。这些要求被解释为对用户代理的要求。

以演算法或是具體步驟呈現的要求可以任何方式實作,唯一的要求是是結果相等。(特別是本規範定義的演算法以容易理解而不以性能高為目的。)

本规范定义的唯一的类是用户代理。

用户代理可以在无约束的输入上施加特殊实现的限制,例如,防止拒绝服务攻击、防止运行时内存不足或解决特定平台的限制。

当对一个特性的支持被禁用时(例如,未解决安全问题的紧急措施、便于开发或者提高性能),用户代理必须被认为不支持该特性且该特性没有在本规范中提及。举例说明,如果一个特定的功能被Web IDL接口中的一个属性使用,该属性本节将被从实现了该接口的对象中省略——将该属性从对象中剥离,而不是返回空或抛出一个异常。

依赖性

本规范依赖几个其他的底层规范。

  • HTML
    • 本规范使用的许多HTML中的基本概念。[HTML]
  • WebIDL
    • 本规范中的IDL块使用了WebIDL规范的语义。[WEBIDL]

术语

构造“一个Foo对象”(其中Foo实际上是一个接口),有时被用于替代更精确的“一个实现了接口Foo的对象”。

术语DOM用于指出Web应用中可用的API集合,这并不意味着DOM Core规范中实际的Document对象或任意其他Node对象存在。

对于一个IDL属性,在取回该属性值时(例如通过编码人员脚本)被称为getting,在将新值分配给该属性时被称为setting

WebSocket接口

[Constructor(DOMString url, optional DOMString protocols),
 Constructor(DOMString url, optional DOMString[] protocols)]
interface WebSocket : EventTarget {
  readonly attribute DOMString url;

  // 准备状态
  const unsigned short CONNECTING = 0;
  const unsigned short OPEN = 1;
  const unsigned short CLOSING = 2;
  const unsigned short CLOSED = 3;
  readonly attribute unsigned short readyState;
  readonly attribute unsigned long bufferedAmount;

  // 网络
  [TreatNonCallableAsNull] attribute Function? onopen;
  [TreatNonCallableAsNull] attribute Function? onerror;
  [TreatNonCallableAsNull] attribute Function? onclose;

  readonly attribute DOMString extensions;
  readonly attribute DOMString protocol;
  void close([Clamp] optional unsigned short code, optional DOMString reason);

  // 消息
  [TreatNonCallableAsNull] attribute Function? onmessage;
           attribute DOMString binaryType;
  void send(DOMString data);
  void send(ArrayBuffer data);
  void send(Blob data);
};

WebSocket(URL, 协议)构造器接受一个或两个参数。第一个参数,URL,指定了要连接到的URL。第二个参数,协议,如果出现,为一个字符串或一个字符串数组。如果其为字符串,则其与仅包含该字符串的数组等价;如果其被忽略,则其等价于空数组。数组中的每个字符串均为一个子协议名称。只有服务器报告其已经选择了一个子协议,连接才会被建立。子协议名称必须全部为匹配元素要求的字符串,这些元素由WebSocket协议规范定义的Sec-WebSocket-Protocal头字段的值组成。[WSP]

当调用WebSocket()构造器时,用户代理必须执行这些步骤:

  1. URL参数解析一个WebSocket URL的部件,以获得主机端口资源名安全连接。如果解析失败,则抛出一个SyntaxError异常并终止这些步骤。[WSP]
  2. 如果安全连接为假,但入口脚本的源拥有一个其自身为安全协议的协议部分,例如HTTPS,则抛出一个SecurityError异常。
  3. 如果端口是一个用户代理中被配置为阻塞连接的端口,则抛出一个SecurityError异常。(用户代理通常会阻塞知名端口,诸如SMTP)。
    到80和443端口的连接不应被阻塞,包括很少出现的在安全连接为假时的443端口和安全连接为真时的80端口。
  4. 如果协议被忽略,设协议为空数组。
    否则,如果协议存在且为一个字符串,则设协议为仅包含该字符串的数组。
  5. 如果协议中的值出现超过一次,或者其不能匹配由WebSocket协议规范定义的Sec-WebSocket-Protocal头字段的值组成元素要求,则抛出一个SyntaxError异常并跳过这些步骤。[WSP]
  6. 为入口脚本的源的ASCII序列化形式,并转换为ASCII小写形式。
  7. 返回一个新的WebSocket对象,并在后台继续这些步骤(不阻塞脚本)。
  8. 建立一个WebSocket连接给出集合(主机端口资源名安全连接),并伴随一个协议列表、一个待扩展的空列表、和发送恰当的cookie的头必须为一个Cookie头,其值为有用户的cookie存储和URL URL计算而得的cookie字符串;因此,其是一个“非HTTP”API。[WSP][COOKIES]
    当用户代理在“建立一个WebSocket连接”算法期间验证服务器的响应时,如果从服务器收到的状态码不是101(例如其为一个重定向),则用户代理必须WebSocket连接失败

如果脚本的全局对象是一个Window对象或一个实现了WorkerUtils接口的对象,则构造器必须是可见的。

url属性必须返回解释传入构造器的URL的结果。(我们不关心其的相对问题,因为我们已经知道其为一个绝对URL。)

readyState属性表示连接的状态。其可以是下列值:

  • CONNECTING(数值0)
    • 连接尚未被建立。
  • OPEN(数值1)
    • WebSocket连接被建立且可以进行通信。
  • CLOSING(数值2)
    • 连接正在进行关闭握手。
  • CLOSED(数值3)
    • 连接已经被关闭或者无法开启。

当该对象被创建时,其readyState必须被设为CONNECTING(0)。

extensions属性必须首先返回空字符串。在WebSocket连接被建立之后,其值可能会改变,将在下面定义。

注:extensions属性返回服务器选择的扩展(如果存在)。(一般情况下将永远保持空字符串。)

protocol属性必须首先返回空字符串。在WebSocket连接被建立之后,其值可能会改变,将在下面定义。

注:extensions属性返回服务器选择的子协议(如果存在)。其可以会同数组形式的构造器第二参数来进行子协议交换。

close()方法必须执行这些步骤:

  1. 如果设置了该方法的第一个参数,但其不是一个等于1000或在3000至4999范围内的整数,则抛出一个InvalidAccessError异常并终止这些步骤。
  2. 如果该方法的第二个参数存在任何不成对的代理,则抛出一个SyntaxError异常并终止这些步骤。
  3. 如果设置了该方法的第二个参数,则设理由为使用UTF-8对该参数进行编码的结果。如果理由大于123字节,则抛出一个SyntaxError异常并终止这些步骤。[RFC3629]
  4. 执行下列列表中第一个匹配的步骤:
    • 如果readyState属性处于CLOSING(2)或CLOSED(3)状态
      • 不进行任何操作。
      • 注:该连接已经开始关闭或者已经关闭。如果还没有,则最终将按照下面的描述触发一个close事件。
    • 如果WebSocket连接尚未建立
      • 使WebSocket连接失败并将readyState属性的值设为CLOSING(2)。[WSP]
      • 注:使WebSocket连接失败算法调用关闭WebSocket连接算法,其之后将使WebSocket连接关闭按照下面的描述触发一个close事件。
    • 如果WebSocket关闭握手尚未开始
      • 开始WebSocket关闭握手readyState属性的值设为CLOSING(2)。[WSP]
      • 如果设置了第一个参数,则WebSocket关闭消息所使用的状态码必须为第一个参数所给出的整数。[WSP]
      • 如果同样设置了第二个参数,则理由必须在关闭消息中的状态码之后给出。RFC3629][WSP]
      • 注:开始WebSocket关闭握手算法最终将调用关闭WebSocket连接算法,其之后将使WebSocket连接关闭按照下面的描述触发一个close事件。
    • 否则
      • readyState属性的值设为CLOSING(2)。
      • 注:WebSocket关闭握手开始,并且最终将调用关闭WebSocket连接算法,其将使WebSocket连接关闭按照下面的描述触发一个close事件。

协议反馈

Ping和Pong帧

WebSocket协议文档将Ping及Pong帧定义为

WebSocket URL的解析過程

下面這個步驟是从地址字符来解析一个WebSocket统一资源定位符。以下过程要么将返回一个主机、端口或者资源名称,要么无法获取导致解析失败

  1. 当'url'字符串擁有非決定性時,算法将无法继续执行;
  2. 對通過已加密爲UTF-8的url字符串進行解析. [RFC3629];
注意! 在已經得知該url擁有絕對性的情況下, 我們無需再去分析其對應性 (句段需要修正);

事件定义

垃圾收集

參考文獻

所有除標記有“不具規範性”外全為規範性參考文獻。

[COOKIES]

HTTP狀態管理機制,A. 巴斯,來自互聯網工程任務組

[DOMCORE]

DOM4文檔,A. 范凱斯特倫,來自萬維網聯盟

[FILEAPI]

文件應用程序接口,A. 蘭加納坦,來自萬維網聯盟

[HTML5]

HTML5文檔,I. 希克森,來自萬維網聯盟

[RFC2119]

RFC指示要求關鍵詞的採用,S. 布蘭德,來自互聯網工程任務組

[RFC3629]

UTF-8, 一種ISO10646的變形規範,F. 耶吉爾,來自萬維網聯盟

致谢

参看完整的致谢名单,请转到此网页:[HTML]