Guides Happy Reference Resources
GitHub
Reference Specifications

nl::Weave::Profiles::DataManagement_Current::SubscriptionClient

Summary

Public types
@123 enum
EventCallback)(void *const aAppState, EventID aEvent, const InEventParam &aInParam, OutEventParam &aOutParam) typedef
void(*
Callback to pass subscription events to application.
EventID{
  kEvent_OnSubscriptionTerminated = 1,
  kEvent_OnExchangeStart = 2,
  kEvent_OnSubscribeRequestPrepareNeeded = 3,
  kEvent_OnSubscriptionEstablished = 4,
  kEvent_OnNotificationRequest = 5,
  kEvent_OnNotificationProcessed = 6,
  kEvent_OnEventStreamReceived = 7,
  kEvent_OnSubscriptionActivity = 8,
  kEvent_OnUpdateComplete = 9,
  kEvent_OnNoMorePendingUpdates = 10
} 		enum
ResubscribePolicyCallback)(void *const aAppState, ResubscribeParam &aInParam, uint32_t &aOutIntervalMsec) typedef
void(*
Callback to fetch the interval of time to wait before the next resubscribe.

Public static functions
DefaultEventHandler(EventID aEvent, const InEventParam & aInParam, OutEventParam & aOutParam)
void
DefaultResubscribePolicyCallback(void *const aAppState, ResubscribeParam & aInParam, uint32_t & aOutIntervalMsec)
void
The default policy implementation will pick a random timeslot with millisecond resolution over an ever increasing window, following a fibonacci sequence upto WDM_RESUBSCRIBE_MAX_FIBONACCI_STEP_INDEX.

Public functions
AbortSubscription(void)
void
Abort the subscription.
DisableResubscribe(void)
void
Disable the resubscribe mechanism.
DiscardUpdates()
void
Tells the SubscriptionClient to empty the set of TraitPaths pending to be updated and abort the update request that is in progress, if any.
EnableResubscribe(ResubscribePolicyCallback aCallback)
void
Enable automatic resubscribes.
EndSubscription(void)
End the subscription.
FlushUpdate()
Signals that the application has finished mutating all TraitUpdatableDataSinks.
FlushUpdate(bool aForce)
Free(void)
void
Free this SubscriptionClient object.
GetBinding(void) const
GetLivenessTimeoutMsec(void) const
uint32_t
GetPeerNodeId(void) const
uint64_t
GetSubscriptionId(uint64_t *const apSubscriptionId)
IndicateActivity(void)
void
InitiateCounterSubscription(const uint32_t aLivenessTimeoutSec)
void
InitiateSubscription(void)
void
Configure the SubscriptionClient as an initiator (as opposed to a counter-subscriber) and bring the subscription up if it is not.
IsAborting()
bool
IsEstablished()
bool
IsEstablishedIdle()
bool
IsFree()
bool
IsInProgressOrEstablished()
bool
IsInResubscribeHoldoff()
bool
IsRetryEnabled()
bool
IsUpdatePendingOrInProgress()
bool
LockUpdateMutex(void)
void
OnCatalogChanged()
void
This method should be called when the TraitDataSink catalog has been modified.
ResetResubscribe(void)
void
Kick the resubscribe mechanism.
SetLivenessTimeoutMsec(uint32_t val)
void
SetUpdated(TraitUpdatableDataSink *aDataSink, PropertyPathHandle aPropertyHandle, bool aIsConditional)
SuspendUpdateRetries()
void
Tells the SubscriptionClient to stop retrying update requests.
UnlockUpdateMutex(void)
void

Structs
nl::Weave::Profiles::DataManagement_Current::SubscriptionClient::LastObservedEvent
nl::Weave::Profiles::DataManagement_Current::SubscriptionClient::ResubscribeParam

Unions
nl::Weave::Profiles::DataManagement_Current::SubscriptionClient::InEventParam
nl::Weave::Profiles::DataManagement_Current::SubscriptionClient::OutEventParam

Public types

@123

 @123

EventCallback

void(* EventCallback)(void *const aAppState, EventID aEvent, const InEventParam &aInParam, OutEventParam &aOutParam)

Callback to pass subscription events to application.

Details
Parameters
[in] aAppState
App state pointer set during initialization of the SubscriptionClient.
[in] aEvent
Indicates which event is happening
[in] aInParam
Struct with additional details about the event
[out] aOutParam
Information passed back by the application

EventID

 EventID
Properties
kEvent_OnEventStreamReceived

Generated when the SubscriptionEngine encountes an event stream within the NotificationRequest message.

The application may call EndSubscription(), AbortSubscription(), or Free() at this point.

kEvent_OnExchangeStart

Generated after the binding has been prepared and ExchangeContext has been set up but prior to any messages being sent.

This is the last chance for an application to adjust ExchangeContext settings, mEC is valid and can be tuned for timeout settings. The application must not touch other fields in the client and must not close the ExchangeContext.

kEvent_OnNoMorePendingUpdates

An event denoting that all paths in the update set have been processed by the peer, and no more paths need to be updated.

kEvent_OnNotificationProcessed

Generated when the SubscriptionEngine finishes proceesing a NotificationRequest message.

The application may call EndSubscription(), AbortSubscription(), or Free() at this point.

kEvent_OnNotificationRequest

Generated on a receit of a NotificationRequest.

The application may call EndSubscription(), AbortSubscription(), or Free() at this point.

kEvent_OnSubscribeRequestPrepareNeeded

Sent when the engine is ready to send the SubscribeRequest.

The application is expected to fill in the paths that it wants to subscribe to.

kEvent_OnSubscriptionActivity

An event indicating subscription activity.

It is generated whenever the client receives an indication on subscription activity; this includes successful subscription establishment, a reception of a NotificationRequest or a receipt of a status report in response to the SubscribeConfirm message.

kEvent_OnSubscriptionEstablished

Generated upon a successful establishment of the subscription.

The application may call EndSubscription(), AbortSubscription(), or Free() at this point.

kEvent_OnSubscriptionTerminated

Marks the end of this subscription.

The parameters sent to the nl::Weave::Profiles::DataManagement_Current::SubscriptionClient::EventCallback will indicate whether a resubscribe will be automatically attempted.

If no retry will be attempted, the state of the client will be Aborted. No more downcalls into the application will be made. Otherwise, the state will not be aborted or freed. Downcalls will continue.

The application may call AbortSubscription() or Free() in this state.

The parameters sent will also include an error code indicating the reason for ending the subscription. There are no guarantees for the state of ::nl::Weave::Profiles::DataManagement_Current::SubscriptionClient::mBinding or ::nl::Weave::Profiles::DataManagement_Current::SubscriptionClient::mEC.

The subscription could have been terminated for a number of reasons (WRM ACK missing, ExchangeContext allocation failure, response timeout,...) Some possible error codes generated by the client:

Error code Meaning
WEAVE_ERROR_INVALID_MESSAGE_TYPE An unrecognized message is received.
WEAVE_ERROR_TIMEOUT An ack is not received or a liveness check fails.
WEAVE_ERROR_INCORRECT_STATE Messages are received in an unexpected state.
WEAVE_ERROR_STATUS_REPORT_RECEIVED A status report is received.
WEAVE_ERROR_INVALID_ARGUMENT Subscribe request fields are invalid.

kEvent_OnUpdateComplete

An event denoting the completion of the update.

Event parameters will indicate whether the update of a specific trait path has succeeded or failed.

ResubscribePolicyCallback

void(* ResubscribePolicyCallback)(void *const aAppState, ResubscribeParam &aInParam, uint32_t &aOutIntervalMsec)

Callback to fetch the interval of time to wait before the next resubscribe.

Applications are allowed to abort/free in this function if they've decided to give up on resubscribing.

Details
Parameters
[in] aAppState
App state pointer set during initialization of the SubscriptionClient.
[in] aInParam
Struct with additional details about the retry
[out] aOutIntervalMsec
Time in milliseconds to wait before next retry

Public static functions

DefaultEventHandler

void DefaultEventHandler(
  EventID aEvent,
  const InEventParam & aInParam,
  OutEventParam & aOutParam
)

DefaultResubscribePolicyCallback

void DefaultResubscribePolicyCallback(
  void *const aAppState,
  ResubscribeParam & aInParam,
  uint32_t & aOutIntervalMsec
)

The default policy implementation will pick a random timeslot with millisecond resolution over an ever increasing window, following a fibonacci sequence upto WDM_RESUBSCRIBE_MAX_FIBONACCI_STEP_INDEX.

Average of the randomized wait time past the WDM_RESUBSCRIBE_MAX_FIBONACCI_STEP_INDEX will be around one hour. When the retry count resets to 0, the sequence starts from the beginning again.

Public functions

AbortSubscription

void AbortSubscription(
  void
)

Abort the subscription.

Immediately stop accepting all traffic associated with the subscription, and release all underlying communication resources. The SubscriptionClient object itself remains valid and may be used again.

DisableResubscribe

void DisableResubscribe(
  void
)

Disable the resubscribe mechanism.

This will abort if a resubscribe was pending.

DiscardUpdates

void DiscardUpdates()

Tells the SubscriptionClient to empty the set of TraitPaths pending to be updated and abort the update request that is in progress, if any.

This method can be invoked from any callback.

EnableResubscribe

void EnableResubscribe(
  ResubscribePolicyCallback aCallback
)

Enable automatic resubscribes.

Attach a callback to specify the next retry time on failure.

Details
Parameters
[in] aCallback
Optional callback to fetch the amount of time to wait before retrying after a failure. If NULL use a default policy.

EndSubscription

WEAVE_ERROR EndSubscription(
  void
)

End the subscription.

When WDM_ENABLE_SUBSCRIPTION_CANCEL compile-time option is enabled, gracefully end the subscription by sending a CancelRequest to the peer. The resources associated with the subscription are freed on response from the peer or on timeout. When the option is disabled, the call is equivalent to AbortSubscription().

FlushUpdate

WEAVE_ERROR FlushUpdate()

Signals that the application has finished mutating all TraitUpdatableDataSinks.

Unless a previous update exchange is in progress, the client will take all data marked as updated and send it to the responder in one update request. This method can be called from any thread.

Details
Parameters
[in] aForce
If true, causes the update to be sent immediately even if a retry has been scheduled in the future. This parameter is considered false by default.
Returns
WEAVE_NO_ERROR in case of success; other WEAVE_ERROR codes in case of failure.

FlushUpdate

WEAVE_ERROR FlushUpdate(
  bool aForce
)

Free

void Free(
  void
)

Free this SubscriptionClient object.

Calls AbortSubscription() if necessary and releases the refcount on this SubscriptionClient object. Under correct usage, this should enable the object to be returned to the object pool

GetBinding

Binding * GetBinding(
  void
) const

GetLivenessTimeoutMsec

uint32_t GetLivenessTimeoutMsec(
  void
) const

GetPeerNodeId

uint64_t GetPeerNodeId(
  void
) const

GetSubscriptionId

WEAVE_ERROR GetSubscriptionId(
  uint64_t *const apSubscriptionId
)

IndicateActivity

void IndicateActivity(
  void
)

InitiateCounterSubscription

void InitiateCounterSubscription(
  const uint32_t aLivenessTimeoutSec
)

InitiateSubscription

void InitiateSubscription(
  void
)

Configure the SubscriptionClient as an initiator (as opposed to a counter-subscriber) and bring the subscription up if it is not.

IsAborting

bool IsAborting()

IsEstablished

bool IsEstablished()

IsEstablishedIdle

bool IsEstablishedIdle()

IsFree

bool IsFree()

IsInProgressOrEstablished

bool IsInProgressOrEstablished()

IsInResubscribeHoldoff

bool IsInResubscribeHoldoff()

IsRetryEnabled

bool IsRetryEnabled()

IsUpdatePendingOrInProgress

bool IsUpdatePendingOrInProgress()

LockUpdateMutex

void LockUpdateMutex(
  void
)

OnCatalogChanged

void OnCatalogChanged()

This method should be called when the TraitDataSink catalog has been modified.

ResetResubscribe

void ResetResubscribe(
  void
)

Kick the resubscribe mechanism.

This will initiate an immediate retry

SetLivenessTimeoutMsec

void SetLivenessTimeoutMsec(
  uint32_t val
)

SetUpdated

WEAVE_ERROR SetUpdated(
  TraitUpdatableDataSink *aDataSink,
  PropertyPathHandle aPropertyHandle,
  bool aIsConditional
)

SuspendUpdateRetries

void SuspendUpdateRetries()

Tells the SubscriptionClient to stop retrying update requests.

Allows the application to suspend updates for a period of time without discarding all metadata. Updates and retries will be resumed when FlushUpdate is called. When called to suspend updates while an update is in-flight, the update is not canceled but in case it fails it will not be retried until FlushUpdate is called again.

UnlockUpdateMutex

void UnlockUpdateMutex(
  void
)