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_REVIDEO_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()
يشير هذا المصطلح إلى إشارات إلى أنّ التطبيق قد انتهى من تغيير جميع 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

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

حدث يشير إلى نشاط الاشتراك.

يتم إنشاء هذا السجلّ عندما يتلقّى العميل إشارة حول نشاط الاشتراك، ويشمل ذلك عملية إنشاء اشتراك ناجحة أو تلقّي إشعار أو تلقّي تقرير الحالة ردًا على رسالة اشترِك.

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_REVIDEO_MAX_FIBONACCI_STEP_INDEX.

سيكون متوسط وقت الانتظار العشوائي بعد WDM_REMEDIA_MAX_FIBONACCI_STEP_INDEX ساعة واحدة تقريبًا. عند إعادة ضبط عدد المحاولات على 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()

لتوجيه SubscriptionClient إلى إفراغ مجموعة TraitPaths المعلَّقة المراد تحديثها وإلغاء طلب التحديث قيد التقدم، إن وجد.

يمكن استدعاء هذه الطريقة من أي معاودة اتصال.

EnableResubscribe

void EnableResubscribe(
  ResubscribePolicyCallback aCallback
)

تفعيل عمليات إعادة الاشتراك التلقائية

يُرجى إرفاق معاودة الاتصال لتحديد وقت إعادة المحاولة التالية عند تعذُّر الإجراء.

التفاصيل
المَعلمات
[in] aCallback
معاودة الاتصال اختيارية لمعرفة مدة الانتظار قبل إعادة المحاولة بعد حدوث إخفاق. وفي حال اختيار "قيمة فارغة"، استخدِم سياسة تلقائية.

EndSubscription

WEAVE_ERROR EndSubscription(
  void
)

إنهاء الاشتراك.

إنهاء اشتراك العميل بلطف.

عندما يتم تمكين خيار وقت التجميع WDM_ENABLE_SUBSCRIPTION_CANCEL، يمكنك إنهاء الاشتراك على نحو ملائم من خلال إرسال طلب الإلغاء إلى المستخدم النظير. ويتم تحرير الموارد المرتبطة بالاشتراك بناءً على استجابة من النظراء أو في مهلة محددة. وعندما يكون هذا الخيار غير مفعّل، يكون الاستدعاء مساويًا للدالة AbortSubscription().

ينهي العميل نهاية الاشتراك بلطف. إذا تم تفعيل دعم إلغاء الاشتراك، يتم إرسال رسالة SubscribeCancelRequest إلى ناشر الاشتراك وينتظر النظام ردًا قبل إنهاء الاشتراك، وإلا يتم إنهاء الاشتراك في الحال بطريقة تشبه AbortSubscription(). وفي حال وجود اشتراك متبادل، يتم أيضًا إنهاء الاشتراك المضاد أيضًا.

أثناء انتظار الرد على SubscribeCancelRequest، تدخل القيمة SubscriptionClient في الحالة Canceling.

بعد بدء عملية الإنهاء، يدخل العنصر SubscriptionClient الحالة Terminated ويتم تسليم حدث OnSubscriptionTerminated إلى معالج أحداث التطبيق. تجدر الإشارة إلى أنّه في حال لم يتم تفعيل دعم الإلغاء، قد يتم استدعاء معالج الحدث بشكل متزامن في استدعاء EndSubscription().

بعد إرجاع معالج أحداث التطبيق، يدخل العنصر SubscriptionClient الحالة Initialized. في هذه المرحلة، يمكن استخدام الكائن SubscriptionClient لبدء اشتراك آخر، أو يمكن تحريره من خلال استدعاء طريقة Free().

FlushUpdate

WEAVE_ERROR FlushUpdate()

يشير هذا المصطلح إلى إشارات إلى أنّ التطبيق قد انتهى من تغيير جميع TraitUpdatableDataSinks.

ما لم تكن عملية تبادل تحديثات سابقة قيد التقدم، سيأخذ العميل جميع البيانات التي تم وضع علامة عليها بأنّها معدّلة ويرسلها إلى المجيب في طلب تعديل واحد. يمكن استدعاء هذه الطريقة من أي سلسلة محادثات.

التفاصيل
المَعلمات
[in] aForce
إذا كانت صحيحة، تؤدي إلى إرسال التحديث فورًا حتى إذا تمت جدولة إعادة المحاولة في المستقبل. وتُعتبر هذه المَعلمة "خطأ" تلقائيًا.
المرتجعات
WEAVE_NO_ERROR في حالة النجاح، ورموز WEAVE_ERROR الأخرى في حالة الإخفاق.

FlushUpdate

WEAVE_ERROR FlushUpdate(
  bool aForce
)

مجاني

void Free(
  void
)

يجب إخلاء عنصر SubscriptionClient هذا.

حرِّر كائن SubscriptionClient.

يتم استدعاء AbortSubscription() إذا لزم الأمر وإطلاق عدد الزيارات في عنصر SubscriptionClient هذا. عند استخدام الإعداد الصحيح، يجب أن يؤدي ذلك إلى تفعيل إعادة الكائن إلى وحدة تجمع الكائنات

يؤدي إلى تحرير الكائن SubscriptionClient. إذا كان الاشتراك نشِطًا أو قيد التقدّم، يتم إنهاؤه على الفور بطريقة مشابهة لاستدعاء AbortSubscription(). وإذا كانت هناك أي طلبات تعديل قيد التقدّم، يتم إلغاء الاشتراك أيضًا.

يكون التطبيق مسؤولاً عن استدعاء Free() مرة واحدة بالضبط خلال عمر العنصر SubscriptionClient. بعد استدعاء 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
)