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

概要

パブリック タイプ

@130 enum
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
}
enum
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
デフォルトのポリシー実装では、WDM_RESUBSCRIBE_MAX_FIBONACCI_STEP_INDEX までのフィボナッチ数列に従って、ミリ秒単位の精度のタイムスロットがますます増加する中、ランダムに選択されます。

パブリック関数

AbortSubscription(void)
void
定期購入を中止します。
ClearUpdated(TraitUpdatableDataSink *aDataSink, PropertyPathHandle aPropertyHandle)
DisableResubscribe(void)
void
再度定期購入するメカニズムを無効にする。
DiscardUpdates()
void
更新が保留中の TraitPath のセットを空にし、進行中の更新リクエストがある場合は中止するよう SubscriptionClient に指示します。
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

エンジンで SubscribeRequest を送信する準備が整うと送信されます。

アプリケーションは、サブスクライブしたいパスを埋めることが想定されています。

kEvent_OnSubscriptionActivity

購読のアクティビティを示すイベント。

クライアントが購読アクティビティの通知を受け取るたびに生成されます。これには、購読の確立の成功、NotificationRequest の受信、SubscribeConfirm メッセージに対するステータス レポートの受信が含まれます。

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
)

デフォルトのポリシー実装では、WDM_RESUBSCRIBE_MAX_FIBONACCI_STEP_INDEX までのフィボナッチ数列に従って、ミリ秒単位の精度のタイムスロットがますます増加する中、ランダムに選択されます。

ランダム化された WDM_RESUBSCRIBE_MAX_FIBONACCI_STEP_INDEX 以降の待ち時間の平均は、約 1 時間になります。再試行回数が 0 にリセットされると、シーケンスは最初から開始されます。

パブリック関数

AbortSubscription

void AbortSubscription(
  void
)

定期購入を中止します。

クライアントのサブスクリプションを中止します。

定期購入に関連するすべてのトラフィックの受け入れを直ちに停止し、基盤となるすべての通信リソースを解放します。SubscriptionClient オブジェクト自体は有効なままで、再度使用できます。

定期購読のニュース メディアに通知せずに、またアプリケーションのイベント ハンドラに OnSubscriptionTerminated イベントを配信せずに、クライアントによる定期購読の終了。相互サブスクリプションが存在する場合、カウンタ サブスクリプションも同様に終了します。

AbortSubscription() を呼び出すと、SubscriptionClient オブジェクトは Terminated 状態になります。終了プロセスが完了すると、オブジェクトは Initialized 状態になります。どちらの移行も、AbortSubscription() の呼び出し内で同期的に行われます。

AbortSubscription() が戻った後、SubscriptionClient オブジェクトを使用して別のサブスクリプションを開始するか、Free() メソッドを呼び出して解放します。

ClearUpdated

WEAVE_ERROR ClearUpdated(
  TraitUpdatableDataSink *aDataSink,
  PropertyPathHandle aPropertyHandle
)

DisableResubscribe

void DisableResubscribe(
  void
)

再度定期購入するメカニズムを無効にする。

再度定期購入が保留されていた場合、定期購入は中止されます。

DiscardUpdates

void DiscardUpdates()

更新が保留中の TraitPath のセットを空にし、進行中の更新リクエストがある場合は中止するよう SubscriptionClient に指示します。

このメソッドは、どのコールバックからでも呼び出すことができます。

EnableResubscribe

void EnableResubscribe(
  ResubscribePolicyCallback aCallback
)

再度定期購入を自動的に有効にする。

失敗時の次回の再試行時間を指定するコールバックをアタッチします。

詳細
パラメータ
[in] aCallback
失敗した後、再試行するまでの待機時間を取得するオプションのコールバック。NULL の場合はデフォルトのポリシーを使用します。

EndSubscription

WEAVE_ERROR EndSubscription(
  void
)

定期購入を終了します。

クライアントのサブスクリプションを正常に終了します。

WDM_ENABLE_SUBSCRIPTION_CANCEL コンパイル時オプションが有効になっている場合、CancelRequest をピアに送信してサブスクリプションを正常に終了します。サブスクリプションに関連付けられているリソースは、ピアからのレスポンス時またはタイムアウト時に解放されます。このオプションが無効になっている場合、呼び出しは AbortSubscription() と同じです。

クライアント側のサブスクリプションを正常に終了します。定期購入の解約のサポートが有効であれば、SubscribeCancelRequest メッセージが定期購読のパブリッシャーに送信され、システムは応答を待機してから登録を終了します。それ以外の場合、定期購入は AbortSubscription() と同様の方法で直ちに終了します。相互のサブスクリプションが存在する場合も、カウンタ サブスクリプションも終了します。

SubscribeCancelRequest への応答を待っている間、SubscriptionClientCanceling 状態になります。

終了プロセスが開始されると、SubscriptionClient オブジェクトが Terminated 状態になり、OnSubscriptionTerminated イベントがアプリのイベント ハンドラに送られます。キャンセルのサポートが有効でない場合、EndSubscription() の呼び出し内でイベント ハンドラが同期的に呼び出される場合があります。

アプリケーションのイベント ハンドラが戻ると、SubscriptionClient オブジェクトは Initialized 状態になります。この時点で、SubscriptionClient オブジェクトを使用して別のサブスクリプションを開始するか、Free() メソッドを呼び出して解放できます。

FlushUpdate

WEAVE_ERROR FlushUpdate()

アプリケーションがすべての TraitUpdatableDataSink の変更を終了したことを通知します。

以前の更新交換が進行中である場合を除き、クライアントは、更新済みとしてマークされたデータをすべて取得し、1 つの更新リクエストでレスポンダーに送信します。このメソッドは、どのスレッドからでも呼び出すことができます。

詳細
パラメータ
[in] aForce
true の場合、再試行がスケジュール設定されていても、更新はすぐに送信されます。このパラメータは、デフォルトでは false とみなされます。
戻り値
成功した場合は WEAVE_NO_ERROR、失敗した場合は他の WEAVE_ERROR コードです。

FlushUpdate

WEAVE_ERROR FlushUpdate(
  bool aForce
)

無料

void Free(
  void
)

この SubscriptionClient オブジェクトを解放します。

SubscriptionClient オブジェクトを解放します。

必要に応じて AbortSubscription() を呼び出し、この SubscriptionClient オブジェクトの参照カウントを解放します。正しく使用すれば、オブジェクトをオブジェクト プールに返すことができます。

SubscriptionClient オブジェクトを解放します。サブスクリプションがアクティブまたは進行中の場合、AbortSubscription() の呼び出しと同様の方法でサブスクリプションが直ちに終了します。進行中の更新リクエストがある場合、同様に中止されます。

アプリケーションは、SubscriptionClient オブジェクトの有効期間中に Free() を 1 回だけ呼び出します。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
)

IndicateActivity

void IndicateActivity(
  void
)

InitiateCounterSubscription

void InitiateCounterSubscription(
  const uint32_t aLivenessTimeoutSec
)

InitiateSubscription

void InitiateSubscription(
  void
)

SubscriptionClient を(カウンタ サブスクライバではなく)イニシエータとして設定し、イニシエータではない場合はサブスクリプションを起動します。

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()

このメソッドは、TraitDataSink カタログが変更されたときに呼び出す必要があります。

ResetResubscribe

void ResetResubscribe(
  void
)

再度定期購入を開始する。

これにより、すぐに再試行が開始されます

SetLivenessTimeoutMsec

void SetLivenessTimeoutMsec(
  uint32_t val
)

SetUpdated

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

SuspendUpdateRetries

void SuspendUpdateRetries()

更新リクエストの再試行を停止するように SubscriptionClient に指示します。

すべてのメタデータを破棄せずに一定期間、更新を一時停止することをアプリに許可します。FlushUpdate が呼び出されると更新と再試行が再開されます。更新の実行中に更新を一時停止するために呼び出された場合、更新はキャンセルされませんが、失敗した場合は FlushUpdate が再び呼び出されるまで再試行されません。

UnlockUpdateMutex

void UnlockUpdateMutex(
  void
)