nl::Weave::Profiles::DataManagement_Legacy::ProtocolEngine

This is an abstract class.

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

The WDM protocol engine class.

Summary

A data management entity, client or publisher, has a protocol engine component and a data manager component. This abstract class represents the common features of the protocol engine.

Inheritance

Direct Known Subclasses:
  nl::Weave::Profiles::DataManagement_Legacy::DMClient
  nl::Weave::Profiles::DataManagement_Legacy::DMPublisher

Constructors and Destructors
ProtocolEngine(void)
~ProtocolEngine(void)

Protected attributes
mBindingTable[kBindingTableSize]
The ProtocolEngine has a binding table that, if the engine is going to be responsible for anything beyond simply receiving broadcast notifications, probably needs to contain at least one entry.
mExchangeMgr
mResponseTimeout
uint32_t
mTransactionTable[kTransactionTableSize]

Public functions
BindConfirm(Binding *aBinding)
virtual WEAVE_ERROR
Handle confirmation that a bind request has been successfully completed.
BindConfirm(Binding *aBinding, StatusReport & aReport)
virtual WEAVE_ERROR
Handle confirmation that a bind request has failed.
BindRequest(const uint64_t & aPeerNodeId, uint8_t aTransport)
Request a binding using a known peer node ID and transport specifier.
BindRequest(const uint64_t & aPeerNodeId)
Bind to a known peer using the default transport.
BindRequest(nl::Weave::Profiles::ServiceDirectory::WeaveServiceManager *aServiceMgr, WeaveAuthMode aAuthMode)
BindRequest(WeaveConnection *aConnection)
Request a binding using an active Weave connection.
IncompleteIndication(Binding *aBinding, StatusReport & aReport)
virtual void
Handle an indication that a binding has failed.
IncompleteIndication(const uint64_t & aPeerNodeId, StatusReport & aReport)=0
virtual void
Handle an indication that a binding has become incomplete.
Init(WeaveExchangeManager *aExchangeMgr)
virtual WEAVE_ERROR
Init(WeaveExchangeManager *aExchangeMgr, uint32_t aResponseTimeout)
virtual WEAVE_ERROR
UnbindRequest(const uint64_t & aPeerNodeId)
void
Request that a binding be undone and removed from the binding table.
UnbindRequest(const uint64_t & aPeerNodeId, WEAVE_ERROR aErr)
void
Request that a binding be undone and removed from the binding table.

Protected functions
Clear(void)
void
ClearBindingTable(void)
void
ClearTransactionTable(void)
void
DequeueTransaction(DMTransaction *aTransaction)
void
EnqueueTransaction(DMTransaction *aTransaction, Binding *aBinding)
EnqueueTransaction(DMTransaction *aTransaction)
FailTransactions(Binding *aBinding, StatusReport & aReport)
bool
Finalize(void)
virtual void
FinalizeBindingTable(void)
void
FinalizeTransactionTable(void)
void
FinalizeTransactions(Binding *aBinding)
void
FromExchangeCtx(ExchangeContext *aExchangeCtx)
GetBinding(const uint64_t & aPeerNodeId)
NewBinding(void)
StartTransaction(DMTransaction *aTransaction, Binding *aBinding)
StartTransaction(DMTransaction *aTransaction)
StatusResponse(ExchangeContext *aExchangeCtx, StatusReport & aStatus)

Classes
nl::Weave::Profiles::DataManagement_Legacy::ProtocolEngine::DMTransaction

Protected attributes

mBindingTable

Binding mBindingTable[kBindingTableSize]

The ProtocolEngine has a binding table that, if the engine is going to be responsible for anything beyond simply receiving broadcast notifications, probably needs to contain at least one entry.

Bindings are generally indexed by node ID. What this means is that each engine can only have a single binding to a given service endpoint.

The WDM specification has this notion of "default binding" which is the place messages go if no explicit destination is supplied. This will mostly be used in very simple devices with a single binding or a small number of bindings and, for other purposes, will just be the first binding formed.

mExchangeMgr

WeaveExchangeManager * mExchangeMgr

mResponseTimeout

uint32_t mResponseTimeout

mTransactionTable

TransactionTableEntry mTransactionTable[kTransactionTableSize]

Public functions

BindConfirm

virtual WEAVE_ERROR BindConfirm(
  Binding *aBinding
)

Handle confirmation that a bind request has been successfully completed.

Once a binding has been completed, the protocol engine goes through the transaction table and starts any transactions that are dependent on that binding.

Details
Parameters
[in] aBinding
A pointer to the completed binding.
Returns
WEAVE_NO_ERROR On success. Otherwise return a WEAVE_ERROR reflecting an inability to start a transaction.

BindConfirm

virtual WEAVE_ERROR BindConfirm(
  Binding *aBinding,
  StatusReport & aReport
)

Handle confirmation that a bind request has failed.

When a bind request fails, the protocol engine must go through the transaction table and fail any transactions depending on the binding.

Details
Parameters
[in] aBinding
A pointer to the failed binding.
[in] aReport
A reference to a StatusReport object detailing the reason for failure.
Returns

BindRequest

WEAVE_ERROR BindRequest(
  const uint64_t & aPeerNodeId,
  uint8_t aTransport
)

Request a binding using a known peer node ID and transport specifier.

Given a peer node ID and a transport specification this request sets up a binding to that peer. The biding will require additional completion ONLY if the transport is TCP. If a binding to the peer is already present, it is re-used.

Details
Parameters
[in] aPeerNodeId
A reference to the 64-bit node ID of the peer entity that is the binding target.
[in] aTransport
The transport to use.
Returns
WEAVE_NO_ERROR on success or WEAVE_ERROR_NO_MEMORY if the binding table is full. Otherwise return a WEAVE_ERROR reflecting a failure to initialize the binding.
See also:
WeaveTransportOption

BindRequest

WEAVE_ERROR BindRequest(
  const uint64_t & aPeerNodeId
)

Bind to a known peer using the default transport.

Details
Parameters
[in] aPeerNodeId
A reference to the 64-bit node ID of the peer entity that is the binding target.
Returns
WEAVE_NO_ERROR On success. Otherwise return a WEAVE_ERROR reflecting the failure of the bind operation.

BindRequest

WEAVE_ERROR BindRequest(
  nl::Weave::Profiles::ServiceDirectory::WeaveServiceManager *aServiceMgr,
  WeaveAuthMode aAuthMode
)

BindRequest

WEAVE_ERROR BindRequest(
  WeaveConnection *aConnection
)

Request a binding using an active Weave connection.

A binding may also be established using an existing, and open, connection. Note that bindings that are established in this way require no additional completion.

Details
Parameters
[in] aConnection
A Pointer to a Weave connection to be used by the binding.
Returns
WEAVE_NO_ERROR on success or WEAVE_ERROR_NO_MEMORY if the binding table is full. Otherwise return an error reflecting a failure to inititialize the binding.

IncompleteIndication

virtual void IncompleteIndication(
  Binding *aBinding,
  StatusReport & aReport
)

Handle an indication that a binding has failed.

When a binding becomes incomplete, i.e. when the connection is closed for a TCP binding, the protocol engine must fail any transactions that depend on it, which includes calling their status handlers. Also, the incomplete indication is passed up to any superclass object implementing the alternate form of this method that takes a peer ID.

Details
Parameters
[in] aBinding
A pointer to the failed binding.
[in] aReport
A reference to a StatusReport object detailing the reason for failure.

IncompleteIndication

virtual void IncompleteIndication(
  const uint64_t & aPeerNodeId,
  StatusReport & aReport
)=0

Handle an indication that a binding has become incomplete.

Higher layers that want to be informed of binding failure should use this method, which simply passes the peer ID along with a status report. In fact, since this method is virtual void, any DMClient or DMPublisher subclass must provide an implementation.

Details
Parameters
[in] aPeerNodeId
A reference to the 64-bit ID of the peer node or service endpoint that is that target of the failed binding.
[in] aReport
A reference to a StatusReport object detailing the reason for failure.

Init

virtual WEAVE_ERROR Init(
  WeaveExchangeManager *aExchangeMgr
)

Init

virtual WEAVE_ERROR Init(
  WeaveExchangeManager *aExchangeMgr,
  uint32_t aResponseTimeout
)

ProtocolEngine

 ProtocolEngine(
  void
)

UnbindRequest

void UnbindRequest(
  const uint64_t & aPeerNodeId
)

Request that a binding be undone and removed from the binding table.

When a binding is "unbound" any transactions that currently depend on it should be removed as well. This method finalizes all transactions with this binding automatically.

Details
Parameters
[in] aPeerNodeId
A reference to the 64-bit node ID or service endpoint that identifies the binding.
See also:
UnbindRequest(const uint64_t, WEAVE_ERROR)

UnbindRequest

void UnbindRequest(
  const uint64_t & aPeerNodeId,
  WEAVE_ERROR aErr
)

Request that a binding be undone and removed from the binding table.

When a binding is "unbound" any transactions that currently depend on it should be removed as well. This method finalizes all transactions with this binding automatically.

Details
Parameters
[in] aPeerNodeId
A reference to the 64-bit node ID or service endpoint that identifies the binding.
[in] aErr
WEAVE_NO_ERROR if there is no specific reason for this unbind request, otherwise the cause of error would be passed down.
See also:
UnbindRequest(const uint64_t)

~ProtocolEngine

virtual  ~ProtocolEngine(
  void
)

Protected functions

Clear

void Clear(
  void
)

ClearBindingTable

void ClearBindingTable(
  void
)

ClearTransactionTable

void ClearTransactionTable(
  void
)

DequeueTransaction

void DequeueTransaction(
  DMTransaction *aTransaction
)

EnqueueTransaction

WEAVE_ERROR EnqueueTransaction(
  DMTransaction *aTransaction,
  Binding *aBinding
)

EnqueueTransaction

WEAVE_ERROR EnqueueTransaction(
  DMTransaction *aTransaction
)

FailTransactions

bool FailTransactions(
  Binding *aBinding,
  StatusReport & aReport
)

Finalize

virtual void Finalize(
  void
)

FinalizeBindingTable

void FinalizeBindingTable(
  void
)

FinalizeTransactionTable

void FinalizeTransactionTable(
  void
)

FinalizeTransactions

void FinalizeTransactions(
  Binding *aBinding
)

FromExchangeCtx

Binding * FromExchangeCtx(
  ExchangeContext *aExchangeCtx
)

GetBinding

Binding * GetBinding(
  const uint64_t & aPeerNodeId
)

NewBinding

Binding * NewBinding(
  void
)

StartTransaction

WEAVE_ERROR StartTransaction(
  DMTransaction *aTransaction,
  Binding *aBinding
)

StartTransaction

WEAVE_ERROR StartTransaction(
  DMTransaction *aTransaction
)

StatusResponse

WEAVE_ERROR StatusResponse(
  ExchangeContext *aExchangeCtx,
  StatusReport & aStatus
)