|
|
Node Websocket/ws模块 API 参考
Class: Websocket.server 服务端
一、new WebSocket.Server(options[, callback]) 参数说明如下：
options {Object}
callback {Function}
1. verifyClient {Function} (默认自动接受)，如果设置该函数则，则该函数会接受如下两个参数：
info {Object}
origin {String} ```HTTP.request.header['Origin']```
req {http.IncomingMessage} GET```HTTP.request```
secure {Boolean} 如果设置了Req.Calnal.授权或Req.Calnal.加密，则为true。
cb {Function} 当用户需要定制拒绝回调信息时使用，该回调可传如下参数：
result {Boolean} 是否接受握手
code {Number} 当```result```为```false```时，该值为指定返回的http错误状态码
name {String} 当```result```为```false```时，该值为指定返回的http错误信息
headers {Object} 当```result```为```false```时，该值可以设定附加的额外头部信息
示例如下：
// 1)、拒绝
verifyClient:function(info){
return false;
// 2)、同意
verifyClient:function(info){
return true;
// 3)、拒绝
verifyClient:function(info,cb){
cb(false,403,'Site access denied',{'Retry-After': 120});
2. handleProtocols {Function} 处理子协议的函数。函数注入参数如下:
protocols {Array} ```HTTP.request.header['Sec-WebSocket-Protocol']```
request {http.IncomingMessage} GET```HTTP.request```
如果函数返回true则会在响应中设置header['Sec-WebSocket-Protocol']
忽略该项则使用HTTP.request.header['Sec-WebSocket-Protocol']第一个值
3. perMessageDeflate {Boolean|Object} 压缩扩展（默认：false）
serverNoContextTakeover {Boolean} Whether to use context takeover or not.
clientNoContextTakeover {Boolean} Acknowledge disabling of client context takeover.
serverMaxWindowBits {Number} The value of windowBits.
clientMaxWindowBits {Number} Request a custom client window size.
zlibDeflateOptions {Object} [deflate options](http://nodejs.cn/api/zlib.html#zlib_class_options)
zlibInflateOptions {Object} [inflate options](http://nodejs.cn/api/zlib.html#zlib_class_options)
threshold {Number} 小于该值的有效载荷将不会被压缩。默认为1024字节。
concurrencyLimit {Number} 并发数限制，默认：10。详情请参阅此问题。
如果属性为空，则使用提供的配置或默认值。当发送分段消息时，将第一片段的长度与阈值进行比较。这就决定了是否对整个消息使用压缩。
注：其实关于压缩使用了node zlib模块 参考地址
4. callback {Function}
非“noServer”模式下运行时，回调将被添加到HTTP服务器上侦听事件的侦听器中。
内置事件：
1. Event: 'close' 服务器关闭时触发 无参数
当服务器关闭时发送。此事件仅取决于HTTP服务器在内部创建时的“关闭”事件。在所有其他情况下，事件是独立发射的。
2. Event: 'connection' 成功握手连接时触发。注入参数如下:
socket {WebSocket} socket连接句柄
request {http.IncomingMessage} GET```HTTP.request```
3. Event: 'error' 发生错误时触发 注入一个Error对象
error {Error}
4. Event: 'headers' 握手前触发 注入参数如下：
在响应头被写入到套接字作为握手的一部分之前发出。这允许您在发送头之前检查/修改标题。
headers {Array} ```HTTP.respone.header```
request {http.IncomingMessage} GET```HTTP.request```
5. Event: 'listening' 绑定端口时触发 无参数
属性说明：
1. server.clients {Set}
存储所有连接客户端的集合。请注意，只有在客户端跟踪是truthy时才添加此属性。
内置方法：
1. server.address() 返回net.server.address()
仅当监听了端口后有值 数据参考地址
2. server.close([callback]) 关闭http服务器并终止所有客户端
如果noServer为真，则需要手动关闭客户端
3. server.handleUpgrade(request, socket, head, callback) 处理websocket升级请求 noServer模式下必须手动调用该函数
request {http.IncomingMessage} GET```HTTP.request```
socket {net.Socket} ```net.Socket```
head {Buffer} 升级后的第一个数据包
callback {Function} 如果升级成功，调用回调将以WebSoCult对象作为参数调用。
4. server.shouldHandle(request) 处理websocket升级请求 noServer模式下必须手动调用该函数
request {http.IncomingMessage} GET```HTTP.request```
默认情况下，此方法验证请求的路径名与path属性是否匹配。返回值，TRUE或FALSE，决定是否接受握手。
当需要自定义处理逻辑时，可以重写此方法。
Class: WebSocket websocket实例 （可用于客户端连接实例、服务端接收到连接的实例）
二、new WebSocket(address[, protocols][, options]) 参数说明如下：
address {String|url.Url|url.URL} 请求地址（例：ws://127.0.0.1:8080/）
protocols {String|Array} 子协议列表http.request.header['Sec-WebSocket-Protocol']
options {Object}
handshakeTimeout {Number} 超时时间（ms）
perMessageDeflate {Boolean|Object} 是否开启压缩（默认：true）
protocolVersion {Number} http.request.header['Sec-WebSocket-Version']
origin {String} http.request.header['Origin'] 或者 http.request.header['Sec-WebSocket-Origin']
maxPayload {Number} 最大消息载荷（bytes）
其它任何 http/s.request属性
7. Event: 'unexpected-response'
request {http.ClientRequest}
response {http.IncomingMessage}
当服务器响应不是预期响应时发出，例如401响应。此事件提供了读取响应以提取有用信息的能力。如果服务器发送无效响应，并且没有该事件的侦听器，则会发出错误。
8. Event: 'upgrade'
response {http.IncomingMessage}
Emitted when response headers are received from the server as part of the handshake. This allows you to read headers from the server, for example 'set-cookie' headers.
9. 内置方法（属性）：
10. websocket.addEventListener(type, listener) 自定义事件侦听器
type {String} 自定义事件名称
listener {Function} 侦听器
11. websocket.removeEventListener(type, listener) 移除事件侦听器
type {String} 自定义事件名称
listener {Function} 侦听器
12. websocket.send(data[, options][, callback]) 发送数据
data {Any} 需要发送的数据
options {Object}
compress {Boolean} 是否压缩（启用perMessageDeflate时默认为true）
binary {Boolean} 是否作为二进制数据发送，默认为true
mask {Boolean} 是否掩码（客户端默认为true，服务端不允许掩码）
fin {Boolean} 指定是否为最后的消息片段，默认：true (用于分片发送)
callback {Function} 在写入数据时调用的可选回调。
通常options不需要设置，除非你基本熟悉websocket协议
13. websocket.ping([data[, mask]][, callback])
data {Any} 同上
mask {Boolean} 同上
callback {Function} 同上
14. websocket.pong([data[, mask]][, callback])
data {Any} 同上
mask {Boolean} 同上
callback {Function} 同上
15. websocket.close([code[, reason]]) 发送连接关闭信号
code {Number} 关闭连接状态码
reason {String} 关闭原因说明
16. websocket.terminate() 强制关闭连接 无参数
terminate()为强制关闭连接
close()为发送关闭信号，通常服务器会处理完当前发送数据然后再缓步关闭
17. websocket.readyState {Number} 实例对象的当前状态
0 => CONNECTING正在连接。
1 => OPEN连接成功，可以通信了。
2 => CLOSING连接正在关闭。
3 => CLOSED连接已经关闭，或者打开连接失败。
18. websocket.binaryType {String} 显式指定收到的二进制数据类型 默认：'nodebuffer'
右侧三选一 ["nodebuffer","arraybuffer","fragments"]
19. websocket.bufferedAmount {Number} 表示还有多少字节的二进制数据没有发送出去。它可以用来判断发送是否结束
20. websocket.protocol {String} 返回服务端选择的子协议
21. websocket.url {String} 仅在服务端socket存在该值
22. websocket.extensions {Object} 包含协商扩展的对象
以下是一些重复的事件省略（包含如下：）
onopen、onmessage、onclose、onerror（与内置的```Event```内置事件是等效的）