nl::Weave::Profiles::DataManagement_Current::CommandSender

Summary

Note:This class encapsulates the protocol details of sending commands, simplifying the mechanics involved for applications. The application provides a PacketBuffer containing the payload of the command as well as an optional set of arguments that alter the contents of the command header as well as the behavior of the command. The utility of this wrapper around command handling is indeed limited, mainly due to the complexity/flexibility involved in security validation and data serialization/de-serialization.

The details for command validation is still TBD

This class also helps applications infer if the data within an associated TraitDataSink has caught up to the side-effects of the commmand (based on the version provided in the command response). The application is responsible for managing the storage of that object.

Weave Binding

An object of this class can be intialized with a Weave Binding, which will serve as the default Binding to use to send Commands. The user may also provide a Binding to each call of SendCommand(), which will override the default Binding. It is not necessary to provide a default Binding, however any binding provided to CommandSender must already be initialized.

EventCallback

The user must define a function of this type if they wish to be updated about events that happen after the sending of the command (see "API Events" below). This can be NULL if the user does not care what happens after the command is sent.

API Events

The following events are the possible outcomes after sending a Command:

CommunicationError

An error occurred while forming or sending the Command, 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. The error reason will be contained in the InEventParam argument to the EventCallback handler.

InProgressReceived

The recipient can send an 'in progress' message which signifies that the Command has been receieved, but not yet completed. Once completed, the recipient will send a Response or StatusReport. Sending an 'in progress' message is not required.

StatusReportReceived

Receipt of a StatusReport implies that there was an error in processing the Command. The StatusReport can be accessed through the InEventParam.

ResponseReceived

Receiving a Response implies that the Command recipient handled the Command successfully. The Response may contain a payload or it may not. If the applcation desires to keep the packet buffer, it may call ExchangeContext::AddRef() to increment the ref count.

Public types

void(* EventCallback)(void *const aAppState, EventType aEvent, const InEventParam &aInParam, OutEventParam &aOutEventParam)

 EventType

void * mAppState = NULL

SynchronizedTraitState * mSyncronizedTraitState = NULL

void DefaultEventHandler(
  void *aAppState,
  EventType aEvent,
  const InEventParam & aInParam,
  OutEventParam & aOutParam
)

void Close(
  bool aAbortNow
)

WEAVE_ERROR Init(
  nl::Weave::Binding *aBinding,
  const EventCallback aEventCallback,
  void *const aAppState
)

WEAVE_ERROR SendCommand(
  nl::Weave::PacketBuffer *aPayload,
  nl::Weave::Binding *aBinding,
  ResourceIdentifier & aResourceId,
  uint32_t aProfileId,
  uint32_t aCommandType
)

WEAVE_ERROR SendCommand(
  nl::Weave::PacketBuffer *aPayload,
  nl::Weave::Binding *aBinding,
  SendParams & aSendParams
)

void SetSynchronizedTraitState(
  SynchronizedTraitState *aTraitState
)