nl::Weave::Profiles::DataManagement_Legacy::Binding

#include <src/lib/profiles/data-management/Legacy/Binding.h>

The Binding class manages communications state on behalf of an application entity using Weave.

Summary

When an application wants to use Weave to communicate with a remote entity there exists a wide variety of options. The Binding class corrals these options and arranges them in such a way that the easy stuff is easy and the more difficult stuff is at least tractable. Options covered include:

  • unicast UDP communication with a known peer node.
  • UDP broadcast with "any" node.
  • unicast WRMP communication with a known peer node.
  • TCP communications with a known peer node.
  • TCP communications with a known service endpoint using a service manager instance to set things up.
  • TCP communications based on a pre-established connection.

Constructors and Destructors

Binding(void)
The default constructor for Binding objects.
~Binding(void)
The destructor for Binding objects.

Public types

@143{
  kState_Incomplete = 0,
  kState_Completing = 1,
  kState_Complete = 2
}
enum
The set of Binding object states.

Public attributes

mAuthMode
WeaveAuthMode
The Weave authentication mode to be used.
mConnection
A pointer to the Weave connection currently in use in this binding.
mEngine
A pointer to the ProtocolEngine object related to this Binding.
mPeerNodeId
uint64_t
The 64-bit node ID of the binding target.
mServiceMgr
A pointer to the (optional) ServiceManager object to use in completing this binding.
mState
uint8_t
The current Binding object state.
mTransport
uint8_t
The transport to use in completing this Binding.

Public functions

CompleteConfirm(WeaveConnection *aConnection)
void
Handle confirmation of a bind request.
CompleteConfirm(StatusReport & aReport)
void
Handle the failure of a bind request.
CompleteConfirm(void)
void
Handle confirmation of a bind request.
CompleteRequest(ProtocolEngine *aEngine)
Request completion of a binding.
Connect(WeaveConnection *aConnection)
Complete a TCP binding by providing a completed connection.
Finalize(void)
void
"Uncomplete" a binding and free it.
Finalize(WEAVE_ERROR aErr)
void
"Uncomplete" a binding and free it.
Free(void)
void
Clear the binding state.
GetExchangeCtx(WeaveExchangeManager *aExchangeMgr, void *aAppState)
Produce an ExchangeContext object from a Binding.
IncompleteIndication(StatusReport & aReport)
void
Handle the failure of a binding.
Init(const uint64_t & aPeerNodeId)
Initialize a Binding with just a node ID.
Init(const uint64_t & aPeerNodeId, uint8_t aTransport)
Initialize a Binding object based on peer ID and transport.
Init(const uint64_t & aServiceEpt, WeaveServiceManager *aServiceMgr, WeaveAuthMode aAuthMode)
Initialize a Binding object to a service endpoint.
Init(WeaveConnection *aConnection)
Initialize a Binding object with a WeaveConnection.
IsComplete(void)
bool
Check if a binding is complete.
IsFree(void)
bool
Check is a binding is free.
UncompleteRequest(void)
void
Cause a binding to be incomplete.
UncompleteRequest(WEAVE_ERROR aErr)
void
Cause a binding to be incomplete.

Public types

@143

 @143

The set of Binding object states.

Properties
kState_Complete

The state of a Binding that is complete and ready for use.

kState_Completing

The state of a Binding that is in the process of being completed.

kState_Incomplete

The initial (and final) state of a Binding.

Public attributes

mAuthMode

WeaveAuthMode mAuthMode

The Weave authentication mode to be used.

(READ_ONLY)

This is the authentication mode used in all communications governed by this binding.

mConnection

WeaveConnection * mConnection

A pointer to the Weave connection currently in use in this binding.

(READ-ONLY)

TCP bindings may be initialized with a connection right off the bat or they may allocate one at completion time.

mEngine

ProtocolEngine * mEngine

A pointer to the ProtocolEngine object related to this Binding.

A binding is generally completed with respect to a particular protocol engine, which is mostly used as a way of accessing the MessageLayer. This is where we keep track of it.

mPeerNodeId

uint64_t mPeerNodeId

The 64-bit node ID of the binding target.

(READ-ONLY)

Every Binding has a target entity, which is named here. In addition to a Weave node ID this may name a service endpoint.

mServiceMgr

nl::Weave::Profiles::ServiceDirectory::WeaveServiceManager * mServiceMgr

A pointer to the (optional) ServiceManager object to use in completing this binding.

(READ-ONLY)

When binding to the Weave service, a 64-bit service endpoint ID may be supplied at initialization time in place of a Weave node ID. In this case, a ServiceManager object is also required to complete the binding. Normal TCP or WRMP bindings do not require a ServiceManager object.

mState

uint8_t mState

The current Binding object state.

Only one "complete" operation can run at a time and, in any case, if you ask to complete a completed binding it just calls the confirm function immediately. The state variable below tracks the current state and acts as a lockout.

mTransport

uint8_t mTransport

The transport to use in completing this Binding.

(READ-ONLY)

Possible values for mTransport are defined in DMConstants.h.

Public functions

Binding

 Binding(
  void
)

The default constructor for Binding objects.

Clears all internal state.

CompleteConfirm

void CompleteConfirm(
  WeaveConnection *aConnection
)

Handle confirmation of a bind request.

Details
Parameters
[in] aConnection
A pointer to an active WeaveConnection to the binding target.

CompleteConfirm

void CompleteConfirm(
  StatusReport & aReport
)

Handle the failure of a bind request.

Details
Parameters
[in] aReport
A reference to a StatusReport object describing the failure.

CompleteConfirm

void CompleteConfirm(
  void
)

Handle confirmation of a bind request.

CompleteRequest

WEAVE_ERROR CompleteRequest(
  ProtocolEngine *aEngine
)

Request completion of a binding.

Completion of a binding is, at least for bindings requiring TCP, carried out with respect to a particular ProtocolEngine object, which provides access to an ExchangeManager instance.

Details
Parameters
[in] aEngine
A pointer to a ProtocolEngine object on behalf of which the completion is being performed.
Return Values
WEAVE_NO_ERROR
On success.
WEAVE_ERROR_INCORRECT_STATE
if the binding is already being completed.
WEAVE_ERROR_NO_MEMORY
If a connection is required and none are available
Returns
Otherwise, any WEAVE_ERROR returned while trying to connect.

Connect

WEAVE_ERROR Connect(
  WeaveConnection *aConnection
)

Complete a TCP binding by providing a completed connection.

A newly initialized TCP binding cannot be used until it has been completed. Normally this is done on demand when the application attempts to make use of the binding to send messages but it can also be explicitly completed by providing a Weave connection.

Details
Parameters
[in] aConnection
A pointer to a WeaveConnection used to complete the binding.
Return Values
WEAVE_NO_ERROR
On success.
WEAVE_ERROR_INCORRECT_STATE
If the binding already has a connection.
WEAVE_ERROR_INVALID_ARGUMENT
If the connection is NULL.

Finalize

void Finalize(
  void
)

"Uncomplete" a binding and free it.

Bindings may have state that requires cleanup, e.g. connection closure, which is handled by the Uncomplete() method in addition to state that is simply cleared to its initial state by the Free() method. This method, largely for the sake of convenience, invokes both.

See also:
Finalize(WEAVE_ERROR)

Finalize

void Finalize(
  WEAVE_ERROR aErr
)

"Uncomplete" a binding and free it.

Bindings may have state that requires cleanup, e.g. connection closure, which is handled by the Uncomplete() method in addition to state that is simply cleared to its initial state by the Free() method. This method, largely for the sake of convenience, invokes both.

Details
Parameters
[in] aErr
This error code indicates the cause of this request. If not WEAVE_NO_ERROR, the TCP connection could be aborted.
See also:
Finalize(void)

Free

void Free(
  void
)

Clear the binding state.

Unconditionally return all binding state to its original state.

GetExchangeCtx

ExchangeContext * GetExchangeCtx(
  WeaveExchangeManager *aExchangeMgr,
  void *aAppState
)

Produce an ExchangeContext object from a Binding.

Details
Parameters
[in] aExchangeMgr
A pointer to the exchange manager from which to request a context.
[in] aAppState
A void pointer to an application state object to be stored in the exchange context for later use.
Returns
a pointer to an ExchangeContext object, or NULL on failure.

IncompleteIndication

void IncompleteIndication(
  StatusReport & aReport
)

Handle the failure of a binding.

This method is invoked and, in turn, invokes higher-layer handlers when the binding fails AFTER completion, i.e. after CompleteConfirm() has been invoked with a status denoting success.

Details
Parameters
[in] aReport
A referemce to a StatusReport describing what went wrong.
See also:
CompleteConfirm(StatusReport &aReport).

Init

WEAVE_ERROR Init(
  const uint64_t & aPeerNodeId
)

Initialize a Binding with just a node ID.

This results in a binding with the configured default transport.

Details
Parameters
[in] aPeerNodeId
A reference to the 64-bit ID of the binding target.
Return Values
WEAVE_NO_ERROR
On success.
WEAVE_ERROR_INVALID_ARGUMENT
If the binding is under-specified.

Init

WEAVE_ERROR Init(
  const uint64_t & aPeerNodeId,
  uint8_t aTransport
)

Initialize a Binding object based on peer ID and transport.

Details
Parameters
[in] aPeerNodeId
A reference to the 64-bit node identifier of the binding target.
[in] aTransport
The transport specification, from WeaveTransportOption.
Return Values
WEAVE_NO_ERROR
On success.
WEAVE_ERROR_INVALID_ARGUMENT
If the binding is under-specified.

Init

WEAVE_ERROR Init(
  const uint64_t & aServiceEpt,
  WeaveServiceManager *aServiceMgr,
  WeaveAuthMode aAuthMode
)

Initialize a Binding object to a service endpoint.

This is how you bind to a particular endpoint on the Nest service. A binding of this kind requires a multi-stage completion process, which may include populating or updating the local service directory cache. For the most part, this process is hidden from the application but it means that errors arising later in the process may be delivered, normally via the relevant "confirm" callback, after - sometimes long after - the original request to use (and complete) the binding.

Details
Parameters
[in] aServiceEpt
A reference to the 64-bit identifier for the Weave Service endpoint of interest.
[in] aServiceMgr
A pointer to the service manager instance to use in looking up a service tier and connecting to it.
[in] aAuthMode
The authentication mode to use in connecting.
Return Values
WEAVE_NO_ERROR
On success.
WEAVE_ERROR_INVALID_ARGUMENT
If the binding is under-specified.

Init

WEAVE_ERROR Init(
  WeaveConnection *aConnection
)

Initialize a Binding object with a WeaveConnection.

Details
Parameters
[in] aConnection
A pointer to a WeaveConnection to use as a basis for the binding..
Return Values
WEAVE_NO_ERROR
On success.
WEAVE_ERROR_INVALID_ARGUMENT
If the binding is under-specified.

IsComplete

bool IsComplete(
  void
)

Check if a binding is complete.

Details
Returns
true if it's complete, false otherwise.
See also:
CompleteRequest(ProtocolEngine *aEngine)

IsFree

bool IsFree(
  void
)

Check is a binding is free.

"Free" in this context simply means, "has a defined peer node ID". IsFree() should be thought of as meaning "has had Free() called on it and has not been used since".

Details
Returns
true if the binding is free, false otherwise.

UncompleteRequest

void UncompleteRequest(
  void
)

Cause a binding to be incomplete.

Fundamentally, a binding shall be in the "incomplete" state after this method has been called on it but, more subtly, any relevant state not contained in the binding itself, e.g. TCP connection, should be cleaned up as well. Applications may consider invoking UncompleteRequest() as part of the cleanup on error.

See also:
UncompleteRequest(WEAVE_ERROR )

UncompleteRequest

void UncompleteRequest(
  WEAVE_ERROR aErr
)

Cause a binding to be incomplete.

Fundamentally, a binding shall be in the "incomplete" state after this method has been called on it but, more subtly, any relevant state not contained in the binding itself, e.g. TCP connection, should be cleaned up as well. Applications may consider invoking UncompleteRequest() as part of the cleanup on error.

Details
Parameters
[in] aErr
If not WEAVE_NO_ERROR, the existing connection, if any, would be aborted instead of gracefully closed.
See also:
UncompleteRequest(void)

~Binding

virtual  ~Binding(
  void
)

The destructor for Binding objects.

Clears all internal state AND, if necessary, closes open connections.