nl::Weave::Binding

#include <src/lib/core/WeaveBinding.h>

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

@13{
  kGetPeerDescription_MaxLength = nl::Weave::kWeavePeerDescription_MaxLength
}
enum
EventCallback)(void *apAppState, EventType aEvent, const InEventParam &aInParam, OutEventParam &aOutParam) typedef
void(*
EventType enum
State enum

Public attributes

AppState
void *

Public functions

AddRef(void)
void
Reserve a reference to the binding object.
AdjustResponseTimeout(ExchangeContext *apExchangeContext) const
Re-configure an existing Exchange Context to adjust the response timeout.
BeginConfiguration()
Being the process of configuring the Binding.
CanBePrepared(void) const
bool
Close(void)
void
Close the binding object and release a reference.
GetConnection() const
Get the Weave connection object associated with the binding.
GetDefaultResponseTimeout() const
uint32_t
Get the default exchange response timeout to be used when communicating with the peer.
GetDefaultWRMPConfig(void) const
const WRMPConfig &
Get the default WRMP configuration to be used when communicating with the peer.
GetEncryptionType(void) const
uint8_t
Retrieve the message encryption type to be used when encrypting messages to/from the peer.
GetEventCallback() const
EventCallback
Get the function that will be called when an API event occurs for the Binding.
GetExchangeManager() const
GetKeyId(void) const
uint32_t
Retrieve the id of the message encryption key to be used when encrypting messages to/from to the peer.
GetLogId(void) const
uint16_t
Get a unique id for the binding.
GetMaxWeavePayloadSize(const System::PacketBuffer *msgBuf)
uint32_t
Get the max Weave payload size that can fit inside the supplied PacketBuffer.
GetPeerDescription(char *buf, uint32_t bufSize) const
void
Constructs a string describing the peer node and its associated address / connection information.
GetPeerIPAddress(nl::Inet::IPAddress & address, uint16_t & port, InterfaceId & interfaceId) const
void
Retrieve the IP address information for the peer, if available.
GetPeerNodeId(void) const
uint64_t
Retrieve the node id of the binding peer.
GetProtocolLayerCallback(EventCallback & callback, void *& state) const
void
GetState(void) const
State
Retrieve the current state of the binding.
IsAuthenticMessageFromPeer(const WeaveMessageInfo *msgInfo)
bool
Determine if a particular incoming message is from the configured peer and is suitably authenticated.
IsPreparing(void) const
bool
IsReady(void) const
bool
NewExchangeContext(ExchangeContext *& appExchangeContext)
Allocate a new Exchange Context for communicating with the peer that is the target of the binding.
Release(void)
void
Release a reference to the binding object.
RequestPrepare()
Request the application to configure and prepare the Binding.
Reset(void)
void
Reset the binding back to an unconfigured state.
SetDefaultResponseTimeout(uint32_t msec)
void
Set the default exchange response timeout to be used when communicating with the peer.
SetDefaultWRMPConfig(const WRMPConfig & wrmpConfig)
void
Set the default WRMP configuration to be used when communicating with the peer.
SetEventCallback(EventCallback aEventCallback)
void
Set the application-defined function to be called when an API event occurs for the Binding.
SetProtocolLayerCallback(EventCallback callback, void *state)
void
Set an event callback function for protocol layer code using the Binding on behalf of an application.

Public static functions

DefaultEventHandler(void *apAppState, EventType aEvent, const InEventParam & aInParam, OutEventParam & aOutParam)
void
Default handler for binding API events.

Classes

nl::Weave::Binding::Configuration

Provides a declarative-style interface for configuring and preparing a Binding object.

Structs

nl::Weave::Binding::InEventParam

Input parameters to a Binding API event.

nl::Weave::Binding::OutEventParam

Output parameters to a Binding API event.

Public types

@13

 @13
Properties
kGetPeerDescription_MaxLength

Maximum length of string (including NUL character) returned by GetPeerDescription().

EventCallback

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

EventType

 EventType

State

 State

Public attributes

AppState

void * AppState

Public functions

AddRef

void AddRef(
  void
)

Reserve a reference to the binding object.

AdjustResponseTimeout

WEAVE_ERROR AdjustResponseTimeout(
  ExchangeContext *apExchangeContext
) const 

Re-configure an existing Exchange Context to adjust the response timeout.

Details
Parameters
[in] apExchangeContext
A pointer to an Exchange Context object to be re-configured

BeginConfiguration

Configuration BeginConfiguration()

Being the process of configuring the Binding.

Applications must call BeginConfiguration() to configure the Binding prior to preparing it for communicating with the peer.

Details
Returns
A Binding::Configuration object that can be used to configure the binding.

CanBePrepared

bool CanBePrepared(
  void
) const 

Close

void Close(
  void
)

Close the binding object and release a reference.

When called, this method causes the binding to enter the Closed state. Any in-progress prepare actions for the binding are canceled and all external communications resources held by the binding are released.

Calling Close() decrements the reference count associated with the binding, freeing the object if the reference count becomes zero.

GetConnection

WeaveConnection * GetConnection() const 

Get the Weave connection object associated with the binding.

Details
Returns
A pointer to a WeaveConnection object, or NULL if there is no connection associated with the binding.

GetDefaultResponseTimeout

uint32_t GetDefaultResponseTimeout() const 

Get the default exchange response timeout to be used when communicating with the peer.

Details
Returns
Response timeout in ms.

GetDefaultWRMPConfig

const WRMPConfig & GetDefaultWRMPConfig(
  void
) const 

Get the default WRMP configuration to be used when communicating with the peer.

Details
Returns
A reference to a WRMPConfig structure containing the default configuration values.

GetEncryptionType

uint8_t GetEncryptionType(
  void
) const 

Retrieve the message encryption type to be used when encrypting messages to/from the peer.

GetEventCallback

EventCallback GetEventCallback() const 

Get the function that will be called when an API event occurs for the Binding.

Details
Returns
A pointer to the callback function.

GetExchangeManager

WeaveExchangeManager * GetExchangeManager() const 

GetKeyId

uint32_t GetKeyId(
  void
) const 

Retrieve the id of the message encryption key to be used when encrypting messages to/from to the peer.

GetLogId

uint16_t GetLogId(
  void
) const 

Get a unique id for the binding.

GetMaxWeavePayloadSize

uint32_t GetMaxWeavePayloadSize(
  const System::PacketBuffer *msgBuf
)

Get the max Weave payload size that can fit inside the supplied PacketBuffer.

For UDP, including UDP with WRM, the maximum payload size returned will ensure the resulting Weave message will not overflow the configured UDP MTU.

Additionally, this method will ensure the Weave payload will not overflow the supplied PacketBuffer.

Details
Parameters
[in] msgBuf
A pointer to the PacketBuffer to which the message payload will be written.
Returns
The max Weave payload size.

GetPeerDescription

void GetPeerDescription(
  char *buf,
  uint32_t bufSize
) const 

Constructs a string describing the peer node and its associated address / connection information.

Details
Parameters
[in] buf
A pointer to a buffer into which the string should be written. The supplied buffer should be at least as big as kGetPeerDescription_MaxLength. If a smaller buffer is given the string will be truncated to fit. The output will include a NUL termination character in all cases.
[in] bufSize
The size of the buffer pointed at by buf.

GetPeerIPAddress

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

Retrieve the IP address information for the peer, if available.

The availability of the peer's IP address information depends on the state and configuration of the binding. IP address information is only available when using an IP-based transport (TCP, UDP, or UDP with WRMP). Prior to the start of preparation, address information is only available if it has been set expressly by the application during configuration. During the preparation phase, address information is available when address preparation completes (e.g. after DNS resolution has completed). After the Binding is ready, address information remains available until the Binding is reset.

Details
Parameters
[out] address
A reference to an IPAddress object that will receive the peer's IP address. If the peer's IP address information is unavailable, this value will be set to IPAddress::Any.
[out] port
A reference to an integer that will receive the peer's port number. If the peer's IP address information is unavailable, this value is undefined.
[out] interfaceId
A reference to an integer that will receive the id of the network interface via which the peer can be reached. If the peer's IP address information is unavailable, this value is undefined.

GetPeerNodeId

uint64_t GetPeerNodeId(
  void
) const 

Retrieve the node id of the binding peer.

Only valid once the binding object has been prepared.

Details
Returns
Weave node ID of the peer

GetProtocolLayerCallback

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

GetState

State GetState(
  void
) const 

Retrieve the current state of the binding.

Details
Returns
The binding state.

IsAuthenticMessageFromPeer

bool IsAuthenticMessageFromPeer(
  const WeaveMessageInfo *msgInfo
)

Determine if a particular incoming message is from the configured peer and is suitably authenticated.

This method confirms that the message in question originated from the peer node of the binding and that the encryption key and type used to encrypt the message matches those configured in the binding. For bindings configured without the use of security, the method confirms that the incoming message is NOT encrypted.

This method is intended to be used in protocols such as WDM where peers can spontaneously initiate exchanges back to the local node after an initial exchange from the node to the peer. In such cases, the method allows the local node to confirm that the incoming unsolicited message was sent by the associated peer. (Of course, for Bindings configured without the use of message encryption, this assertion provides no value from a security perspective. It merely confirms that the sender node id in the received message matches the peer's node id.)

Note that if the binding is not in the Ready state, this method will always return false.

Details
Parameters
[in] msgInfo
The Weave message information for the incoming message.
Returns
True if the message is authentically from the peer.

IsPreparing

bool IsPreparing(
  void
) const 

Details
Returns
True if the Binding is currently being prepared.

IsReady

bool IsReady(
  void
) const 

Details
Returns
True if the Binding is in the Ready state.

NewExchangeContext

WEAVE_ERROR NewExchangeContext(
  ExchangeContext *& appExchangeContext
)

Allocate a new Exchange Context for communicating with the peer that is the target of the binding.

Details
Parameters
[out] appExchangeContext
A reference to a pointer that will receive the newly allocated Exchange Context object. The pointer will be set to NULL in the event that the method fails.
Return Values
WEAVE_NO_ERROR
If the exchange context was successfully allocated.
WEAVE_ERROR_NO_MEMORY
If no memory was available to allocate the exchange context.
WEAVE_ERROR_INCORRECT_STATE
If the binding is not in the Ready state.
other
Other errors related to configuring the exchange context based on the configuration of the binding.

Release

void Release(
  void
)

Release a reference to the binding object.

If there are no more references to the binding object, the binding is closed and freed.

RequestPrepare

WEAVE_ERROR RequestPrepare()

Request the application to configure and prepare the Binding.

Protocol layer code can use this method on a Binding that has not been configured, or has failed, to trigger an event to the application (kEvent_PrepareRequested) requesting that it configure and prepare the binding for use.

This method can only be called on Bindings in the NotConfigured or Failed states.

If the application does not support on-demand configuration/preparation of Bindings, the method will fail with WEAVE_ERROR_NOT_IMPLEMENTED.

Reset

void Reset(
  void
)

Reset the binding back to an unconfigured state.

When Reset() is called, any in-progress prepare actions for the binding are canceled and all external communications resources held by the binding are released. Reset() places the binding in the Unconfigured state, after which it may be configured and prepared again.

Reset() does not alter the reference count of the binding.

SetDefaultResponseTimeout

void SetDefaultResponseTimeout(
  uint32_t msec
)

Set the default exchange response timeout to be used when communicating with the peer.

Details
Parameters
[in] timeout
The new response timeout in ms.

SetDefaultWRMPConfig

void SetDefaultWRMPConfig(
  const WRMPConfig & wrmpConfig
)

Set the default WRMP configuration to be used when communicating with the peer.

Details
Parameters
[in] aWRMPConfig
A reference to a WRMPConfig structure containing the new default configuration.

SetEventCallback

void SetEventCallback(
  EventCallback aEventCallback
)

Set the application-defined function to be called when an API event occurs for the Binding.

Details
Parameters
[in] aEventCallback
A pointer to the callback function.

SetProtocolLayerCallback

void SetProtocolLayerCallback(
  EventCallback callback,
  void *state
)

Set an event callback function for protocol layer code using the Binding on behalf of an application.

This function will be called in addition to the application-defined callback function when API events occur for the Binding.

Details
Parameters
[in] callback
A pointer to the callback function.
[in] state
A pointer to a state object that will be supplied to the protocol layer code when a protocol layer callback occurs.

Public static functions

DefaultEventHandler

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

Default handler for binding 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 binding to the application's event handler function.

Details
Parameters
[in] apAppState
A pointer to application-defined state information associated with the binding.
[in] aEvent
Event ID passed by the event callback
[in] aInParam
Reference of input event parameters passed by the event callback
[in] aOutParam
Reference of output event parameters passed by the event callback