nl::Weave::Profiles::Echo_Next::WeaveEchoClient

#include <src/lib/profiles/echo/Next/WeaveEchoClient.h>

Provides the ability to send Weave EchoRequest messages to a peer node and receive
the corresponding EchoResponse messages.

摘要

WeaveEchoClient 类用于实现 Weave Echo 协议的发起方。与 ICMP ping 协议类似,Weave Echo 协议可用于测试 Weave 节点的活跃性和可达性。

应用可以使用 WeaveEchoClient 类向 Binding 对象标识的对等节点发送一次性或重复的 EchoRequest 消息。相应的类可用于响应回声请求(请参阅 WeaveEchoServer)。

客户端绑定

WeaveEchoClient 会有一个 Weave Binding 对象,用于标识回声请求的预期收件人并与之建立通信。绑定可以在应用初始化 WeaveEchoClient 对象之前由应用进行配置和准备,在这种情况下,WeaveEchoClient 将请求按需绑定绑定(如需了解详情,请参阅 Binding::RequestPrepare())。

如果绑定在进入就绪状态后失败,则系统也会请求按需绑定。

SendRepeating 模式

SendRepeating() 方法可用于将 WeaveEchoClient 置于 SendRepeating 模式。在此模式下,客户端对象会以配置的时间间隔向对等设备发送重复的 EchoRequest 消息序列。可以通过调用 Stop() 方法取消 SendRepeating 模式。

多播和广播

WeaveEchoClient 对象可通过使用适当的 IPv6 多播地址或 IPv4 本地网络广播地址 (255.255.255.255) 配置 Binding 对象,从而同时向多个收件人发送 EchoRequest。当 WeaveEchoClient 对象检测到多播或广播对等地址时,会在发送 EchoRequest 时自动进入多响应模式。

在此模式下,对象会继续监听并传递到达同一广告交易平台的所有 EchoResponse 消息。该对象会一直处于 MultiResponse 模式,直到:1) 应用调用 Stop()Send(),2) 在 SendRepeating 模式下,该时间到了发送另一个请求,或者 3) 未收到响应并且接收超时到期。

API 事件

在操作过程中,WeaveEchoClient 对象会调用应用以请求执行特定操作或传送重要事件的通知。这些 API 事件调用是在客户端对象上当前配置的回调函数执行的。除非另有说明,否则应用可在事件回调期间随意更改客户端的状态。一种整体例外情况是该对象的 Shutdown() 方法,该方法在回调期间可能永远不会被调用。

定义了以下 API 事件:

准备载荷

WeaveEchoClient 将生成 EchoRequest 消息,并请求应用提供载荷。如果应用需要,可能会返回包含载荷数据的新 PacketBuffer。如果应用不处理此事件,系统会自动发送具有零长度载荷的 EchoRequest。在此回调期间,应用不得更改 WeaveEchoClient 的状态。

已发送的请求

已向对等设备发送 EchoRequest 消息。

收到响应

从对等端收到了 EchoResponse 消息。该事件的参数包含响应载荷以及有关响应消息的元信息。

通信错误

生成或发送 EchoRequest 或等待响应时发生错误。等待响应时可能发生的错误示例如下:关键错误或意外连接关闭。该事件的参数包含错误原因。

响应超时

在指定时间内未收到 EchoResponse。响应超时由 Binding 对象上的 DefaultResponseTimeout 属性控制。

请求已中止

正在进行的 Echo 交换被取消了,因为在收到对上一条消息的响应前又发送了另一个 EchoRequest 请求。当到达到达时间以发送下一个 EchoRequest 时,在 SendRepeating 模式下可能会出现此问题。如果应用在发送 EchoRequest 之后但收到任何响应之前调用了 Send(),也会出现这种情况。

当对象处于 MultiResponse 模式时,如果至少收到一条 EchoResponse 消息,则系统将抑制该事件。

构造函数和构造函数

WeaveEchoClient(void)

公共类型

EventCallback)(void *appState, EventType eventType, const InEventParam &inParam, OutEventParam &outParam) typedef
void(*
EventType{
  kEvent_PreparePayload = 1,
  kEvent_RequestSent = 2,
  kEvent_ResponseReceived = 3,
  kEvent_CommunicationError = 4,
  kEvent_ResponseTimeout = 5,
  kEvent_RequestAborted = 6,
  kEvent_DefaultCheck = 100
}
枚举
State{
  kState_NotInitialized = 0,
  kState_Idle = 1,
  kState_PreparingBinding = 2,
  kState_RequestInProgress = 3,
  kState_WaitingToSend = 4
}
枚举

公共属性

AppState
void *
指向应用专属数据的指针。

公共函数

GetBinding(void) const
返回与 WeaveEchoClient 关联的 Binding 对象。
GetEventCallback(void) const
EventCallback
返回当前在 WeaveEchoClient 对象上配置的 API 事件回调函数的指针。
GetState(void) const
检索 WeaveEchoClient 对象的当前状态。
Init(Binding *binding, EventCallback eventCallback, void *appState)
初始化 WeaveEchoClient 对象。
IsSendRrepeating() const
bool
如果 WeaveEchoClient 对象当前处于发送重复模式,则返回 true。
RequestInProgress() const
bool
如果已发送 EchoRequest 且 WeaveEchoClient 对象正在等待响应,则返回 true。
Send(void)
向对等设备发送 EchoRequest 消息。
Send(PacketBuffer *payloadBuf)
向对等方发送包含特定载荷的 EchoRequest 消息。
SendRepeating(uint32_t sendIntervalMS)
开始向对等设备发送重复的 EchoRequest 消息。
SetEventCallback(EventCallback eventCallback)
void
针对 WeaveEchoClient 对象设置 API 事件回调函数。
Shutdown(void)
void
关闭之前初始化的 WeaveEchoClient 对象。
Stop(void)
void
停止正在进行的任何 Echo 交换并取消发送重复模式。

公共静态函数

DefaultEventHandler(void *appState, EventType eventType, const InEventParam & inParam, OutEventParam & outParam)
void
WeaveEchoClient API 事件的默认处理程序。

结构体

nl::Weave::Profiles::Echo_Next::WeaveEchoClient::InEventParam

WeaveEchoClient API 事件的输入参数,

nl::Weave::Profiles::Echo_Next::WeaveEchoClient::OutEventParam

WeaveEchoClient API 事件的输出参数。

公共类型

EventCallback

void(* EventCallback)(void *appState, EventType eventType, const InEventParam &inParam, OutEventParam &outParam)

EventType

 EventType
属性
kEvent_CommunicationError

发送 EchoRequest 或等待响应时发生通信错误。

kEvent_DefaultCheck

用于验证应用的默认事件处理是否正确。

kEvent_PreparePayload

请求应用为 Echo 请求准备载荷。

kEvent_RequestAborted

进行中的 Echo 交换已取消,因为有人请求启动另一个广告交易平台。

kEvent_RequestSent

已向对等设备发送 EchoRequest 消息。

kEvent_ResponseReceived

从对等端收到了 EchoResponse 消息。

kEvent_ResponseTimeout

在指定时间内未收到 EchoResponse。

状态

 State
属性
kState_Idle

客户端对象处于空闲状态。

kState_NotInitialized

客户端对象未初始化。

kState_PreparingBinding

客户端对象正在等待绑定准备就绪。

kState_RequestInProgress

已发送 EchoRequest 消息,客户端对象正在等待响应。

kState_WaitingToSend

SendRepeating() 时,客户端对象正在等待下次发送 EchoRequest。

公共属性

应用状态

void * AppState

指向应用专属数据的指针。

公共函数

GetBinding

Binding * GetBinding(
  void
) const 

返回与 WeaveEchoClient 关联的 Binding 对象。

GetEventCallback

EventCallback GetEventCallback(
  void
) const 

返回当前在 WeaveEchoClient 对象上配置的 API 事件回调函数的指针。

GetState

State GetState(
  void
) const 

检索 WeaveEchoClient 对象的当前状态。

Init

WEAVE_ERROR Init(
  Binding *binding,
  EventCallback eventCallback,
  void *appState
)

初始化 WeaveEchoClient 对象。

初始化 WeaveEchoClient 对象,以便为向对等端发送回声消息做好准备。

详细信息
参数
[in] binding
用于与对等节点建立通信的 Binding 对象。
[in] eventCallback
指向函数的指针,将由 WeaveEchoClient 对象调用,以向应用传递 API 事件。
[in] appState
指向应用定义的对象的指针,每当发生 API 事件时,该对象都会传递回应用。

重复发送

bool IsSendRrepeating() const 

如果 WeaveEchoClient 对象当前处于发送重复模式,则返回 true。

请求进行中

bool RequestInProgress() const 

如果已发送 EchoRequest 且 WeaveEchoClient 对象正在等待响应,则返回 true。

发送

WEAVE_ERROR Send(
  void
)

向对等设备发送 EchoRequest 消息。

此方法会启动向对等节点发送 EchoRequest 消息的过程。如果收到相应的 EchoResponse 消息,则系统会通过 ResponseReceived API 事件将其传送到应用。

在生成 EchoRequest 消息时,WeaveEchoClient 通过 PreparePayload API 事件向应用发出请求,以准备消息的有效负载。

在调用此方法时,如果 Binding 对象未处于 Ready 状态,系统会向 Binding::RequestPrepare() 方法发出请求,以启动按需准备。然后,发送操作会排入队列,直到此过程完成。此队列的最大深度为 1。因此,如果队列中之前有发送操作,对 Send() 的任何调用都只会发送一个 EchoRequest。

WeaveEchoClient 处于发送重复模式(即,之前对 SendRepeating() 调用)时调用 Send() 可以加快和重置发送周期,但不会使 WeaveEchoClient 退出发送重复模式。

发送

WEAVE_ERROR Send(
  PacketBuffer *payloadBuf
)

向对等方发送包含特定载荷的 EchoRequest 消息。

此方法会启动向对等节点发送 EchoRequest 消息的过程。提供的负载缓冲区的内容将作为 EchoRequest 消息的载荷发送到对等设备。如果收到相应的 EchoResponse 消息,则系统会通过 ResponseReceived API 事件将其传送到应用。

调用此方法时,所提供的载荷缓冲区的所有权将传递给 WeaveEchoClient 对象,该对象负责释放该对象。无论方法成功完成还是出现错误,都是如此。

在调用此方法时,如果 Binding 对象未处于 Ready 状态,系统会向 Binding::RequestPrepare() 方法发出请求,以启动按需准备。然后,发送操作会排入队列,直到此过程完成。此队列的最大深度为 1。因此,如果队列中之前有发送操作,对 Send() 的任何调用都只会发送一个 EchoRequest。

WeaveEchoClient 处于发送重复模式(即,之前对 SendRepeating() 调用)时调用 Send() 可以加快和重置发送周期,但不会使 WeaveEchoClient 退出发送重复模式。

详细信息
参数
[in] payloadBuf
包含要发送到对等节点的载荷数据的 PacketBuffer 对象。在所有情况下,此缓冲区的所有权都会传递给 WeaveEchoClient 对象。

发送重复

WEAVE_ERROR SendRepeating(
  uint32_t sendIntervalMS
)

开始向对等设备发送重复的 EchoRequest 消息。

此方法会启动一个重复流程,以将 EchoRequest 消息发送到对等端。由于 EchoResponse 消息是从对等端接收的,因此通过 ResponseReceived API 事件被传送到应用。

调用 SendRepeating() 时,WeaveEchoClient 会进入发送重复模式,直到调用 Stop() 或发生绑定错误为止。多次调用 SendRepeating() 可以重置发送周期并更新间隔。

序列的初始发送发生在调用 SendRepeating() 时,或在每次调用 Binding 之后,SendRepeating()(见下文)。之后按照指定的时间间隔发送。

每次发生发送事件时,WeaveEchoClient 都会通过 PreparePayload API 事件向应用发出请求,以准备消息载荷。

如果在发送消息时 Binding 对象未处于就绪状态,系统会向 Binding::RequestPrepare() 方法发出请求以启动按需准备。后续重复发送的信息会暂停,直到此过程完成为止。在按需绑定准备期间失败将导致 WeaveEchoClient 退出发送重复模式。

SetEventCallback

void SetEventCallback(
  EventCallback eventCallback
)

针对 WeaveEchoClient 对象设置 API 事件回调函数。

关机

void Shutdown(
  void
)

关闭之前初始化的 WeaveEchoClient 对象。

请注意,只有在之前调用过 Init() 方法的情况下才能调用此方法。

停止

void Stop(
  void
)

停止正在进行的任何 Echo 交换并取消发送重复模式。

WeaveEchoClient

 WeaveEchoClient(
  void
)

公共静态函数

DefaultEventHandler 类中的方法

void DefaultEventHandler(
  void *appState,
  EventType eventType,
  const InEventParam & inParam,
  OutEventParam & outParam
)

WeaveEchoClient API 事件的默认处理程序。

应用必须为其无法识别或处理的任何 API 事件调用此方法。提供的参数必须与客户端对象传递给应用的事件处理脚本函数的参数相同。

详细信息
参数
[in] appState
指向与客户端对象关联的应用定义状态信息的指针。
[in] eventType
事件回调传递的事件 ID
[in] inParam
事件回调传递的输入事件参数引用
[in] outParam
事件回调传递的输出事件参数参考