UDP

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

1. 通过startAsync创建UDP会话「UdpSession」。
2. 操作UDP会话实例，主动（作为发送方）或被动（作为接收方）获取远端实例「UdpRemote」。
3. 操作远端实例，通过 sendAsync 或 inPacketAsync 接口获取数据包实例「UdpPacket」。
4. 操作数据包实例，通过接口 replyAsync 向数据来源发送数据。

操作接口

UDP 协议的操作接口由入口函数 startAsync 和不同层级（会话/远端/数据包）的工具类接口共同组成。

startAsync()

入口函数。启动1个UDP会话，返回 UdpSession 实例。

• 函数签名

function startAsync (hostPort?: string | number): Promise<UdpSession>;

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

startWithAsync()

入口函数的便利版本。根据指定页面的参数启动1个UDP会话，返回 UdpSession 实例。

• 函数签名

function startWithAsync (pageName: string): Promise<UdpSession>;

• 输入参数
  • pageName 目标UDP接口页面名称。查找指定名称的接口页面，获取该页面中的参数，并以此启动1个UDP会话。
• 返回值 UdpSession 实例对象。

UdpSession

UDP会话的操作接口如下：

connectToAsync()

创建1个UDP远端实例。

• 函数签名

  connectToAsync (hostPort: string | number): Promise<UdpRemote>;

• 输入参数

  • hostPort 建立到指定地址 & 端口的远端对象。若传入数字则为本地地址（localhost）的端口号。

• 返回值 UdpRemote实例对象

inRemoteAsync()

异步获取新产生的UDP远端对象。该函数只有在被动创建远端对象时才会返回。

• 函数签名

  inRemoteAsync (): Promise<UdpRemote>;

• 输入参数 无

• 返回值 Promise对象，建立新远端后返回UdpRemote对象。

onRemote()

当产生新的远端对象时触发的回调函数。包括主动（通过调用connectToAsync()）或被动（作为接收方收到来自远端的数据）产生。

• 函数签名

  onRemote (
    handler: (remote: UdpRemote) => void,
    once?: boolean
  ): CancelFunc;

• 输入参数

  • handler 回调函数，每次回调时传入的remote参数是新的远端对象。
  • once（可选），默认值为false。是否注册为一次性的回调函数，若传入true则触发了1次回调后会自动取消注册。

• 返回值 取消函数，调用此函数可以解除本次注册。

endAsync()

正常结束本会话。

• 函数签名

  endAsync (): Promise<void>;

• 输入参数 无

• 返回值 无

UdpRemote

UDP远端的操作接口如下：

sendAsync()

向远端发送数据。

• 函数签名

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

• 输入参数

  • type 数据类型。
  • data 数据内容。

  协议支持的数据类型如下：

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

• 返回值 Promise对象，发送完成后返回所发送的UdpPacket对象。

sendWithAsync()

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

• 函数签名

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

• 输入参数

  • pageName 页面名称，仅限在「接口」和「模板」页面中查找。
  • contentName 内容名称

• 返回值 Promise对象，发送完成后返回所发送的UdpPacket对象。

inPacketAsync()

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

• 函数签名

  inPacketAsync (): Promise<UdpPacket>;

• 输入参数 无

• 返回值 Promise对象，接收到数据包后返回UdpPacket对象。

onPacket()

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

• 函数签名

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

• 输入参数

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

• 返回值 取消函数，调用此函数可以解除本次注册。

onPacketIn()

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

• 函数签名

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

• 输入参数

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

• 返回值 取消函数，调用此函数可以解除本次注册。

onPacketOut()

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

• 函数签名

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

• 输入参数

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

• 返回值 取消函数，调用此函数可以解除本次注册。

UdpPacket

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

replyAsync()

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

• 函数签名

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

• 输入参数

  • type 数据类型。
  • data 数据内容。

  协议支持的数据类型如下：

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

• 返回值 Promise对象，发送完成后返回所发送的UdpPacket对象。

只读接口

UdpSession

UDP会话实例（UdpSession）提供常规的数据和状态访问接口如下：

• inBytes()：返回自会话创建以来累计接收的字节数，包含其所有远端。
• outBytes()：返回自会话创建以来累计发送的字节数，包含其所有远端。
• inPackets()：返回自会话创建以来累计接收的数据包个数，包含其所有远端。
• outPackets()：返回自会话创建以来累计发送的数据包个数，包含其所有远端。

UdpRemote

records()

获取远端的打开记录列表，远端只会打开一次。

• 函数签名

records (): FlowConnectionRecord[];

FlowConnectionRecord

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

UdpPacket

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