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

Summary

Public types
@124 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.
IsCanceling() const
bool
IsEstablished()
bool
IsEstablishedIdle()
bool
IsFree()
bool
IsInProgressOrEstablished()
bool
IsInResubscribeHoldoff()
bool
IsRetryEnabled()
bool
IsTerminated()
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

@124

 @124

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.

During the event handler call, the state of the client will be Terminated. If no retry will be attempted, the state of the client will transition to Initialized when the event handler returns. Otherwise, the state will transition to ResubscribeHoldoff and an attempt will be made to re-establish the subscription after the hold-off time.

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.

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.

Abort a client 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.

Terminates the client end of a subscription, without notifying the subscription publisher and without delivering an OnSubscriptionTerminated event to the application's event handler. If a mutual subscription exists, the counter subscription is terminated as well.

Upon calling AbortSubscription(), the SubscriptionClient object enters the Terminated state. Once the termination process completes, the object enters the Initialized state. Both transitions happen synchronously within the call to AbortSubscription().

After AbortSubscription() returns, the SubscriptionClient object may be used to initiate another subscription, or it may be freed by calling the Free() method.

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.

Gracefully end a client 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().

Gracefully terminates the client end of a subscription. If subscription cancel support is enabled, a SubscribeCancelRequest message is sent to the subscription publisher and the system awaits a reply before terminating the subscription; otherwise the subscription is immediately terminated in a similar manner to AbortSubscription(). If a mutual subscription exists, the counter subscription is terminated as well.

While awaiting a response to a SubscribeCancelRequest, the SubscriptionClient enters the Canceling state.

Once the termination process begins, the SubscriptionClient object enters the Terminated state and an OnSubscriptionTerminated event is delivered to the application's event handler. Note that, if cancel support is not enabled, the event handler may be called synchronously within the call to EndSubscription().

After the application's event handler returns, the SubscriptionClient object enters the Initialized state. At this point the SubscriptionClient object may be used to initiate another subscription, or it may be freed by calling the Free() method.

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.

Free a 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

Frees the SubscriptionClient object. If a subscription is active or in-progress, the subscription is immediately terminated in a similar manner to calling AbortSubscription(). If any update requests are in progress, they are similarly aborted.

The application is responsible for calling Free() exactly once during the lifetime of a SubscriptionClient object. After Free() is called, no further references should be made to the object.

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.

IsCanceling

bool IsCanceling() const

IsEstablished

bool IsEstablished()

IsEstablishedIdle

bool IsEstablishedIdle()

IsFree

bool IsFree()

IsInProgressOrEstablished

bool IsInProgressOrEstablished()

IsInResubscribeHoldoff

bool IsInResubscribeHoldoff()

IsRetryEnabled

bool IsRetryEnabled()

IsTerminated

bool IsTerminated()

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
)