wscio v1.5.7

wscio

长连接通讯库-客户端

3 客户端 API

3.1 wscio

wscio

作为独立生成中的 wscio 命名空间暴露，或调用 require('wscio')

<script>
    const socket= wscio('http://127.0.0.1');
</script>

const wscio= require('wscio')
//或者使用import 语法
import { wscio } from 'wscio'

3.1.1 wscio.protocpl

• Number

解析协议版本号

3.1.2 wscio([url][,optiosn])

• url (string) (默认为 window.location)
• options (object)
  • forceNew? (boolean) 是否重用现有连接
  • query? (string) 第一次请求连接时 URL 请求参数
  • nsp? (string) 命名空间
  • auth? (string | object) 命名空间连接时验证参数
  • ... 其余参数在 Client 实例时所需参数
• Return: Socket

为给定的URL创建新的管理器，并尝试在后续调用中重用现有的管理器，除非用false传递多路复用选项。传递此选项等同于传递 force new connection：true 或 forcenew:true 。

有关可用选项的列表，见 new Client(url[, options])

3.1.3 带多路复用

默认情况下，连接到不同命名空间时使用单个连接（以最小化资源）

const wscio= require('wscio')
const socket= wscio()
const test =wscio('/test')
//  将建立单一连接

使用forceNew选项可以禁用该行为：

const wscio= require('wscio')
const socket = wscio();
const test = wscio('/test',{forceNew:true})
// 将创建两个不同的连接

3.1.4 自定义路径

const wscio = require('wscio')
const socket = wscio('http://127.0.0.1',{
    path:"/mypath"
})
// 服务端
const wss = new require('wssio')({
    path:"/mypath"
})

请求的 URL 会像：127.0.0.1/mypath

3.1.5 查询参数

const wscio = require('wscio')
const socket= wscio('http://127.0.0.1?token=abc');
// 服务端
functionverifyClient(data, callback) {//这样能彻底断开连接
    const url = data.req.url;
    //处理逻辑
    callback(); //传入处理结果
}
const wss = new require('wssio')({
  verifyClient,
})
// 中间件验证并不能断开socket原始连接
wss.use((socket,next)=>{
    const token = socket.handshake.query.token;
    if (isValid(token)){
        return next();
    }
    return next(new Error('验证失败'))
})
// 然后
wss.on('connection', (socket) => {
    const token= socket.handshake.query.token
})

3.1.6 自定义解析器

待完成

3.2 Client

3.2.1 new Client(url,options)

• url (string)
• options? (object)
• Return: Client

可用的选项：

运行与 Node 端时 ws 库基本客户端选项参见 ws库文档

3.3 Socket

3.3.1 socket.id

• (string)

socket 会话的唯一标识符。在触发 connect 事件后设置，并在 reconnect 事件后更新。

const wscio = require('wscio')
const socket= wscio('http://127.0.0.1')
console.log(socket.id) //undefined
socket.on('connect',()=>{
    console.log(socket.id) // xxxx...
})

3.3.2 socket.connected

• (boolean)

socket 是否连接到服务器。

const wscio = require('wscio')
const socket= wscio('http://127.0.0.1')
console.log(socket.connected) //false
socket.on('connect',()=>{
    console.log(socket.connected) //true
})

3.3.3 socket.disconnected

见 socket.close()

3.3.4 socket.open([value])

• auth?: object | string 连接时上传的认证参数
• Return: Socket

手动打开 socket

const wscio = require('wscio')
const socket= wscio('http://127.0.0.1', {
    autoConnect:false
})
// ...
socket.open() //手动打开连接

它还可用于手动重新连接：

socket.on('disconnect',()=>{
    socket.open()
})

3.3.5 socket.connect()

同 socket.open()，但不支持参数

3.3.6 socket.send([...args][,ack])

• args: (any) 数据列表，可以时多个
• ack: (function) 回执函数
• Return: Socket

3.3.7 socket.emit(event,[...args][,ack])

• event: (string) 事件名
• args: (any) 数据列表
• ack: (function) 回执函数
• Return: Socket

向字符串名称标识的socket发出事件。可以包括任何其他参数。支持所有可序列化的数据结构，包括`Buffer。

const wscio = require('wscio')
const socket= wscio('http://127.0.0.1')
socket.on('connect', function() {
    socket.emit('event', arg1, arg2, ...)
    socket.emit('event', { data: new Buffer(6) })
    //ack参数是可选的，将通过服务器应答调用。
    socket.emit('event1', 'data', function(data) {
        console.log(data) // data 将是 'data1'
    })
})
// 服务器：
const wss = new require('wssio')()
wss.on('connection', (socket) => {
    socket.on('event1',(name,fn)=>{
        fn('data1');
    })
})

3.3.8 socket.on(event,callback)

• event: (string) 事件名
• callback: (function) 接收事件响应数据

为给定事件注册新的处理程序。

socket.on('event', function(data) {
    console.log(data)
})
// 多个参数
socket.on('event', function(arg1, arg2, arg3, ...) {
    // ...
})
// 使用回调
socket.on('event', function(cb) {
    cb(0)
})
// 使用参数+回调
socket.on('event', function(arg1, arg2, arg3, ..., cb) {
    cb(0)
})

socket 实际上继承了 Emitter 类的每个方法，比如 hasListeners ， once 或 off （删除一个事件监听器）

3.3.9 socket.compress(compress)

• compress: (boolean) 是否压缩数据传输标志
• Return: Socket

为后续事件发送设置一个修饰符，该修饰符只在值为 true 时压缩事件数据。不调用方法时默认为 true 。

socket.compress(false).emit('event', { data: new Buffer(1024) })

3.3.10 socket.close()

• Return: Socket

手动断开 socket 。

3.3.11 socket.disconnect()

同 socket.close()相同

3.3.12 event:connect

第一次连接成功时触发。

const wscio = require('wscio')
const socket= wscio('http://127.0.0.1')
socket.on('connect', function() {
    //第一次连接成功触发事件
})
// 注意：您应该在connect之外注册事件处理程序，
// 因此重新连接时不会再次注册它们
socket.on('myevent',()=>{
    // ....
})

3.3.13 event:connect_error

• error: (object) 错误对象

在连接错误时触发

const wscio = require('wscio')
const socket= wscio('http://127.0.0.1')
socket.on('connect_error', function(error) {
    // error为错误信息
})

3.3.14 event:error

• error: (object) 错误对象

发生错误时触发。

const wscio = require('wscio')
const socket= wscio('http://127.0.0.1')
socket.on('error', function(error) {
    // error为错误信息
})

3.3.15 event:disconnect

• reason: (string | number) '值为 客户端断开连接 时为客户端断开'，值为 3666 时为服务器端授权失败被动断开，其余值根据具体情况考虑

断开时触发

const wscio = require('wscio')
const socket= wscio('http://127.0.0.1')
socket.on('disconnect',(reason)=>{
    if(reason.code !== 3666 && reason != '客户端断开连接'){
        // 断开连接是由服务器启动的，需要手动重新连接
        socket.connect()
    }
    // 否则，socket将自动尝试重新连接
})

3.3.16 event:reconnect

• attempt: (number) 重新连接尝试次数

在成功重新连接时触发。

const wscio = require('wscio')
const socket= wscio('http://127.0.0.1')
socket.on('reconnect',(attemptNumber)=>{
    //重连成功触发，不在触发connect事件
})

3.3.17 event:reconnect_attempt

• attempt: (number) 重新连接尝试次数

试图重新连接时触发。

const wscio = require('wscio')
const socket= wscio('http://127.0.0.1')
socket.io('reconnect_attempt',(attemptNumber)=>{
    //试图重新连接时触发
})

3.3.18 event:reconnecting

• attempt: (number) 重新连接尝试次数

正在试图重新连接时触发。

const wscio = require('wscio')
const socket= wscio('http://127.0.0.1')
socket.on('reconnecting',(attemptNumber)=>{
    //正在试图重新连接时触发。
})

3.3.19 event:reconnect_error

• error: (object) 错误对象

在重新连接尝试错误时触发。

const wscio = require('wscio')
const socket= wscio('http://127.0.0.1')
socket.on('reconnect_error',(error)=>{
    //在重新连接尝试错误时触发。
})

3.3.20 event:reconnect_failed

在 reconnectionAttempts （尝试重连）内无法重新连接时触发

const wscio = require('wscio')
const socket= wscio('http://127.0.0.1')
socket.on('reconnect_failed',()=>{
    //在 `reconnectionAttempts` （尝试重连）内无法重新连接时触发
})

3.3.21 event:ping

在将ping数据包写入服务器时触发。

const wscio = require('wscio')
const socket= wscio('http://127.0.0.1')
socket.on('ping',()=>{
    //在将ping数据包写入服务器时触发。 
})