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 类将一次性或重复的 EchoRequest 消息发送到由 Binding 对象标识的对等节点。也存在响应 echo 请求的相应类(请参阅 WeaveEchoServer)。

客户端绑定

WeaveEchoClient 接受一个 Weave Binding 对象,该对象用于标识 echo 请求的预期接收者并与之建立通信。Binding 可由应用在初始化 WeaveEchoClient 对象之前进行配置和准备,也可以处于未准备状态,在这种情况下,WeaveEchoClient 会请求按需准备绑定(如需了解详情,请参阅 Binding::RequestPrepare())。

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

发送重复模式

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

多播和广播

您可以使用 WeaveEchoClient 对象来同时向多个接收者发送 EchoRequest,方法是使用适当的 IPv6 多播地址或 IPv4 本地网络广播地址 (255.255.255.255) 配置 Binding 对象。当 WeaveEchoClient 对象检测到多播或广播对等地址时,会在发送 EchoRequest 时自动进入 MultiResponse 模式。

在此模式下,该对象会继续监听并传送通过同一交换消息到达的所有传入 EchoResponse 消息。该对象将保持 MultiResponse 模式,直到:1) 应用调用 Stop()Send();2) 在 SendRepeating 模式下发送另一个请求,或者 3) 未收到响应,且接收超时到期。

API 事件

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

定义了以下 API 事件:

PreparePayload

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

RequestSent

向对等端发送了 EchoRequest 消息。

ResponseReceived

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

CommunicationError

形成或发送 EchoRequest 或者在等待响应时出错。等待响应期间可能发生的错误示例包括关键错误或连接意外关闭。事件的参数包含错误原因。

ResponseTimeout

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

RequestAborted

由于在收到对上一条消息的响应之前发出了发送另一个 EchoRequest 的请求,因此正在进行的 Echo 交换被取消。当到达发送下一个 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。

公共属性

AppState

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 事件时,该对象将传递回应用。

IsSendRrepeating

bool IsSendRrepeating() const 

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

RequestInProgress

bool RequestInProgress() const 

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

发送

WEAVE_ERROR Send(
  void
)

向对等端发送一条 EchoRequest 消息。

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

形成 EchoRequest 消息时,WeaveEchoClient 会通过 PreparePayload API 事件向应用发出请求,以准备消息的载荷。

如果在调用此方法时 Binding 对象未处于就绪状态,系统将向 Binding::RequestPrepare() 方法发出请求,以启动按需准备。然后,发送操作将排入队列,直到此过程完成。此队列的最大深度为一。因此,当队列中有上一个发送时,如果对 Send() 进行调用,则仅发送一个 EchoRequest。

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

发送

WEAVE_ERROR Send(
  PacketBuffer *payloadBuf
)

向对等方发送带有特定载荷的 EchoRequest 消息。

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

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

如果在调用此方法时 Binding 对象未处于就绪状态,系统将向 Binding::RequestPrepare() 方法发出请求,以启动按需准备。然后,发送操作将排入队列,直到此过程完成。此队列的最大深度为一。因此,当队列中有上一个发送时,如果对 Send() 进行调用,则仅发送一个 EchoRequest。

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

具体说明
参数
[in] payloadBuf
PacketBuffer 对象,包含要发送到对等方的载荷数据。在任何情况下,此缓冲区的所有权都会传递给 WeaveEchoClient 对象。

SendRepeating

WEAVE_ERROR SendRepeating(
  uint32_t sendIntervalMS
)

开始向对等端重复发送一系列 EchoRequest 消息。

此方法会重复执行向对等端发送 EchoRequest 消息的过程。从对等方收到 EchoResponse 消息后,它们会通过 ResponseReceived API 事件传送到应用。

当调用 SendRepeating() 时,WeaveEchoClient 会进入重复发送模式,在该模式下,直到调用 Stop() 或发生 Binding 错误为止。多次调用 SendRepeating() 会导致重置发送周期并更新时间间隔。

序列的初始发送发生在 SendRepeating() 调用时,或者每当调用 SendRepeating()Binding 变为就绪时(见下文)。后续发送将按照指定的时间间隔发送。

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

如果 Binding 对象在发送消息时未处于就绪状态,系统将向 Binding::RequestPrepare() 方法发出请求,以启动按需准备。系统会暂停继续重复发送的消息,直到此过程完成为止。如果按需 Binding 准备阶段失败,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
对事件回调函数传递的输出事件参数的引用