nl::Weave::Profiles::DataManagement_Legacy::DMClient

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

The abstract base class for application-specific WDM clients.

Summary

DMClient is the standard WDM client. The implementation optionally includes subscription/notification. It is a mix of the DM ProtocolEngine class, which handles the comms crank-turning, and the wholly abstract ClientDataManager class, with some of the subscription-related methods implemented so that higher layers don't have to worry about them.

The handlers for subscription-related tasks mainly act as a thin adapter over the ClientNotifier object. Subclass implementers should take care to call the relevant super-class methods in order to turn the subscription manager crank.

DMClient request methods generally have 2 signatures, one with an explicit destination node ID and the other with a specified destination. In either case, the ability to send a message to a publisher depends on a pre-existing binding in the client but, in the first case, the destination ID is intended to select between multiple bound destination and, in the second case, the first item in the binding table is selected as a default. This is useful, for example, if the client will only ever be bound to a single publisher.

Inheritance

Inherits from:
  nl::Weave::Profiles::DataManagement_Legacy::ProtocolEngine
  nl::Weave::Profiles::DataManagement_Legacy::ClientDataManager

Constructors and Destructors
DMClient(void)
The default constructor for DMClient objects.
~DMClient(void)
The destructor for DMClient objects.
ViewRequest(const uint64_t & aDestinationId, ReferencedTLVData & aPathList, uint16_t aTxnId, uint32_t aTimeout)
virtual WEAVE_ERROR
Request a view of published data.
ViewRequest(ReferencedTLVData & aPathList, uint16_t aTxnId, uint32_t aTimeout)
virtual WEAVE_ERROR
Request a view of data on default publisher.
UpdateRequest(const uint64_t & aDestinationId, ReferencedTLVData & aDataList, uint16_t aTxnId, uint32_t aTimeout)
virtual WEAVE_ERROR
Request an update to published data.
UpdateRequest(ReferencedTLVData & aDataList, uint16_t aTxnId, uint32_t aTimeout)
virtual WEAVE_ERROR
Request an update to data on the default publisher.

Protected attributes
mUpdatePool[kUpdatePoolSize]
mViewPool[kViewPoolSize]

Public functions
CancelTransactionRequest(uint16_t aTxnId, WEAVE_ERROR aError)
Request that an executing transaction be canceled.
Clear(void)
virtual void
Clear the internal state associated with a DMClient object.
Finalize(void)
virtual void
Shut down an operating DMClient.
IncompleteIndication(Binding *aBinding, StatusReport & aReport)
virtual void
Handle the "incompletion" of a binding in use by the client.

Protected functions
NewUpdate(void)
Update *
NewView(void)
View *

ViewRequest

virtual WEAVE_ERROR ViewRequest(
  const uint64_t & aDestinationId,
  ReferencedTLVData & aPathList,
  uint16_t aTxnId,
  uint32_t aTimeout
)

Request a view of published data.

Request a view of data residing on and managed by a specified remote publisher.

Details
Parameters
[in] aDestinationId
A reference to the 64-bit node ID of the remote publisher.
[in] aPathList
A reference to a ReferencedTLVData object containing a TLV-encoded path list indicating the requested data.
[in] aTxnId
An identifier for the WDM transaction set up to manage this view operation.
[in] aTimeout
A maximum time in milliseconds to wait for the view response.
Return Values
WEAVE_NO_ERROR
On success.
WEAVE_ERROR_NO_MEMORY
If a transaction couldn't be allocated.
Returns
Otherwise, a WEAVE_ERROR reflecting the failure to initialize or start the transaction.

ViewRequest

virtual WEAVE_ERROR ViewRequest(
  ReferencedTLVData & aPathList,
  uint16_t aTxnId,
  uint32_t aTimeout
)

Request a view of data on default publisher.

Request a view of data residing on and managed by the "default" publisher, i.e. the first (or only) publisher in the client's binding table.

Details
Parameters
[in] aPathList
A reference to a ReferencedTLVData object containing a TLV-encoded path list indicating the requested data.
[in] aTxnId
An identifier for the WDM transaction set up to manage this view operation.
[in] aTimeout
A maximum time in milliseconds to wait for the view response.
Return Values
WEAVE_NO_ERROR
On success.
WEAVE_ERROR_NO_MEMORY
If a transaction couldn't be allocated.
Returns
Otherwise, a WEAVE_ERROR reflecting the failure to initialize or start the transaction.

UpdateRequest

virtual WEAVE_ERROR UpdateRequest(
  const uint64_t & aDestinationId,
  ReferencedTLVData & aDataList,
  uint16_t aTxnId,
  uint32_t aTimeout
)

Request an update to published data.

Request that a remote publisher update data under management.

Details
Parameters
[in] aDestinationId
A reference to the 64-bit node ID of the remote publisher to which the request is being sent.
[in] aDataList
A reference to a ReferencedTLVData object containing a TLV-encoded data list containing a representation of the update including the paths to which the update is to be applied.
[in] aTxnId
An identifier for the transaction set up to manage the update request.
[in] aTimeout
A maximum time in milliseconds to wait for the corresponding status report.
Returns
WEAVE_NO_ERROR on success or WEAVE_ERROR_NO_MEMORY if an update transaction could not be allocated. Otherwise, return a WEAVE_ERROR reflecting an update failure.

UpdateRequest

virtual WEAVE_ERROR UpdateRequest(
  ReferencedTLVData & aDataList,
  uint16_t aTxnId,
  uint32_t aTimeout
)

Request an update to data on the default publisher.

Request that a remote publisher update data under management. This version directs the request to the publisher that is the target of the client's default binding.

Details
Parameters
[in] aDataList
A reference to a ReferencedTLVData object containing a TLV-encoded data list containing a representation of the update including the paths to which the update is to be applied.
[in] aTxnId
An identifier for the transaction set up to manage the update request.
[in] aTimeout
A maximum time in milliseconds to wait for the corresponding status report.
Returns
WEAVE_NO_ERROR on success or WEAVE_ERROR_NO_MEMORY if an update transaction could not be allocated. Otherwise, return a WEAVE_ERROR reflecting an update failure.

Protected attributes

mUpdatePool

Update mUpdatePool[kUpdatePoolSize]

mViewPool

View mViewPool[kViewPoolSize]

Public functions

CancelTransactionRequest

WEAVE_ERROR CancelTransactionRequest(
  uint16_t aTxnId,
  WEAVE_ERROR aError
)

Request that an executing transaction be canceled.

This method doesn't generate network traffic, but just release resources allocated for the specified transaction(s)

Details
Parameters
[in] aTxnId
The number of the transaction to be canceled. If kTransactionIdNotSpecified is provided, all transactions would be canceled.
[in] aError
The WEAVE_ERROR to report when canceling the transaction.
Returns
WEAVE_NO_ERROR on success or a WEAVE_ERROR reflecting a failure to cancel the transaction.

Clear

virtual void Clear(
  void
)

Clear the internal state associated with a DMClient object.

In particular, this method clears all the client transaction pools. For clients that have been in use the Finalize() method is preferable since it also cancels subscriptions and cleans up the transaction and binding tables.

See also:
Finalize()

DMClient

 DMClient(
  void
)

The default constructor for DMClient objects.

Clears all internal state. A DMClient requires further initialization with Init() before use.

Finalize

virtual void Finalize(
  void
)

Shut down an operating DMClient.

Clears all the operating state associated with the client and removes all related subscriptions from the notifier. After a call to Finalize() a DMClient may be reinitialized simply by calling Init(). Finalize() is invoked by the DMClient destructor but may be called in the case where a DMClient requires cleanup, e.g. in case of failure or temporary shutdown, but may need to be reconstituted at some later time.

IncompleteIndication

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

Handle the "incompletion" of a binding in use by the client.

When a binding fails unexpectedly, e.g. if the connection involved in the binding is closed, then this method is called.

Details
Parameters
[in] aBinding
A pointer to the Binding that has become incomplete.
[in] aReport
A reference to a status report giving a reason for the failure.

~DMClient

virtual  ~DMClient(
  void
)

The destructor for DMClient objects.

Clears all internal state and, if necessary cancels pending subscriptions.

Protected functions

NewUpdate

Update * NewUpdate(
  void
)

NewView

View * NewView(
  void
)