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.

Summary

The WeaveEchoClient class implements the initiator side of the Weave Echo protocol. Similar to the ICMP ping protocol, the Weave Echo protocol can be used to test the liveness and reachability of a Weave node.

Applications can use the WeaveEchoClient class to send one-off or repeating EchoRequest messages to a peer node identified by a Binding object. A corresponding class exists for responding to echo requests (see WeaveEchoServer).

Client Binding

The WeaveEchoClient takes a Weave Binding object which is used to identify and establish communication with the intended recipient of the echo requests. The Binding can be configured and prepared by the application prior to the initialization of the WeaveEchoClient object, or it can be left unprepared, in which case the WeaveEchoClient will request on-demand preparation of the binding (see Binding::RequestPrepare() for details).

On-demand preparation of the Binding will also be requested should it fail after having entered the Ready state.

SendRepeating Mode

The SendRepeating() method can be used to put the WeaveEchoClient into SendRepeating mode. In this mode the client object sends a repeating sequence of EchoRequest messages to the peer at a configured interval. SendRepeating mode can be canceled by calling the Stop() method.

Multicast and Broadcast

A WeaveEchoClient object can be used to send EchoRequests to multiple recipients simultaneously by configuring the Binding object with an appropriate IPv6 multicast address or IPv4 local network broadcast address (255.255.255.255). When the WeaveEchoClient object detects a multicast or broadcast peer address, it automatically enters MultiResponse mode upon send of the EchoRequest.

In this mode, the object continues to listen for and deliver all incoming EchoResponse messages that arrive on the same exchange. The object remains in MultiResponse mode until: 1) the application calls Stop() or Send(), 2) in SendRepeating mode, the time comes to send another request, or 3) no response is received and the receive timeout expires.

API Events

During the course of its operation, the WeaveEchoClient object will call up to the application to request specific actions or deliver notifications of important events. These API event calls are made to the currently configured callback function on the client object. Except where noted, applications are free to alter the state of the client during an event callback. One overall exception is the object's Shutdown() method, which may never be called during a callback.

The following API events are defined:

PreparePayload

The WeaveEchoClient is about to form an EchoRequest message and is requesting the application to supply a payload. If an application desires, it may return a new PacketBuffer containing the payload data. If the application does not handle this event, a EchoRequest with a zero-length payload will be sent automatically. The application MAY NOT alter the state of the WeaveEchoClient during this callback.

RequestSent

An EchoRequest message was sent to the peer.

ResponseReceived

An EchoResponse message was received from the peer. Arguments to the event contain the response payload and meta-information about the response message.

CommunicationError

An error occurred while forming or sending an EchoRequest, or while waiting for a response. Examples of errors that can occur while waiting for a response are key errors or unexpected close of a connection. Arguments to the event contain the error reason.

ResponseTimeout

An EchoResponse was not received in the alloted time. The response timeout is controlled by the DefaultResponseTimeout property on the Binding object.

RequestAborted

An in-progress Echo exchange was aborted because a request was made to send another EchoRequest before a response was received to the previous message. This can arise in SendRepeating mode when the time arrives to send the next EchoRequest. This can also happen if the application calls Send() after an EchoRequest has been sent but before any response is received.

When the object is in MultiResponse mode, the event is suppressed if at least one EchoResponse message has been received.

Constructors and Destructors
`WeaveEchoClient(void)`

Public types
`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 }`	enum
`State{ kState_NotInitialized = 0, kState_Idle = 1, kState_PreparingBinding = 2, kState_RequestInProgress = 3, kState_WaitingToSend = 4 }`	enum

Public attributes
`AppState`	`void *` A pointer to application-specific data.

Public functions
`GetBinding(void) const`	`Binding *` Returns a pointer to the Binding object associated with the WeaveEchoClient.
`GetEventCallback(void) const`	`EventCallback` Returns a pointer to the API event callback function currently configured on the WeaveEchoClient object.
`GetState(void) const`	`State` Retrieve the current state of the WeaveEchoClient object.
`Init(Binding binding, EventCallback eventCallback, void appState)`	`WEAVE_ERROR` Initialize a WeaveEchoClient object.
`IsSendRrepeating() const`	`bool` Returns true if the WeaveEchoClient object is currently in send-repeating mode.
`RequestInProgress() const`	`bool` Returns true if an EchoRequest has been sent and the WeaveEchoClient object is awaiting a response.
`Send(void)`	`WEAVE_ERROR` Send an EchoRequest message to the peer.
`Send(PacketBuffer *payloadBuf)`	`WEAVE_ERROR` Send an EchoRequest message to the peer with a specific payload.
`SendRepeating(uint32_t sendIntervalMS)`	`WEAVE_ERROR` Initiate sending a repeating sequence of EchoRequest messages to the peer.
`SetEventCallback(EventCallback eventCallback)`	`void` Sets the API event callback function on the WeaveEchoClient object.
`Shutdown(void)`	`void` Shutdown a previously initialized WeaveEchoClient object.
`Stop(void)`	`void` Stops any Echo exchange in progress and cancels send-repeating mode.

Public static functions
`DefaultEventHandler(void *appState, EventType eventType, const InEventParam & inParam, OutEventParam & outParam)`	`void` Default handler for WeaveEchoClient API events.

Structs
nl::Weave::Profiles::Echo_Next::WeaveEchoClient::InEventParam	Input parameters to WeaveEchoClient API event.
nl::Weave::Profiles::Echo_Next::WeaveEchoClient::OutEventParam	Output parameters to WeaveEchoClient API event.

Public types

EventCallback

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

EventType

 EventType

Properties
`kEvent_CommunicationError`	A communication error occurred while sending an EchoRequest or waiting for a response.
`kEvent_DefaultCheck`	Used to verify correct default event handling in the application.
`kEvent_PreparePayload`	The application is requested to prepare the payload for the Echo request.
`kEvent_RequestAborted`	An in-progress Echo exchange was aborted because a request was made to start another exchange.
`kEvent_RequestSent`	An EchoRequest message was sent to the peer.
`kEvent_ResponseReceived`	An EchoResponse message was received from the peer.
`kEvent_ResponseTimeout`	An EchoResponse was not received in the alloted time.

State

 State

Properties
`kState_Idle`	The client object is idle.
`kState_NotInitialized`	The client object is not initialized.
`kState_PreparingBinding`	The client object is waiting for the binding to become ready.
`kState_RequestInProgress`	An EchoRequest message has been sent and the client object is awaiting a response.
`kState_WaitingToSend`	SendRepeating() has been called and the client object is waiting for the next time to send an EchoRequest.

Public attributes

AppState

void * AppState

A pointer to application-specific data.

Public functions

GetBinding

Binding * GetBinding(
  void
) const

Returns a pointer to the Binding object associated with the WeaveEchoClient.

GetEventCallback

EventCallback GetEventCallback(
  void
) const

Returns a pointer to the API event callback function currently configured on the WeaveEchoClient object.

GetState

State GetState(
  void
) const

Retrieve the current state of the WeaveEchoClient object.

Init

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

Initialize a WeaveEchoClient object.

Initialize a WeaveEchoClient object in preparation for sending echo messages to a peer.

Details

Parameters

`[in] binding`	A Binding object that will be used to establish communication with the peer node.
`[in] eventCallback`	A pointer to a function that will be called by the WeaveEchoClient object to deliver API events to the application.
`[in] appState`	A pointer to an application-defined object which will be passed back to the application whenever an API event occurs.

IsSendRrepeating

bool IsSendRrepeating() const

Returns true if the WeaveEchoClient object is currently in send-repeating mode.

RequestInProgress

bool RequestInProgress() const

Returns true if an EchoRequest has been sent and the WeaveEchoClient object is awaiting a response.

Send

WEAVE_ERROR Send(
  void
)

Send an EchoRequest message to the peer.

This method initiates the process of sending an EchoRequest message to the peer node. If and when a corresponding EchoResponse message is received it will be delivered to the application via the ResponseReceived API event.

When forming the EchoRequest message, the WeaveEchoClient makes a request to the application, via the PreparePayload API event, to prepare the payload of the message.

If the Binding object is not in the Ready state when this method is called, a request will be made to Binding::RequestPrepare() method to initiate on-demand preparation. The send operation will then be queued until this process completes. The maximum depth of this queue is one. Thus any call to Send() while there is a previous send in the queue will result in only a single EchoRequest being sent.

Calling Send() while the WeaveEchoClient is in send-repeating mode (i.e. because of a previous call to SendRepeating()) has the effect of accelerating and resetting the send cycle but does not take the WeaveEchoClient out of send-repeating mode.

Send

WEAVE_ERROR Send(
  PacketBuffer *payloadBuf
)

Send an EchoRequest message to the peer with a specific payload.

This method initiates the process of sending an EchoRequest message to the peer node. The contents of the supplied payload buffer will be sent to the peer as the payload of the EchoRequest message. If and when a corresponding EchoResponse message is received it will be delivered to the application via the ResponseReceived API event.

Upon calling this method, ownership of the supplied payload buffer passes to the WeaveEchoClient object, which has the responsibility to free it. This is true regardless of whether method completes successfully or with an error.

If the Binding object is not in the Ready state when this method is called, a request will be made to Binding::RequestPrepare() method to initiate on-demand preparation. The send operation will then be queued until this process is complete. The maximum depth of this queue is one. Thus any call to Send() while there is a previous send in the queue will result in only a single EchoRequest being sent.

Details

Parameters

[in] payloadBuf

A PacketBuffer object containing payload data to be sent to the peer. Ownership of this buffer passes to the WeaveEchoClient object in all cases.

SendRepeating

WEAVE_ERROR SendRepeating(
  uint32_t sendIntervalMS
)

Initiate sending a repeating sequence of EchoRequest messages to the peer.

This method initiates a repeating process of sending EchoRequest messages to the peer. As EchoResponse messages are received from the peer they are delivered to the application via the ResponseReceived API event.

When SendRepeating() is called, the WeaveEchoClient enters send-repeating mode in which it stays until Stop() is called or a Binding error occurs. Calling SendRepeating() multiple times has the effect of resetting the send cycle and updating the interval.

The initial send of a sequence occurs at the time SendRepeating() is called, or whenever the Binding becomes ready after SendRepeating() is called (see below). Subsequent sends occur thereafter at the specified interval.

Each time a send occurs, the WeaveEchoClient makes a request to the application, via the PreparePayload API event, to prepare the payload of the message.

If the Binding object is not in the Ready state when it comes time to send a message, a request will be made to the Binding::RequestPrepare() method to initiate on-demand preparation. Further repeated message sends will be paused until this process completes. A failure during on-demand Binding preparation will cause the WeaveEchoClient to leave send-repeating mode.

SetEventCallback

void SetEventCallback(
  EventCallback eventCallback
)

Sets the API event callback function on the WeaveEchoClient object.

Shutdown

void Shutdown(
  void
)

Shutdown a previously initialized WeaveEchoClient object.

Note that this method can only be called if the Init() method has been called previously.

Stop

void Stop(
  void
)

Stops any Echo exchange in progress and cancels send-repeating mode.

WeaveEchoClient

 WeaveEchoClient(
  void
)

Public static functions

DefaultEventHandler

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

Default handler for WeaveEchoClient API events.

Applications are required to call this method for any API events that they don't recognize or handle. Supplied parameters must be the same as those passed by the client object to the application's event handler function.

Details

Parameters

`[in] appState`	A pointer to application-defined state information associated with the client object.
`[in] eventType`	Event ID passed by the event callback
`[in] inParam`	Reference of input event parameters passed by the event callback
`[in] outParam`	Reference of output event parameters passed by the event callback

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

Summary

Constructors and Destructors

Public types

Public attributes

Public functions

Public static functions

Structs

Public types

EventCallback

EventType

State

Public attributes

AppState

Public functions

GetBinding

GetEventCallback

GetState

Init

IsSendRrepeating

RequestInProgress

Send

Send

SendRepeating

SetEventCallback

Shutdown

Stop

WeaveEchoClient

Public static functions

DefaultEventHandler