# 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 成员列表 # ### 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](https://www.aardio.com/zh-cn/docs/library-reference/wsock/tcp/asyncClient.html#tcpaclientObject) ### websocketclientObject.url # 上次成功连接的网址 也可以用于指定下次连接的默认网址 ### websocketclientObject.userAgent # 客户端应用程序代理头 默认为"Mozilla/5.0" ### websocketclientObject.waitForConnected(关联窗口句柄,超时) # 等待连接到WebSocket服务端 所有参数可选,超时以毫秒为单位, 连接成功返回true,失败返回false或null ## websocketclientObject 事件列表 # ### websocketclientObject.onClose # ```aardio websocketclientObject.onClose = function(e){ /*连接被关闭 e.code为错误代码e.reason为错误原因*/ } ``` ### websocketclientObject.onError # ```aardio websocketclientObject.onError = function(err){ /*发生错误,err为错误信息*/ } ``` ### websocketclientObject.onFragment # ```aardio websocketclientObject.onFragment = function(msg){ /*收到分片数据 第一个数据包使用msg.type指明类型,参考WebSocket协议规范 后续数据包msg.type为0,最后一个数据包msg.fin为1 如果不指定这个回调函数,则自动并接分片数据后触发onMessage事件*/ } ``` ### websocketclientObject.onMessage # ```aardio websocketclientObject.onMessage = function(msg){ /*收到服务端数据 msg.type 为 1 时 msg.data 为文本, 否则 msg.data 为字节串（buffer 类型）*/ } ``` ### websocketclientObject.onOpen # ```aardio websocketclientObject.onOpen = function(){ websocketclientObject.send("已连接到WebSocket服务"); } ```