nl::Weave::Profiles::Echo_Next::WeaveEchoClient

#include <src/lib/profiles/echo/Next/WeaveEchoClient.h> 

Provides the ability to send Weave EchoRequest messages to a peer node and receive
the corresponding EchoResponse messages.

ملخّص

تنفِّذ فئة WeaveEchoClient جانب البدء من بروتوكول Weave Echo. على غرار بروتوكول فحص اتصال بروتوكول رسائل التحكّم في الإنترنت (ICMP)، يمكن استخدام بروتوكول Weave Echo لاختبار مدى حيوية عقدة Weave وإمكانية الوصول إليها.

يمكن للتطبيقات استخدام الفئة WeaveEchoClient لإرسال رسائل EchoRequest لمرة واحدة أو بشكل متكرر إلى عقدة مثلى يحددها كائن Binding. توجد فئة مقابلة للاستجابة لطلبات الارتداد (راجِع WeaveEchoServer).

ربط العملاء

يأخذ WeaveEchoClient كائن ربط Weave الذي يُستخدم لتحديد وإنشاء اتصال مع المستلم المقصود لطلبات الارتداد. يمكن أن يتم ضبط الربط وإعداده من خلال التطبيق قبل إعداد الكائن WeaveEchoClient أو إذا كان من الممكن تركه غير جاهز، وفي هذه الحالة يطلب WeaveEchoClient إعداد الربط عند الطلب (يمكنك الاطّلاع على Binding::RequestPrepare() للحصول على التفاصيل).

وسيتم أيضًا طلب إعداد الربط عند الطلب في حال تعذّر إكماله بعد الدخول إلى حالة "جاهز".

وضع تكرار الإرسال

يمكن استخدام الطريقة SendRepeating() لوضع WeaveEchoClient في وضع SendRepeating. في هذا الوضع، يرسل كائن العميل تسلسلاً متكررًا لرسائل EchoRequest إلى النظير في فاصل تم إعداده. يمكن إلغاء وضع تكرار الإرسال من خلال استدعاء الإجراء Stop().

البث المتعدد والبث

يمكن استخدام كائن WeaveEchoClient لإرسال طلبات EchoRequests إلى عدة مستلمين في وقت واحد من خلال تهيئة الكائن Binding باستخدام عنوان البث المتعدد IPv6 المناسب أو عنوان بث الشبكة المحلية لبروتوكول IPv4 (255.255.255.255). عندما يرصد كائن WeaveEchoClient عنوان بث متعدد أو نظير بث، يدخل تلقائيًا في وضع "الاستجابة المتعددة" عند إرسال EchoRequest.

في هذا الوضع، يستمر الكائن في الاستماع إلى جميع رسائل EchoResponse الواردة التي تصل إلى نفس التبادل وتسليمه. يظل العنصر في وضع "الاستجابة المتعددة" حتى: 1) يستدعي التطبيق Stop() أو Send()، أو 2) في وضع SendRepeating، ويحين وقت إرسال طلب آخر، أو 3) لا يتم تلقّي أي رد وتنتهي مهلة الاستلام.

أحداث واجهة برمجة التطبيقات

خلال فترة تشغيل الكائن WeaveEchoClient، سيتم استدعاء التطبيق لطلب إجراءات محدّدة أو عرض إشعارات بالأحداث المهمة. يتم إجراء طلبات الأحداث من واجهة برمجة التطبيقات هذه إلى دالة معاودة الاتصال التي تم ضبطها حاليًا في كائن العميل. باستثناء ما يتم ذكره، يمكن للتطبيقات تغيير حالة العميل أثناء استدعاء الحدث. ويُستثنى من ذلك الطريقة العامة للكائن Launchdown()، والتي قد لا يتم استدعاؤها أبدًا أثناء عملية معاودة الاتصال.

يتم تحديد أحداث واجهة برمجة التطبيقات التالية:

PreparePayload

إنّ WeaveEchoClient على وشك إنشاء رسالة EchoRequest ويطلب من التطبيق توفير حمولة. إذا رغب أحد التطبيقات، فقد يعرض حزمة PacketBuffer جديدة تحتوي على بيانات الحمولة. إذا لم يتعامل التطبيق مع هذا الحدث، سيتم تلقائيًا إرسال EchoRequest مع حمولة بيانات ذات طول صفري. قد لا يغيّر التطبيق حالة WeaveEchoClient أثناء معاودة الاتصال هذه.

RequestSent

تم إرسال رسالة EchoRequest إلى التطبيق المشابه.

ResponseReceived

تم تلقي رسالة EchoResponse من أحد الزملاء. تحتوي وسيطات الحدث على حمولة الاستجابة والمعلومات الوصفية حول رسالة الاستجابة.

CommunicationError

حدث خطأ أثناء إنشاء EchoRequest أو إرساله، أو أثناء انتظار رد. ومن الأمثلة على الأخطاء التي يمكن أن تحدث أثناء انتظار الرد: الأخطاء الرئيسية أو الإغلاق غير المتوقّع للاتصال. تحتوي وسيطات الحدث على سبب الخطأ.

ResponseTimeout

لم يتم تلقي استجابة EchoResponse في الوقت المخصص. يتم التحكّم في مهلة الاستجابة من خلال السمة defaultResponseTimeout في العنصر Binding.

RequestAborted

تم إلغاء عملية Echo Exchange قيد التقدم بسبب تقديم طلب لإرسال EchoRequest آخر قبل تلقي رد على الرسالة السابقة. وقد تنشأ هذه المشكلة في وضع SendRepeating عند حلول الوقت لإرسال EchoRequest التالي. قد يحدث ذلك أيضًا إذا كان التطبيق يستدعي Send() بعد إرسال EchoRequest ولكن قبل تلقي أي استجابة.

عندما يكون العنصر في وضع "الاستجابة المتعددة"، يتم منع الحدث في حال تلقّي رسالة EchoResponse واحدة على الأقل.

الشركات المصنّعة والمُصنّعة
WeaveEchoClient(void)

الأنواع العامة
EventCallback)(void *appState, EventType eventType, const InEventParam &inParam, OutEventParam &outParam) تعريف الكتابة
void(*
EventType{
  kEvent_PreparePayload = 1,
  kEvent_RequestSent = 2,
  kEvent_ResponseReceived = 3,
  kEvent_CommunicationError = 4,
  kEvent_ResponseTimeout = 5,
  kEvent_RequestAborted = 6,
  kEvent_DefaultCheck = 100
} 		تعداد
State{
  kState_NotInitialized = 0,
  kState_Idle = 1,
  kState_PreparingBinding = 2,
  kState_RequestInProgress = 3,
  kState_WaitingToSend = 4
} 		تعداد

السمات العامة
AppState
void *
يشير هذا المصطلح إلى مؤشر للبيانات الخاصة بالتطبيقات.

وظائف عامة
GetBinding(void) const
تعرض مؤشرًا إلى الكائن Binding المرتبط بـ WeaveEchoClient.
GetEventCallback(void) const
EventCallback
تعرض مؤشرًا إلى دالة استدعاء حدث واجهة برمجة التطبيقات التي تم ضبطها حاليًا على الكائن WeaveEchoClient.
GetState(void) const
استرِد الحالة الحالية للعنصر WeaveEchoClient.
Init(Binding *binding, EventCallback eventCallback, void *appState)
إعداد كائن WeaveEchoClient.
IsSendRrepeating() const
bool
تعرض القيمة true إذا كان الكائن WeaveEchoClient في وضع تكرار الإرسال حاليًا.
RequestInProgress() const
bool
تعرض القيمة "صحيح" إذا تم إرسال EchoRequest وكان الكائن WeaveEchoClient بانتظار الرد.
Send(void)
أرسِل رسالة EchoRequest إلى الزميل.
Send(PacketBuffer *payloadBuf)
أرسل رسالة EchoRequest إلى التطبيق المشابه مع حمولة محددة.
SendRepeating(uint32_t sendIntervalMS)
بدء إرسال تسلسل متكرر لرسائل EchoRequest إلى النظير.
SetEventCallback(EventCallback eventCallback)
void
تضبط هذه السياسة دالة استدعاء حدث واجهة برمجة التطبيقات في الكائن WeaveEchoClient.
Shutdown(void)
void
أوقِف كائن WeaveEchoClient الذي تم إعداده سابقًا.
Stop(void)
void
يؤدي هذا الخيار إلى إيقاف أي تبادل للصدى قيد التقدم وإلغاء وضع تكرار الإرسال.

الدوال الثابتة العامة
DefaultEventHandler(void *appState, EventType eventType, const InEventParam & inParam, OutEventParam & outParam)
void
المعالج التلقائي لأحداث واجهة برمجة التطبيقات WeaveEchoClient

بُنى
nl::Weave::Profiles::Echo_Next::WeaveEchoClient::InEventParam

أدخِل المَعلمات في حدث واجهة برمجة التطبيقات WeaveEchoClient.

nl::Weave::Profiles::Echo_Next::WeaveEchoClient::OutEventParam

إخراج المَعلمات لحدث واجهة برمجة التطبيقات WeaveEchoClient

الأنواع العامة

EventCallback

void(* EventCallback)(void *appState, EventType eventType, const InEventParam &inParam, OutEventParam &outParam)

EventType

 EventType
أماكن إقامة
kEvent_CommunicationError

حدث خطأ في الاتصال أثناء إرسال EchoRequest أو انتظار الرد.

kEvent_DefaultCheck

يتم استخدامه للتأكّد من صحة المعالجة التلقائية للأحداث في التطبيق.

kEvent_PreparePayload

ويُطلب من التطبيق تحضير حمولة البيانات لطلب Echo.

kEvent_RequestAborted

تم إلغاء عملية تبادل Echo Exchange قيد التقدم بسبب تقديم طلب لبدء تبادل آخر.

kEvent_RequestSent

تم إرسال رسالة EchoRequest إلى التطبيق المشابه.

kEvent_ResponseReceived

تم تلقي رسالة EchoResponse من أحد الزملاء.

kEvent_ResponseTimeout

لم يتم تلقي استجابة EchoResponse في الوقت المخصص.

الحالة

 State
أماكن إقامة
kState_Idle

كائن العميل غير نشِط.

kState_NotInitialized

لم يتم إعداد كائن العميل.

kState_PreparingBinding

عنصر العميل في انتظار أن يصبح الربط جاهزًا.

kState_RequestInProgress

تم إرسال رسالة EchoRequest وينتظر كائن العميل ردًا.

kState_WaitingToSend

تم استدعاء SendRepeating() وينتظر كائن العميل المرة القادمة لإرسال EchoRequest.

السمات العامة

AppState

void * AppState

يشير هذا المصطلح إلى مؤشر للبيانات الخاصة بالتطبيقات.

وظائف عامة

GetBinding

Binding * GetBinding(
  void
) const

تعرض مؤشرًا إلى الكائن Binding المرتبط بـ WeaveEchoClient.

GetEventCallback

EventCallback GetEventCallback(
  void
) const

تعرض مؤشرًا إلى دالة استدعاء حدث واجهة برمجة التطبيقات التي تم ضبطها حاليًا على الكائن WeaveEchoClient.

GetState

State GetState(
  void
) const

استرِد الحالة الحالية للعنصر WeaveEchoClient.

Init

WEAVE_ERROR Init(
  Binding *binding,
  EventCallback eventCallback,
  void *appState
)

إعداد كائن WeaveEchoClient.

عليك إعداد كائن WeaveEchoClient استعدادًا لإرسال رسائل صدى إلى أحد التطبيقات المشابهة.

التفاصيل
المعلمات
[in] binding
كائن ربط سيتم استخدامه لإجراء اتصال مع العقدة المشابهة.
[in] eventCallback
مؤشر إلى دالة سيتم استدعاؤها بواسطة الكائن WeaveEchoClient لعرض أحداث واجهة برمجة التطبيقات إلى التطبيق.
[in] appState
يشير هذا المصطلح إلى مؤشر إلى عنصر معرَّف من خلال التطبيق سيتم تمريره مرة أخرى إلى التطبيق عند وقوع أي حدث في واجهة برمجة التطبيقات.

IsSendRrepeating

bool IsSendRrepeating() const

تعرض القيمة true إذا كان الكائن WeaveEchoClient في وضع تكرار الإرسال حاليًا.

RequestInProgress

bool RequestInProgress() const

تعرض القيمة "صحيح" إذا تم إرسال EchoRequest وكان الكائن WeaveEchoClient بانتظار الرد.

إرسال

WEAVE_ERROR Send(
  void
)

أرسِل رسالة EchoRequest إلى الزميل.

تبدأ هذه الطريقة عملية إرسال رسالة EchoRequest إلى عقدة النظير. في حال تلقّي رسالة EchoResponse المقابلة، سيتم تسليمها إلى التطبيق من خلال حدث ResponseReceived API.

عند إنشاء رسالة EchoRequest، يرسل WeaveEchoClient طلبًا إلى التطبيق، من خلال حدث PreparePayload API، لإعداد حمولة الرسالة.

إذا لم يكن الكائن Binding في حالة جاهز عند استدعاء هذه الطريقة، سيتم إرسال طلب إلى طريقة Binding::RequestPrepare() لبدء الإعداد عند الطلب. ستتم بعد ذلك وضع عملية الإرسال في قائمة الانتظار حتى تكتمل هذه العملية. يبلغ الحد الأقصى لعمق قائمة الانتظار هذه واحدًا. وبالتالي، سيؤدي أي استدعاء إلى Send() أثناء وجود عملية إرسال سابقة في قائمة الانتظار إلى إرسال طلب EchoRequest واحد فقط.

إنّ استدعاء الدالة Send() عندما يكون WeaveEchoClient في وضع التكرار (مثلاً بسبب استدعاء سابق إلى SendRepeating()) يؤدي إلى تسريع دورة الإرسال وإعادة ضبطها ولكنه لا يخرج WeaveEchoClient من وضع تكرار الإرسال.

إرسال

WEAVE_ERROR Send(
  PacketBuffer *payloadBuf
)

أرسل رسالة EchoRequest إلى التطبيق المشابه مع حمولة محددة.

تبدأ هذه الطريقة عملية إرسال رسالة EchoRequest إلى عقدة النظير. سيتم إرسال محتوى المخزن المؤقت لحمولة البيانات إلى البيانات المشابهة باعتباره حمولة رسالة EchoRequest. في حال تلقّي رسالة EchoResponse المقابلة، سيتم تسليمها إلى التطبيق من خلال حدث ResponseReceived API.

عند طلب هذه الطريقة، تنتقل ملكية المخزن المؤقت للحمولة المقدَّم إلى الكائن WeaveEchoClient الذي يتحمل مسؤولية تحريره. وينطبق ذلك بغض النظر عما إذا كانت الطريقة قد اكتملت بنجاح أم مع وجود خطأ.

إذا لم يكن الكائن Binding في حالة جاهز عند استدعاء هذه الطريقة، سيتم إرسال طلب إلى طريقة Binding::RequestPrepare() لبدء الإعداد عند الطلب. ستتم بعد ذلك وضع عملية الإرسال في قائمة الانتظار حتى تكتمل هذه العملية. يبلغ الحد الأقصى لعمق قائمة الانتظار هذه واحدًا. وبالتالي، سيؤدي أي استدعاء إلى Send() أثناء وجود عملية إرسال سابقة في قائمة الانتظار إلى إرسال طلب EchoRequest واحد فقط.

إنّ استدعاء الدالة Send() عندما يكون WeaveEchoClient في وضع التكرار (مثلاً بسبب استدعاء سابق إلى SendRepeating()) يؤدي إلى تسريع دورة الإرسال وإعادة ضبطها ولكنه لا يخرج WeaveEchoClient من وضع تكرار الإرسال.

التفاصيل
المعلمات
[in] payloadBuf
كائن PacketBuffer الذي يحتوي على بيانات الحمولة لإرسالها إلى النظير. تنتقل ملكية هذا المخزن المؤقت إلى الكائن WeaveEchoClient في جميع الحالات.

SendRepeating

WEAVE_ERROR SendRepeating(
  uint32_t sendIntervalMS
)

بدء إرسال تسلسل متكرر لرسائل EchoRequest إلى النظير.

تبدأ هذه الطريقة عملية متكررة لإرسال رسائل EchoRequest إلى النظير. عند تلقّي رسائل EchoResponse، يتم إرسالها إلى التطبيق من خلال حدث ResponseReceived API.

عند استدعاء الدالة SendRepeating()، تدخل دالة WeaveEchoClient في وضع تكرار الإرسال حيث يتم استدعاء الإجراء Stop() أو حدوث خطأ Binding. ينتج عن استدعاء SendRepeating() عدة مرات تأثير إعادة ضبط دورة الإرسال وتعديل الفاصل الزمني.

يحدث الإرسال الأولي للتسلسل عند استدعاء SendRepeating() أو عندما يصبح Binding جاهزًا بعد استدعاء SendRepeating() (انظر أدناه). تحدث عمليات الإرسال اللاحقة بعد ذلك خلال الفاصل الزمني المحدد.

في كل مرة يتم فيها إرسال رسالة، يرسل WeaveEchoClient طلبًا إلى التطبيق من خلال حدث PreparePayload API لإعداد حمولة الرسالة.

إذا لم يكن الكائن Binding في حالة "جاهز" عندما يحين وقت إرسال الرسالة، سيتم إرسال طلب إلى طريقة Binding::RequestPrepare() لبدء الإعداد عند الطلب. وسيتم إيقاف أي عمليات إرسال رسائل متكررة أخرى مؤقتًا إلى أن تكتمل هذه العملية. سيؤدي تعذّر إعداد الربط عند الطلب إلى خروج WeaveEchoClient من وضع تكرار الإرسال.

SetEventCallback

void SetEventCallback(
  EventCallback eventCallback
)

تضبط هذه السياسة دالة استدعاء حدث واجهة برمجة التطبيقات في الكائن WeaveEchoClient.

إيقاف التشغيل

void Shutdown(
  void
)

أوقِف كائن WeaveEchoClient الذي تم إعداده سابقًا.

تجدر الإشارة إلى أنّه لا يمكن استدعاء هذه الطريقة إلا إذا تم استدعاء الإجراء Init() من قبل.

إيقاف

void Stop(
  void
)

يؤدي هذا الخيار إلى إيقاف أي تبادل للصدى قيد التقدم وإلغاء وضع تكرار الإرسال.

WeaveEchoClient

 WeaveEchoClient(
  void
)

الدوال الثابتة العامة

DefaultEventHandler

void DefaultEventHandler(
  void *appState,
  EventType eventType,
  const InEventParam & inParam,
  OutEventParam & outParam
)

المعالج التلقائي لأحداث واجهة برمجة التطبيقات WeaveEchoClient

ويجب أن تطلب التطبيقات هذه الطريقة لأي أحداث واجهة برمجة تطبيقات لا يمكنها التعرّف عليها أو معالجتها. يجب أن تكون المَعلمات المقدَّمة مطابقة لتلك التي يتم تمريرها من خلال كائن العميل إلى دالة معالِج الحدث في التطبيق.

التفاصيل
المعلمات
[in] appState
مؤشر إلى معلومات الحالة التي يحددها التطبيق والمرتبطة بكائن العميل.
[in] eventType
تم تمرير رقم تعريف الحدث من خلال معاودة الاتصال بالحدث
[in] inParam
مرجع مَعلمات أحداث الإدخال التي تم تمريرها من خلال معاودة الاتصال بالحدث
[in] outParam
مرجع مَعلمات أحداث النتائج التي يتم تمريرها من خلال عملية معاودة الاتصال بالحدث