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. على غرار بروتوكول ping لبروتوكول ICMP، يمكن استخدام بروتوكول Weave Echo لاختبار مدى الحياة وإمكانية الوصول إلى عقدة Weave.

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

ربط العميل

يأخذ WeaveEchoClient كائن الربط الذي يتم استخدامه لتحديد وتأسيس اتصال مع المستلم المقصود لطلبات الارتداد. يمكن ضبط الربط وإعداده من خلال التطبيق قبل إعداد كائن WeaveEchoClient، أو يمكن تركه بدون إعداد، وفي هذه الحالة سيطلب WeaveEchoClient إعداد الربط عند الطلب (يمكنك الرجوع إلى جمل::طلبPrepare() للحصول على التفاصيل).

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

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

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

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

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

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

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

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

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

PreparePayload

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

RequestSent

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

ResponseReceived

تم استلام رسالة EchoResponse من المستخدم الزميل. تتضمن وسيطات الحدث حمولة الاستجابة ومعلومات وصفية حول رسالة الاستجابة.

CommunicationError

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

ResponseTimeout

لم يتم تلقّي EchoResponse في الوقت المخصّص. يتم التحكّم في مهلة الاستجابة من خلال سمة DefaultResponseTimeout في كائن الربط.

RequestAborted

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

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

الدلالة والهياكل
WeaveEchoClient(void)

الأنواع العلنية
EventCallback)(void *appState, EventType eventType, const InEventParam &inParam, OutEventParam &outParam) typedef
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
تعرض مؤشرًا لكائن الربط المرتبط بـ WeaveEchoClient.
GetEventCallback(void) const
EventCallback
لعرض مؤشر لدالة استدعاء حدث واجهة برمجة التطبيقات التي تم إعدادها حاليًا على الكائن WeaveEchoClient.
GetState(void) const
استرِد الحالة الحالية لكائن WeaveEchoClient.
Init(Binding *binding, EventCallback eventCallback, void *appState)
تهيئة كائن WeaveEchoClient.
IsSendRrepeating() const
bool
يتم عرض "صحيح" إذا كان الكائن 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

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

kEvent_RequestAborted

تم إلغاء عملية تبادل Echo قيد التقدّم بسبب تقديم طلب لبدء عملية تبادل أخرى.

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

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

GetEventCallback

EventCallback GetEventCallback(
  void
) const

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

GetState

State GetState(
  void
) const

استرِد الحالة الحالية لكائن WeaveEchoClient.

إنت

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

تهيئة كائن WeaveEchoClient.

تهيئة كائن WeaveEchoClient استعدادًا لإرسال رسائل ارتداد إلى نظير.

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

IsSendRrepeating

bool IsSendRrepeating() const

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

RequestInProgress

bool RequestInProgress() const

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

إرسال

WEAVE_ERROR Send(
  void
)

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

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

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

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

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

إرسال

WEAVE_ERROR Send(
  PacketBuffer *payloadBuf
)

أرسل رسالة EchoRequest إلى النظير مع حمولة محددة.

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

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

إذا لم يكن كائن الربط في حالة جاهز عند استدعاء هذه الطريقة، فسيتم تقديم طلب إلى طريقة جمود::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() أو يحدث خطأ الربط. يؤدي استدعاء SendRepeating() عدة مرات إلى إعادة ضبط دورة الإرسال وتعديل الفاصل.

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

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

إذا لم يكن كائن عودة في حالة الاستعداد عندما يحين وقت إرسال رسالة، سيتم إرسال طلب إلى طريقة جمل "تجليد::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
مرجع مَعلمات أحداث النتائج التي تم تمريرها من خلال استدعاء الحدث