aardio 文档

web.socket.client 库模块帮助文档

web.socket.client 成员列表 #

支持单线程异步的 WebSocket 客户端
可直接在界面线程中使用,不会阻塞界面,不需要创建多线程
支持服务端心跳(Ping/Pong帧),客户端单向心跳(Pong帧)机制,
可调用 close 函数断线,并可调用 connect 函数实现重析连接服务器

web.socket.client.getSecAccept() #

获取WebSocket客户端配对密钥,
参数指定服务端HTTP头中sec-websocket-accept返回的值

web.socket.client.getSecKey() #

获取WebSocket客户端密钥

web.socket.client.sha1() #

使用sha1算法取哈希值,并使用Base64编码为普通文本

web.socket 成员列表 #

纯 aardio 代码实现的轻量 WebSocket 组件。
默认支持 ws 协议。
如果提前导入 dotNet.sslTunnel.client 可支持 wss 协议。
改用 web.SocketSharp 扩展库也可支持 wss 协议

web.socket.client() #

返回对象:websocketclientObject

websocketclientObject 成员列表 #

websocketclientObject._translateMessage #

此回调函数的参数与onMessage相同,
如果定义了这个回调函数,
那么此函数将在调用onMessage以后被调用,
这个函数提供了一个机会用于自动处理服务器消息
,为其他需要扩展web.socket.client功能的库所预留,
一旦定义将不能修改

websocketclientObject.close() #

关闭连接
可选增加2个参数指定发送给服务器的关闭帧附加数据:
参数@1为数值类型的错误代码,参数@2为字符串类型错误描述

websocketclientObject.connect("ws://") #

重新连接到 WebSocket 服务端。
参数 @1 指定 WebSocket 服务端网址,例如 ws://localhost:7511
如果事先导入 dotNet.sslTunnel.client 则可以指定 wss:// 协议的网址。
如果指定 wss 协议网址,则可选用参数 @2 指定证书路径或数据(buffer 类型),
可选用参数 @3 指定证书密码。
如果不指定参数 @1,则获取上次调用此函数指定的网址参数,
如果之前也没有指定网址则抛出异常

websocketclientObject.headers #

其他HTTP请求头
值可以是文本或数组、或键值对组成的表
请求时会调用 web.joinHeaders()函数拼接并转换HTTP头
该函数支持的类型和格式这个属性都可以支持

websocketclientObject.heartbeatData #

心跳包发送的数据,默认为空字符串("")。
指定为空字符串时,默认发送 Ping 帧(Ping/Pong 双向心跳)。
指定非空字符串则发送文本帧(业务心跳,最常用)。
指定 buffer 或结构体则发送二进微 Binary 帧(业务心跳)。
可用 heartbeatType 属性显式指定心跳帧类型。

修改此属性只能在下次调用 connect 函数才会生效。

websocketclientObject.heartbeatInterval #

客户端主动发送心跳间隔。
以秒为单位,默认为 30 秒,设为-1时禁用客户端心跳。
默认发送 Ping 帧(Ping/Pong 双向心跳)。
heartbeatData 指定非空字符串则发送文本帧(业务心跳,最常用)。
heartbeatData 指定 buffer 或结构体则发送二进微 Binary 帧(业务心跳)。
可用 heartbeatType 属性显式指定心跳帧类型。

websocketclientObject.heartbeatType #

单向心跳发送的的帧类型。
设为 null (默认、推荐)则根据 heartbeatData 属性自动选择帧类型。
也可设为 1(文本帧),2(Binary帧),0xA(单向心跳 Pong 帧), 9 (Ping 帧)。
大多数服务端不支持单向 Pong 帧心跳,容易导致报错不建议使用。
Ping/Poing 帧大多数由服务端先发起,客户端一般不必发 Ping 帧心跳。
大多数 WebSocket 支持的是业务心跳。

修改此属性下次调用 connect 函数才会生效

websocketclientObject.isClosed() #

套接字是否已关闭

websocketclientObject.isConnected() #

套接字是否已连接并准备就绪(已与服务器握手成功)

websocketclientObject.originUrl #

浏览器启动 WebSocket 客户端的网址
一些 WebSocket 服务器根据这个判断是不是允许连接,
所以有时候设置这个很重要
默认使用WebSocket网址,并把 前面的ws://改为http://

websocketclientObject.protocol #

HTTP 头Sec-WebSocket-Protocol 的值,
也就是应用程序支持的协议列表。
默认值为 "chat",指定为 null 则省略此 HTTP 头。

websocketclientObject.readyState #

连接状态,
0为等待连接,1为已连接并准备就绪,2为正在关闭,3为已关闭
只有成功通过WebSocket协议握手以后readyState才会被置为1
这与socket.readyState连接成功就会置为1是不同的

websocketclientObject.responseHeaders #

服务端响应的 HTTP 头,
这是一个表对象,键名都已转为小写

websocketclientObject.secKey #

连接密钥,不可改动

websocketclientObject.send() #

发送数据,支持字符串或 buffer、结构体
字符串作为UTF8文本类型发送,其他以二进制类型发送,
成功返回true

websocketclientObject.sendData(data,opcode,fin,mask,rsv1,rsv2,rsv3) #

发送WebSocket数据包
参数@1支持支持字符串或 buffer、结构体
除参数@1以外,所以参数可选
一般应当调用send函数,而不是调用sendData函数

如果一定要使用这个函数,请阅读此函数源码,以及WebSocket协议相关说明

websocketclientObject.socket #

异步套接字对象
在关闭连接状态下此属性的值为null
应由对象自动打开或删除套接字对象,调用者不可改动此属性的值

返回对象:tcpaclientObject

websocketclientObject.url #

上次成功连接的网址
也可以用于指定下次连接的默认网址

websocketclientObject.userAgent #

客户端应用程序代理头
默认为"Mozilla/5.0"

websocketclientObject.waitForConnected(关联窗口句柄,超时) #

等待连接到WebSocket服务端
所有参数可选,超时以毫秒为单位,

连接成功返回true,失败返回false或null

websocketclientObject 事件列表 #

websocketclientObject.onClose #

websocketclientObject.onClose = function(e){
    /*连接被关闭  
e.code为错误代码e.reason为错误原因*/  
}

websocketclientObject.onError #

websocketclientObject.onError = function(err){
    /*发生错误,err为错误信息*/
}

websocketclientObject.onFragment #

websocketclientObject.onFragment = function(msg){
   /*收到分片数据  
第一个数据包使用msg.type指明类型,参考WebSocket协议规范  
后续数据包msg.type为0,最后一个数据包msg.fin为1  

如果不指定这个回调函数,则自动并接分片数据后触发onMessage事件*/ 
}

websocketclientObject.onMessage #

websocketclientObject.onMessage = function(msg){
    /*收到服务端数据  
msg.type 为 1 时 msg.data 为文本,  
否则 msg.data 为字节串(buffer 类型)*/

}

websocketclientObject.onOpen #

websocketclientObject.onOpen = function(){
    websocketclientObject.send("已连接到WebSocket服务");
}

Markdown 格式