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

总结

公共类型

@130 枚举
EventCallback)(void *const aAppState, EventID aEvent, const InEventParam &aInParam, OutEventParam &aOutParam) typedef
void(*
用于将订阅事件传递给应用的回调。
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
}
枚举
ResubscribePolicyCallback)(void *const aAppState, ResubscribeParam &aInParam, uint32_t &aOutIntervalMsec) typedef
void(*
用于提取在下一次重新订阅之前等待的时间间隔的回调。

公共静态函数

DefaultEventHandler(EventID aEvent, const InEventParam & aInParam, OutEventParam & aOutParam)
void
DefaultResubscribePolicyCallback(void *const aAppState, ResubscribeParam & aInParam, uint32_t & aOutIntervalMsec)
void
默认政策实现会遵循不断递增的时间范围(按照 fibonacci 序列不超过 WDM_RESUBSCRIBE_MAX_FIBONACCI_STEP_INDEX)的随机时间时段(毫秒)。

公共函数

AbortSubscription(void)
void
取消订阅。
ClearUpdated(TraitUpdatableDataSink *aDataSink, PropertyPathHandle aPropertyHandle)
DisableResubscribe(void)
void
停用重新订阅机制。
DiscardUpdates()
void
指示 SubscriptionClient 清空一系列待更新的 TraitPaths,并中止正在进行的更新请求(如果有)。
EnableResubscribe(ResubscribePolicyCallback aCallback)
void
启用自动重新订阅功能。
EndSubscription(void)
结束订阅。
FlushUpdate()
表明应用已完成所有 TraitUpdatableDataSink 的转变。
FlushUpdate(bool aForce)
Free(void)
void
释放此 SubscriptionClient 对象。
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
SubscriptionClient 配置为发起者(而不是计数器订阅者),并在未订阅的情况下启动订阅。
IsCanceling() const
bool
IsEstablished()
bool
IsEstablishedIdle()
bool
IsFree()
bool
IsInProgressOrEstablished()
bool
IsInResubscribeHoldoff()
bool
IsRetryEnabled()
bool
IsTerminated()
bool
IsUpdatePendingOrInProgress()
bool
LockUpdateMutex(void)
void
OnCatalogChanged()
void
修改 TraitDataSink 目录时,应调用此方法。
ResetResubscribe(void)
void
启用重新订阅机制。
SetLivenessTimeoutMsec(uint32_t val)
void
SetUpdated(TraitUpdatableDataSink *aDataSink, PropertyPathHandle aPropertyHandle, bool aIsConditional)
SuspendUpdateRetries()
void
指示 SubscriptionClient 停止重试更新请求。
UnlockUpdateMutex(void)
void

结构体

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

联合

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

公共类型

@130

 @130

EventCallback

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

用于将订阅事件传递给应用的回调。

详情
参数
[in] aAppState
SubscriptionClient 的初始化过程中设置的应用状态指针。
[in] aEvent
指示所发生的事件
[in] aInParam
使用与活动相关的其他细节构造结构
[out] aOutParam
应用传回的信息

EventID

 EventID
属性
kEvent_OnEventStreamReceived

SubscriptionEngine 计算 NotificationRequest 消息中的事件流时生成。

此时,应用可以调用 EndSubscription()AbortSubscription()Free()

kEvent_OnExchangeStart

在绑定准备好且 ExchangeContext 设置完毕之后、系统发送任何邮件之前生成。

这是应用调整 ExchangeContext 设置的最后机会。mEC 是有效的,可以调整超时设置。应用不得触摸客户端中的其他字段,也不得关闭 ExchangeContext

kEvent_OnNoMorePendingUpdates

一个事件,表示更新集中的所有路径均由对等方处理,无需再更新路径。

kEvent_OnNotificationProcessed

SubscriptionEngine 完成处理 NotificationRequest 消息时生成。

此时,应用可以调用 EndSubscription()AbortSubscription()Free()

kEvent_OnNotificationRequest

在生成 NotificationRequest 时生成。

此时,应用可以调用 EndSubscription()AbortSubscription()Free()

kEvent_OnSubscribeRequestPrepareNeeded

当引擎准备好发送 订阅者请求时发送。

应用应填写其想要订阅的路径。

kEvent_OnSubscriptionActivity

指示订阅活动的事件。

每当客户端收到有关订阅活动的指示时,系统便会生成此事件。其中包括:成功创建订阅、收到 NotificationRequest 或为了响应 SubscriptionConfirm 消息而收到状态报告。

kEvent_OnSubscriptionEstablished

成功创建订阅时生成。

此时,应用可以调用 EndSubscription()AbortSubscription()Free()

kEvent_OnSubscriptionTerminated

标记此次订阅的结束日期。

发送至 nl::Weave::Profiles::DataManagement_Current::SubscriptionClient::EventCallback 的参数将指示是否自动尝试重新订阅。

在事件处理脚本调用期间,客户端状态为 Terminated。如果不尝试重试,则事件处理程序返回时,客户端状态将转换为 Initialized。否则,该状态将转换为 ResubscribeHoldoff,并尝试在延迟期结束后重新订阅。

应用可以在此状态下调用 AbortSubscription()Free()

发送的参数还会包含错误代码,以说明终止订阅的原因。

订阅可能因多种原因而被终止(WRM ACK 缺失、ExchangeContext 分配失败、响应超时等)客户端可能生成的一些错误代码:

错误代码 含义
WEAVE_ERROR_INVALID_MESSAGE_TYPE 收到无法识别的消息。
WEAVE_ERROR_TIMEOUT 未收到确认消息或活跃性检查失败。
WEAVE_ERROR_INCORRECT_STATE 邮件以非预期状态接收。
WEAVE_ERROR_STATUS_REPORT_RECEIVED 收到状态报告。
WEAVE_ERROR_INVALID_ ARGUMENT 订阅请求字段无效。

kEvent_OnUpdateComplete

一个指明更新完成的事件。

事件参数将指明特定特征路径的更新是成功还是失败。

ResubscribePolicyCallback

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

用于提取在下一次重新订阅之前等待的时间间隔的回调。

如果应用决定放弃重新订阅,则可在此函数中中止/释放。

详情
参数
[in] aAppState
SubscriptionClient 的初始化过程中设置的应用状态指针。
[in] aInParam
使用有关重试的更多详情构建结构
[out] aOutIntervalMsec
下次重试前等待的时间(以毫秒为单位)

公共静态函数

DefaultEventHandler 类中的方法

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

DefaultResubscribePolicyCallback

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

默认政策实现会遵循不断递增的时间范围(按照 fibonacci 序列不超过 WDM_RESUBSCRIBE_MAX_FIBONACCI_STEP_INDEX)的随机时间时段(毫秒)。

WDM_RESUBSCRIBE_MAX_FIBONACCI_STEP_INDEX 之后的随机等待时间平均值大约为 1 小时。当重试计数重置为 0 时,将再次从头开始计数。

公共函数

中止订阅

void AbortSubscription(
  void
)

取消订阅。

取消客户端订阅。

立即停止接受与订阅相关的所有流量,并释放所有底层通信资源。SubscriptionClient 对象本身仍然有效,可再次使用。

终止订阅的客户端,而不通知订阅发布商,也不向应用的事件处理程序传递 OnSubscriptionTerminated 事件。如果双方订阅都存在,计数器订阅也会终止。

调用 AbortSubscription() 后,SubscriptionClient 对象会进入 Terminated 状态。终止过程完成后,对象将进入 Initialized 状态。这两个转换在调用 AbortSubscription() 期间同步发生。

AbortSubscription() 返回后,SubscriptionClient 对象可用于发起其他订阅,或者通过调用 Free() 方法进行释放。

已更新

WEAVE_ERROR ClearUpdated(
  TraitUpdatableDataSink *aDataSink,
  PropertyPathHandle aPropertyHandle
)

停用重新订阅

void DisableResubscribe(
  void
)

停用重新订阅机制。

如果重新订阅正在等待处理,则会取消。

舍弃更新

void DiscardUpdates()

指示 SubscriptionClient 清空一系列待更新的 TraitPaths,并中止正在进行的更新请求(如果有)。

可从任何回调调用该方法。

启用重新订阅

void EnableResubscribe(
  ResubscribePolicyCallback aCallback
)

启用自动重新订阅功能。

附加回调以指定失败后的下一次重试时间。

详情
参数
[in] aCallback
用于提取失败后重试前等待的可选回调函数。如果值为 NULL,请使用默认政策。

结束订阅

WEAVE_ERROR EndSubscription(
  void
)

结束订阅。

正常终止客户订阅。

启用 WDM_ENABLE_SUBSCRIPTION_CANCEL 编译时选项后,向对等端发送 CancelRequest 妥善地终止订阅。与订阅关联的资源会在来自对等方的响应或超时时释放。停用该选项后,调用相当于 AbortSubscription()

正常终止订阅的客户端。如果启用了订阅取消支持,系统会向订阅发布者发送 SubscriptionCancelRequest 消息,然后系统会在终止订阅之前等待回复;否则,系统会以与 AbortSubscription() 类似的方式立即终止订阅。如果存在共同订阅,则计数器订阅也会终止。

在等待对 CancelCancelRequest 的响应时,SubscriptionClient 会进入 Canceling 状态。

终止进程开始后,SubscriptionClient 对象将进入 Terminated 状态,并且 OnSubscriptionTerminated 事件会传递到应用的事件处理程序。请注意,如果未启用取消支持,则在 EndSubscription() 调用中同步调用事件处理程序。

应用事件处理脚本返回后,SubscriptionClient 对象会进入 Initialized 状态。此时,SubscriptionClient 对象可用于发起其他订阅,或者通过调用 Free() 方法进行释放。

刷新

WEAVE_ERROR FlushUpdate()

表明应用已完成所有 TraitUpdatableDataSink 的转变。

除非之前的更新交换正在进行中,否则客户端会获取一个标记为“已更新”的所有数据,并在一个更新请求中将其发送给响应者。该方法可从任何线程调用。

详情
参数
[in] aForce
如果为 true,则即使安排了未来的重试,也会立即发送更新。此参数默认被视为 false。
返回值
WEAVE_NO_ERROR(如果成功);其他 WEAVE_ERROR 代码(如果失败)。

刷新

WEAVE_ERROR FlushUpdate(
  bool aForce
)

免费

void Free(
  void
)

释放此 SubscriptionClient 对象。

释放一个 SubscriptionClient 对象。

根据需要调用 AbortSubscription() 并释放对此 SubscriptionClient 对象的引用。在正确使用的情况下,这应该会使对象返回到对象池

释放 SubscriptionClient 对象。如果订阅处于有效状态或正在进行中,订阅会立即终止,其调用方式与调用 AbortSubscription() 类似。如果有任何更新请求正在进行,同样会中止。

应用负责在 SubscriptionClient 对象的生命周期内调用一次 Free()。调用 Free() 之后,就不应再对该对象进行引用。

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
)

指标活动

void IndicateActivity(
  void
)

InitiateCounterSubscription

void InitiateCounterSubscription(
  const uint32_t aLivenessTimeoutSec
)

启动订阅

void InitiateSubscription(
  void
)

SubscriptionClient 配置为发起者(而不是计数器订阅者),并在未订阅的情况下启动订阅。

正在取消

bool IsCanceling() const 

已建立

bool IsEstablished()

已建立空闲策略

bool IsEstablishedIdle()

免费

bool IsFree()

正在进行或已建立

bool IsInProgressOrEstablished()

重新订阅暂停订阅

bool IsInResubscribeHoldoff()

已重试

bool IsRetryEnabled()

已终止

bool IsTerminated()

IsUpdatePendingOrInProgress

bool IsUpdatePendingOrInProgress()

锁定更新静音

void LockUpdateMutex(
  void
)

已更改的目录

void OnCatalogChanged()

修改 TraitDataSink 目录时,应调用此方法。

重置重新订阅

void ResetResubscribe(
  void
)

启用重新订阅机制。

此操作会立即重试

SetLivenessTimeoutMsec

void SetLivenessTimeoutMsec(
  uint32_t val
)

已更新

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

SuspendUpdateRetries(挂起更新重试)

void SuspendUpdateRetries()

指示 SubscriptionClient 停止重试更新请求。

允许应用暂停更新一段时间,而不舍弃所有元数据。调用 FlushUpdate 时,将恢复更新和重试。如果在更新正在传输时调用以暂停更新,该更新不会取消,但如果更新失败,则不会重试,直到再次调用 FlushUpdate 为止。

解锁更新静音

void UnlockUpdateMutex(
  void
)