WebSocket

WebSocket 协议的接口以「jc.ws」作为对象访问前缀。WebSocket 通信流程包含以下步骤：

WebSocket服务端

通过startServerAsync创建WebSocket服务端会话「WsServerSession」。
操作服务端会话实例，获取连接实例「WsServerConnection」。
操作连接实例，通过 sendAsync 或 inPacketAsync 接口获取数据包实例「WsPacket」。
操作数据包实例，通过接口 replyAsync 向数据来源发送数据。

WebSocket客户端

通过startClientAsync创建WebSocket客户端连接「WsClientConnection」。
操作客户端实例，通过 sendAsync 或 inPacketAsync 接口获取数据包实例「WsPacket」。
操作数据包实例，通过接口 replyAsync 向数据包的来源发送数据。

操作接口

WebSocket 协议的操作接口由入口函数 startServerAsync、startClientAsync 和不同层级（会话/连接/数据包）的工具类接口共同组成。

`startServerAsync()`

服务端入口函数。启动1个WebSocket服务端会话，返回 WsServerSession 实例。

函数签名

function startServerAsync (hostPort?: string | number): Promise<WsServerSession>;

输入参数
- hostPort（可选）本地监听的IP地址和端口。若传入数字则为端口号，并绑定到本机的所有IP地址。若未提供则使用随机端口号，并绑定到本地所有IP地址。
返回值 WsServerSession 实例对象。

`startClientAsync()`

客户端入口函数。启动1个WebSocket客户端连接，返回 WsClientConnection 实例。

函数签名

function startClientAsync (hostPort: string | number): Promise<WsClientConnection>;

输入参数
- hostPort（可选）服务器的地址和端口。若传入数字则为端口号，并绑定到本机的所有IP地址。若未提供则使用随机端口号，并绑定到本地所有IP地址。
返回值 WsClientConnection 实例对象。

`WsServerSession`

WebSocket服务端会话的操作接口如下：

`inConnectionAsync()`

异步获取新产生的WS连接对象。

函数签名

inConnectionAsync (): Promise<WsServerConnection>;

输入参数无
返回值 Promise对象，建立新连接后返回WsServerConnection对象。

`onConnection()`

当建立（收到）新的WebSocket连接时触发的回调函数。

函数签名

onConnection (
  handler: (connection: WsServerConnection) => void,
  once?: boolean
): CancelFunc;

输入参数
- handler 回调函数，每次回调时传入的connection参数是新的连接对象。
- once（可选），默认值为false。是否注册为一次性的回调函数，若传入true则触发了1次回调后会自动取消注册。
返回值取消函数，调用此函数可以解除本次注册。

`endAsync()`

正常结束本会话

函数签名
ts
```
endAsync (): Promise<void>;
```
输入参数无
返回值无

`WsServerConnection`

WebSocket服务端连接实例的操作接口如下：

`sendAsync()`

向远端发送数据。

函数签名

sendAsync (type: string, data: any): Promise<WsPacket>;

输入参数
- type 数据类型。
- data 数据内容。
协议支持的数据类型如下：
type data类型
'text' string
'hex' string
'raw' Buffer
返回值 Promise对象，发送完成后返回所发送的WsPacket对象。

type	data类型
`'text'`	`string`
`'hex'`	`string`
`'raw'`	`Buffer`

`sendWithAsync()`

将其他页面中定义的已有数据内容向远端发送。

函数签名

sendWithAsync (pageName: string, contentName: string): Promise<WsPacket>;

输入参数
- pageName 页面名称，仅限在「接口」和「模板」页面中查找。
- contentName 内容名称
返回值 Promise对象，发送完成后返回所发送的WsPacket对象。

`inPacketAsync()`

异步获取接收到的数据包对象。

函数签名
ts
```
inPacketAsync (): Promise<WsPacket>;
```
输入参数无
返回值 Promise对象，接收到数据包后返回WsPacket对象。

`onPacket()`

当「发送」或「接收」数据包时触发回调。

函数签名

onPacket (
  handler: (packet: WsPacket) => void, once?: boolean
): CancelFunc;

输入参数
- handler 新数据包的处理函数。触发时将会回调本函数，并传入新的WsPacket实例。
- once（可选），默认值为false。是否注册为一次性的回调函数，若传入true则触发了1次回调后会自动取消注册。
返回值取消函数，调用此函数可以解除本次注册。

`onPacketIn()`

当「接收」数据包时触发回调。

函数签名

onPacketIn (
  handler: (packet: WsPacket) => void, once?: boolean
): CancelFunc;

输入参数
- handler 新数据包的处理函数。触发时将会回调本函数，并传入新的WsPacket实例。
- once（可选），默认值为false。是否注册为一次性的回调函数，若传入true则触发了1次回调后会自动取消注册。
返回值取消函数，调用此函数可以解除本次注册。

`onPacketOut()`

当「发送」数据包时触发回调。

函数签名

onPacketOut (
  handler: (packet: WsPacket) => void, once?: boolean
): CancelFunc;

输入参数
- handler 新数据包的处理函数。触发时将会回调本函数，并传入新的WsPacket实例。
- once（可选），默认值为false。是否注册为一次性的回调函数，若传入true则触发了1次回调后会自动取消注册。
返回值取消函数，调用此函数可以解除本次注册。

`destroyAsync()`

正常断开（双向关闭）本连接。

函数签名
ts
```
destroyAsync (): Promisable<void>;
```
输入参数无
返回值无

`whenDestroyedAsync()`

异步等待连接关闭。

函数签名
ts
```
whenDestroyedAsync (): Promise<void>;
```
输入参数无
返回值无

`onDestroyed()`

当连接断开后触发回调。

函数签名

onDestroyed (
  handler: (hadError: boolean) => void,
  once?: boolean
): CancelFunc;

输入参数
- handler 连接断开时的处理函数。触发时将会回调本函数，传入的参数表示是否为错误断开。
- once（可选），默认值为false。是否注册为一次性的回调函数，若传入true则触发了1次回调后会自动取消注册。
返回值取消函数，调用此函数可以解除本次注册。

`WsClientConnection`

WebSocket客户端连接实例的操作接口如下：

`sendAsync()`

向远端发送数据。

函数签名

sendAsync (type: string, data: any): Promise<WsPacket>;

输入参数
- type 数据类型。
- data 数据内容。
协议支持的数据类型如下：
type data类型
'text' string
'hex' string
'raw' Buffer
返回值 Promise对象，发送完成后返回所发送的WsPacket对象。

type	data类型
`'text'`	`string`
`'hex'`	`string`
`'raw'`	`Buffer`

`sendWithAsync()`

将其他页面中定义的已有数据内容向远端发送。

函数签名

sendWithAsync (pageName: string, contentName: string): Promise<WsPacket>;

输入参数
- pageName 页面名称，仅限在「接口」和「模板」页面中查找。
- contentName 内容名称
返回值 Promise对象，发送完成后返回所发送的WsPacket对象。

`inPacketAsync()`

异步获取接收到的数据包对象。

函数签名
ts
```
inPacketAsync (): Promise<WsPacket>;
```
输入参数无
返回值 Promise对象，接收到数据包后返回WsPacket对象。

`onPacket()`

当「发送」或「接收」数据包时触发回调。

函数签名

onPacket (
  handler: (packet: WsPacket) => void, once?: boolean
): CancelFunc;

输入参数
- handler 新数据包的处理函数。触发时将会回调本函数，并传入新的WsPacket实例。
- once（可选），默认值为false。是否注册为一次性的回调函数，若传入true则触发了1次回调后会自动取消注册。
返回值取消函数，调用此函数可以解除本次注册。

`onPacketIn()`

当「接收」数据包时触发回调。

函数签名

onPacketIn (
  handler: (packet: WsPacket) => void, once?: boolean
): CancelFunc;

输入参数
- handler 新数据包的处理函数。触发时将会回调本函数，并传入新的WsPacket实例。
- once（可选），默认值为false。是否注册为一次性的回调函数，若传入true则触发了1次回调后会自动取消注册。
返回值取消函数，调用此函数可以解除本次注册。

`onPacketOut()`

当「发送」数据包时触发回调。

函数签名

onPacketOut (
  handler: (packet: WsPacket) => void, once?: boolean
): CancelFunc;

输入参数
- handler 新数据包的处理函数。触发时将会回调本函数，并传入新的WsPacket实例。
- once（可选），默认值为false。是否注册为一次性的回调函数，若传入true则触发了1次回调后会自动取消注册。
返回值取消函数，调用此函数可以解除本次注册。

`destroyAsync()`

正常断开（双向关闭）本连接。

函数签名
ts
```
destroyAsync (): Promisable<void>;
```
输入参数无
返回值无

`whenDestroyedAsync()`

异步等待连接关闭。

函数签名
ts
```
whenDestroyedAsync (): Promise<void>;
```
输入参数无
返回值无

`onDestroyed()`

当连接断开后触发回调。

函数签名

onDestroyed (
  handler: (hadError: boolean) => void,
  once?: boolean
): CancelFunc;

输入参数
- handler 连接断开时的处理函数。触发时将会回调本函数，传入的参数表示是否为错误断开。
- once（可选），默认值为false。是否注册为一次性的回调函数，若传入true则触发了1次回调后会自动取消注册。
返回值取消函数，调用此函数可以解除本次注册。

`WsPacket`

WebSocket数据包的操作接口如下：

`replyAsync()`

向数据包的来源回复1个数据包。

函数签名

replyAsync (type: string, data: any): Promise<WsPacket>;

输入参数
- type 数据类型。
- data 数据内容。
协议支持的数据类型如下：
type data类型
'text' string
'hex' string
'raw' Buffer
返回值 Promise对象，发送完成后返回所发送的WsPacket对象。

type	data类型
`'text'`	`string`
`'hex'`	`string`
`'raw'`	`Buffer`

只读接口

`WsServerSession`

WebSocket服务端会话实例（WsServerSession）提供常规的数据和状态访问接口如下：

inBytes()：返回自会话创建以来累计接收的字节数，包含其所有连接（若存在多个连接）。
outBytes()：返回自会话创建以来累计发送的字节数，包含其所有连接（若存在多个连接）。
inPackets()：返回自会话创建以来累计接收的数据包个数，包含其所有连接（若存在多个连接）。
outPackets()：返回自会话创建以来累计发送的数据包个数，包含其所有连接（若存在多个连接）。

`WsServerConnection`

`records()`

获取连接的打开记录列表，连接只会打开一次。

函数签名

records (): FlowConnectionRecord[];

`FlowConnectionRecord`

inBytes()：返回自本次连接创建以来累计接收的字节数。
outBytes()：返回自本次连接创建以来累计发送的字节数。
inPackets()：返回自本次连接创建以来累计接收的数据包个数。
outPackets()：返回自本次连接创建以来累计发送的数据包个数。

`WsClientConnection`

`records()`

获取连接的打开记录列表，因为连接可能被多次打开/关闭。

函数签名

records (): FlowConnectionRecord[];

`WsPacket`

inout()：该数据包的收发方向，"in"为接收，"out"为发送。
length()：数据包载荷的字节数。
payload()：该数据包的原始载荷内容，即二进制数据。

WebSocket ​

操作接口 ​

startServerAsync() ​

startClientAsync() ​

WsServerSession ​

inConnectionAsync() ​

onConnection() ​

endAsync() ​

WsServerConnection ​

sendAsync() ​

sendWithAsync() ​

inPacketAsync() ​

onPacket() ​

onPacketIn() ​

onPacketOut() ​

destroyAsync() ​

whenDestroyedAsync() ​

onDestroyed() ​

WsClientConnection ​

sendAsync() ​

sendWithAsync() ​

inPacketAsync() ​

onPacket() ​

onPacketIn() ​

onPacketOut() ​

destroyAsync() ​

whenDestroyedAsync() ​

onDestroyed() ​

WsPacket ​

replyAsync() ​

只读接口 ​

WsServerSession ​

WsServerConnection ​

records() ​

FlowConnectionRecord ​

WsClientConnection ​

records() ​

WsPacket ​

WebSocket

操作接口

`startServerAsync()`

`startClientAsync()`

`WsServerSession`

`inConnectionAsync()`

`onConnection()`

`endAsync()`

`WsServerConnection`

`sendAsync()`

`sendWithAsync()`

`inPacketAsync()`

`onPacket()`

`onPacketIn()`

`onPacketOut()`

`destroyAsync()`

`whenDestroyedAsync()`

`onDestroyed()`

`WsClientConnection`

`sendAsync()`

`sendWithAsync()`

`inPacketAsync()`

`onPacket()`

`onPacketIn()`

`onPacketOut()`

`destroyAsync()`

`whenDestroyedAsync()`

`onDestroyed()`

`WsPacket`

`replyAsync()`

只读接口

`WsServerSession`

`WsServerConnection`

`records()`

`FlowConnectionRecord`

`WsClientConnection`

`records()`

`WsPacket`