nl::Weave::Binding

Captures the intended target of a Weave communication and associated configuration information.

Summary

A Binding object identifies the intended target of a Weave communication (also known as the "peer"), along with a set of configuration parameters describing how communication with the peer should take place. Bindings are independent of the application protocol being spoken between the two parties. As such, they capture the "who" and the "how" of a communication, but not the "what."

Configuration

Applications must configure a Binding with parameters specific to the type of communication channel desired. Bindings provide support for a range of network transports, including TCP, UDP, UDP with Weave Reliable Messaging, and Weave over BLE (WoBLE). Applications can also request the use of specific security mechanisms to protect messages sent between the parties. These include CASE and PASE sessions, and application group keys. The interface for configuring a Binding uses a declarative API style that allows applications to state their requirements for the communication in simple terms.

See the documentation for Binding::Configuration for further details.

Preparation

Prior to communication taking place, a Binding must be "prepared." The act of preparing a Binding involves establishing the necessary state for communication to take place. This can include things such as: resolving the network address of the peer, establishing a network connection, and negotiating security keys. Once configured by the application, the Binding takes care of all the steps necessary to prepare for communication, calling back to the application when the process is complete. In this way, Bindings hide the mechanics of communication, allowing applications to concentrate on the high-level interactions.

Communication

Once a Binding has been prepared it becomes ready for use. In this state, applications (or more commonly, protocol layer code working on behalf of an application) request the Binding to allocate a Weave exchange context. The resultant exchange context comes pre-configured for communication, allowing the application to immediately initiate a Weave exchange with the peer. The application can continue to request exchange contexts from the Binding until such time as the Binding is closed, or some event, e.g., a network failure, terminates the underlying communication channel.

Binding State Changes

Over the course of its use, a Binding will deliver API events to the application informing it of changes in the Binding's state. For example, when preparation succeeds, the application will receive an event informing it that the Binding is ready for use. Similarly, if the underlying communication channel fails, an event is delivered to the application informing it that the Binding is no longer in the ready state.

API events are delivered to the application via an event callback function supplied when the Binding is allocated.

Binding Lifetime

Binding are reference counted to allow shared use across multiple software components. When a Binding is allocated, a single reference to the binding is created. The application is responsible for releasing this reference at some point in the future such that the Binding is free for subsequent reuse.

When an application is done with a Binding it may call Close() on the binding. This releases the application's reference to the Binding and blocks all further delivery of API events. When the last reference to a Binding is released, it is automatically closed.

Public types

 @23

void(* EventCallback)(void *apAppState, EventType aEvent, const InEventParam &aInParam, OutEventParam &aOutParam)

 EventType

 State

void * AppState

void AddRef(
  void
)

WEAVE_ERROR AdjustResponseTimeout(
  ExchangeContext *apExchangeContext
) const 

WEAVE_ERROR AllocateRightSizedBuffer(
  PacketBuffer *& buf,
  const uint32_t desiredSize,
  const uint32_t minSize,
  uint32_t & outMaxPayloadSize
)

Configuration BeginConfiguration()

bool CanBePrepared(
  void
) const 

void Close(
  void
)

WeaveConnection * GetConnection() const 

uint32_t GetDefaultResponseTimeout() const 

const WRMPConfig & GetDefaultWRMPConfig(
  void
) const 

uint8_t GetEncryptionType(
  void
) const 

EventCallback GetEventCallback() const 

WeaveExchangeManager * GetExchangeManager() const 

uint32_t GetKeyId(
  void
) const 

uint16_t GetLogId(
  void
) const 

uint32_t GetMaxWeavePayloadSize(
  const System::PacketBuffer *msgBuf
)

void GetPeerDescription(
  char *buf,
  uint32_t bufSize
) const 

void GetPeerIPAddress(
  nl::Inet::IPAddress & address,
  uint16_t & port,
  InterfaceId & interfaceId
) const 

uint64_t GetPeerNodeId(
  void
) const 

void GetProtocolLayerCallback(
  EventCallback & callback,
  void *& state
) const 

State GetState(
  void
) const 

bool IsAuthenticMessageFromPeer(
  const WeaveMessageInfo *msgInfo
)

bool IsConnectionTransport() const 

bool IsPreparing(
  void
) const 

bool IsReady(
  void
) const 

bool IsUDPTransport() const 

bool IsUnreliableUDPTransport() const 

bool IsWRMTransport() const 

WEAVE_ERROR NewExchangeContext(
  ExchangeContext *& appExchangeContext
)

void Release(
  void
)

WEAVE_ERROR RequestPrepare()

void Reset(
  void
)

void SetDefaultResponseTimeout(
  uint32_t msec
)

void SetDefaultWRMPConfig(
  const WRMPConfig & wrmpConfig
)

void SetEventCallback(
  EventCallback aEventCallback
)

void SetProtocolLayerCallback(
  EventCallback callback,
  void *state
)

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