nl::Weave::Profiles::DataManagement_Current::NotificationEngine::NotifyRequestBuilder

#include <src/lib/profiles/data-management/Current/NotificationEngine.h>

This provides a helper class to compose notifies and abstract away the construction and structure of the message from its consumers.

Summary

This is a more compact version of a similar class provided in MessageDef.cpp that aims to be sensitive to the flash and ram needs of the device.

Public functions
Checkpoint(TLV::TLVWriter & aPoint)
Checkpoint the request state into a TLVWriter.
EndDataList()
End the construction of the data list array.
EndEventList()
End the construction of the event list.
EndNotifyRequest()
End the construction of the notify.
GetWriter(void)
Init(PacketBuffer *aBuf, TLV::TLVWriter *aWriter, SubscriptionHandler *aSubHandler, uint32_t aMaxPayloadSize)
Initializes the builder.
MoveToState(NotifyRequestBuilderState aDesiredState)
The main state transition function.
Rollback(TLV::TLVWriter & aPoint)
Rollback the request state into the checkpointed TLVWriter.
StartDataList(void)
Starts the construction of the data list array.
StartEventList()
Starts the construction of the event list.
StartNotifyRequest()
Start the construction of the notify.
WriteDataElement(TraitDataHandle aTraitDataHandle, PropertyPathHandle aPropertyPathHandle, SchemaVersion aSchemaVersion, PropertyPathHandle *aMergeDataHandleSet, uint32_t aNumMergeDataHandles, PropertyPathHandle *aDeleteHandleSet, uint32_t aNumDeleteHandles)
Given a trait path, write out the data element associated with that path.

Public functions

Checkpoint

WEAVE_ERROR Checkpoint(
  TLV::TLVWriter & aPoint
)

Checkpoint the request state into a TLVWriter.

Details
Parameters
[out] aPoint
A writer to checkpoint the state of the TLV writer into.
Return Values
WEAVE_NO_ERROR
On success.

EndDataList

WEAVE_ERROR EndDataList()

End the construction of the data list array.

Details
Return Values
WEAVE_NO_ERROR
On success.
WEAVE_ERROR_INCORRECT_STATE
If the request is not at the DataList container.
other
Unable to construct the end of the data list.

EndEventList

WEAVE_ERROR EndEventList()

End the construction of the event list.

Details
Return Values
WEAVE_NO_ERROR
On success.
WEAVE_ERROR_INCORRECT_STATE
If the request is not at the EventList container.
other
Unable to construct the end of the data list.

EndNotifyRequest

WEAVE_ERROR EndNotifyRequest()

End the construction of the notify.

Details
Return Values
WEAVE_NO_ERROR
On success.
WEAVE_ERROR_INCORRECT_STATE
If the request is not at Notify container.
other
Unable to construct the end of the notify.

GetWriter

TLV::TLVWriter * GetWriter(
  void
)

Init

WEAVE_ERROR Init(
  PacketBuffer *aBuf,
  TLV::TLVWriter *aWriter,
  SubscriptionHandler *aSubHandler,
  uint32_t aMaxPayloadSize
)

Initializes the builder.

Should only be called once.

Details
Return Values
WEAVE_NO_ERROR
On success.
other
Was unable to initialize the builder.

MoveToState

WEAVE_ERROR MoveToState(
  NotifyRequestBuilderState aDesiredState
)

The main state transition function.

The function takes the desired state (i.e., the phase of the notify request builder that we would like to reach), and transitions the request into that state. If the desired state is the same as the current state, the function does nothing. Otherwise, an PacketBuffer is allocated (if needed); the function first transitions the request into the toplevel notify request (either opening the notify request TLV structure, or closing the current TLV data container as needed), and then transitions the Notify request either by opening the appropriate TLV data container or by closing the overarching Notify request.

Details
Parameters
aDesiredState
The desired state the request should transition into
Return Values
WEAVE_NO_ERROR
On success.
WEAVE_ERROR_NO_MEMORY
Could not transition into the state because of insufficient memory.
WEAVE_ERROR_INCORRECT_STATE
Corruption of the internal state machine.
other
When the state machine could not record the state in its buffer, likely indicates a design flaw rather than a runtime issue.

Rollback

WEAVE_ERROR Rollback(
  TLV::TLVWriter & aPoint
)

Rollback the request state into the checkpointed TLVWriter.

Details
Parameters
[in] aPoint
A writer to that captured the state at some point in the past
Return Values
WEAVE_NO_ERROR
On success.

StartDataList

WEAVE_ERROR StartDataList(
  void
)

Starts the construction of the data list array.

Details
Return Values
WEAVE_NO_ERROR
On success.
WEAVE_ERROR_INCORRECT_STATE
If the request is not at the Notify container.
other
Unable to construct the beginning of the data list.

StartEventList

WEAVE_ERROR StartEventList()

Starts the construction of the event list.

Details
Return Values
WEAVE_NO_ERROR
On success.
WEAVE_ERROR_INCORRECT_STATE
If the request is not at the Notify container.
other
Unable to construct the beginning of the data list.

StartNotifyRequest

WEAVE_ERROR StartNotifyRequest()

Start the construction of the notify.

Details
Return Values
WEAVE_NO_ERROR
On success.
WEAVE_ERROR_INCORRECT_STATE
If the request is not at the toplevel of the buffer.
other
Unable to construct the end of the notify.

WriteDataElement

WEAVE_ERROR WriteDataElement(
  TraitDataHandle aTraitDataHandle,
  PropertyPathHandle aPropertyPathHandle,
  SchemaVersion aSchemaVersion,
  PropertyPathHandle *aMergeDataHandleSet,
  uint32_t aNumMergeDataHandles,
  PropertyPathHandle *aDeleteHandleSet,
  uint32_t aNumDeleteHandles
)

Given a trait path, write out the data element associated with that path.

The caller can also optionally pass in a handle set allows for leveraging the merge operation with a narrower set of immediate child nodes of the parent property path handle.

Details
Return Values
WEAVE_NO_ERROR
On success.
other
Unable to retrieve and write the data element.