（暂放）

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

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

摘要

本节不具规范性

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

规范要求

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

在具有規範性的部份裡，關鍵詞「必須（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连接被建立之后，其值可能会改变，将在下面定义。

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

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]