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
`@165{ 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`	`WeaveConnection *` A pointer to the Weave connection currently in use in this binding.
`mEngine`	`ProtocolEngine *` A pointer to the ProtocolEngine object related to this Binding.
`mPeerNodeId`	`uint64_t` The 64-bit node ID of the binding target.
`mServiceMgr`	`nl::Weave::Profiles::ServiceDirectory::WeaveServiceManager *` 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)`	`WEAVE_ERROR` Request completion of a binding.
`Connect(WeaveConnection *aConnection)`	`WEAVE_ERROR` 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)`	`ExchangeContext *` Produce an ExchangeContext object from a Binding.
`IncompleteIndication(StatusReport & aReport)`	`void` Handle the failure of a binding.
`Init(const uint64_t & aPeerNodeId)`	`WEAVE_ERROR` Initialize a Binding with just a node ID.
`Init(const uint64_t & aPeerNodeId, uint8_t aTransport)`	`WEAVE_ERROR` Initialize a Binding object based on peer ID and transport.
`Init(const uint64_t & aServiceEpt, WeaveServiceManager *aServiceMgr, WeaveAuthMode aAuthMode)`	`WEAVE_ERROR` Initialize a Binding object to a service endpoint.
`Init(WeaveConnection *aConnection)`	`WEAVE_ERROR` 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

@165

 @165

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.

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.

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.

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.

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

Summary

Constructors and Destructors

Public types

Public attributes

Public functions

Public types

@165

Public attributes

mAuthMode

mConnection

mEngine

mPeerNodeId

mServiceMgr

mState

mTransport

Public functions

Binding

CompleteConfirm

CompleteConfirm

CompleteConfirm

CompleteRequest

Connect

Finalize

Finalize

Free

GetExchangeCtx

IncompleteIndication

Init

Init

Init

Init

IsComplete

IsFree

UncompleteRequest

UncompleteRequest

~Binding