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
デフォルトのポリシー実装では、WDM_RESUBSCRIBE_MAX_FIBONACCI_STEP_INDEX までのフィボナッチ シーケンスに続いて、ミリ秒単位で解像度が増加するランダムなタイムスロットが選択されます。

パブリック関数
AbortSubscription(void)
void
サブスクリプションを中止します。
ClearUpdated(TraitUpdatableDataSink *aDataSink, PropertyPathHandle aPropertyHandle)
DisableResubscribe(void)
void
再度定期購入メカニズムを無効にします。
DiscardUpdates()
void
SubscriptionClient に、更新待ちの TraitPath のセットを空にして、進行中の更新リクエストがある場合は中止します。
EnableResubscribe(ResubscribePolicyCallback aCallback)
void
自動再登録を有効にします。
EndSubscription(void)
サブスクリプションを終了します。
FlushUpdate()
アプリケーションがすべての TraitUpdatableDataSinks のミューテーションを終了したことを示します。
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

イベント コールバック

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

定期購入イベントをアプリに渡すコールバック。

詳細
パラメータ
[in] aAppState
SubscriptionClient の初期化中に設定されたアプリの状態ポインタ。
[in] aEvent
発生しているイベントを示します
[in] aInParam
イベントに関する追加情報を含む構造体を作成する
[out] aOutParam
アプリケーションから返される情報

EventID

 EventID
Properties
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（デフォルトの ResubscribePolicyCallback）

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

デフォルトのポリシー実装では、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 に、更新待ちの TraitPath のセットを空にして、進行中の更新リクエストがある場合は中止します。

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

再登録

void EnableResubscribe(
  ResubscribePolicyCallback aCallback
)

自動再登録を有効にします。

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

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

エンド サブスクリプション

WEAVE_ERROR EndSubscription(
  void
)

サブスクリプションを終了します。

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

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

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

SubscribeCancelRequest へのレスポンスを待っている間、SubscriptionClient は Canceling 状態になります。

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

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

フラッシュ更新

WEAVE_ERROR FlushUpdate()

アプリケーションがすべての TraitUpdatableDataSinks のミューテーションを終了したことを示します。

前回の更新のエクスチェンジが進行中でない限り、クライアントは更新済みとしてマークされたすべてのデータを取得し、1 つの更新リクエストで応答者に送信します。このメソッドは任意のスレッドから呼び出すことができます。

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

フラッシュ更新

WEAVE_ERROR FlushUpdate(
  bool aForce
)

無料

void Free(
  void
)

この SubscriptionClient オブジェクトを削除します。

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

必要に応じて AbortSubscription() を呼び出し、この SubscriptionClient オブジェクトの参照値を解放します。正しい使用状況では、これによりオブジェクトがオブジェクト プールに返されるようになります

SubscriptionClient オブジェクトを解放します。定期購入がアクティブまたは進行中の場合、定期購入は AbortSubscription() の呼び出しと同様にすぐに終了します。更新リクエストが進行中の場合も同様に中止されます。

アプリケーションは、SubscriptionClient オブジェクトの有効期間内に 1 回だけ Free() を呼び出します。Free() が呼び出された後は、オブジェクトに対してその他の参照を作成しないでください。

バインディングの取得

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
)

CounterSubscription を開始

void InitiateCounterSubscription(
  const uint32_t aLivenessTimeoutSec
)

定期購入を開始する

void InitiateSubscription(
  void
)

SubscriptionClient をイニシエータとして（反サブスクライバではなく）構成し、サブスクリプションを起動していない場合は起動する。

キャンセル中

bool IsCanceling() const

確立済み

bool IsEstablished()

IsEstablishedIdle

bool IsEstablishedIdle()

無料

bool IsFree()

IsInProgressOrEstablished

bool IsInProgressOrEstablished()

IsInResubscribeHoldoff

bool IsInResubscribeHoldoff()

IsRetryEnabled（再試行の有効化）

bool IsRetryEnabled()

終了

bool IsTerminated()

IsUpdatePendingOrInProgress

bool IsUpdatePendingOrInProgress()

LockUpdate ミュート x

void LockUpdateMutex(
  void
)

OnCatalogChanged

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 が再度呼び出されるまで再試行されません。

UnlockUpdate ミュート x

void UnlockUpdateMutex(
  void
)