nl::Weave::الملفات الشخصية::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 لمرة واحدة أو عقدة مماثلة إلى عقدة مطابقة يحدّدها عنصر ربط. تتوفّر فئة مقابلة للاستجابة لطلبات صدى الصوت (راجِع WeaveEchoServer).

ربط العميل

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

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

وضع Sendتكرار

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

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

يمكن استخدام عنصر WeaveEchoClient لإرسال طلبات EchoRequests إلى العديد من المُستلِمين في آنٍ واحد من خلال ضبط عنصر الربط مع عنوان بث متوافق مع IPv6 مناسب أو عنوان بث الشبكة المحلية IPv4 (255.255.255.255). عندما يرصد الكائن WeaveEchoClient عنوان البث المباشر أو بث الزملاء، سيدخل تلقائيًا في وضع MultiResponse عند إرسال EchoRequest.

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

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

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

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

تجهيز الحمولة

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

تم إرسال الطلب

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

تمّ تلقي ردّ.

تم تلقّي رسالة EchoResponse من الزملاء. تتضمن وسيطات الحدث حمولة الرد ومعلومات وصفية حول رسالة الرد.

خطأ في الاتصال

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

مهلة الاستجابة

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

تم إلغاء الطلب

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

عندما يكون العنصر في وضع MultiResponse، يتم منع الحدث في حال استلام رسالة 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
لعرض مؤشر على العنصر Binding (الربط) المرتبط بـ 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
لإيقاف أي تبادل Echo قيد التقدم وإلغاء وضع تكرار الإرسال.

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

الهياكل
nl::Weave::الملفات الشخصية::Echo_Next::WeaveEchoClient::InEventParam

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

nl::Weave::الملفات الشخصية::Echo_Next::WeaveEchoClient::OutEventParam

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

الأنواع المتاحة للجميع

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

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

نوع الحدث

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

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

kEvent_DefaultCheck

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

kEvent_PreparePayload

ويتم تقديم طلب إلى التطبيق لتجهيز حمولة طلب Echo.

kEvent_RequestAborted

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

kEvent_RequestSent

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

kEvent_ResponseReceived

تم تلقّي رسالة EchoResponse من الزملاء.

kEvent_ResponseTimeout

لم يتم استلام EchoResponse في الوقت المخصّص.

الولاية

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

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

kState_NotInitialized

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

kState_PreparingBinding

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

kState_RequestInProgress

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

kState_WaitingToSend

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

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

حالة التطبيق

void * AppState

مؤشر للبيانات الخاصة بالتطبيق.

وظائف عامة

الحصول على تجميع البيانات

Binding * GetBinding(
  void
) const

لعرض مؤشر على العنصر Binding (الربط) المرتبط بـ WeaveEchoClient.

GetEventCallback

EventCallback GetEventCallback(
  void
) const

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

الحصول على الولاية

State GetState(
  void
) const

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

إنيت

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

ابدأ إعداد كائن WeaveEchoClient.

يمكنك إعداد عنصر WeaveEchoClient استعدادًا لإرسال رسائل صدى الصوت إلى نظير.

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

تكرار إرسال SendR

bool IsSendRrepeating() const

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

الطلب قيد التقدم

bool RequestInProgress() const

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

إرسال

WEAVE_ERROR Send(
  void
)

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

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

عند إنشاء رسالة EchoRequest، يقدم WeaveEchoClient طلبًا للتطبيق، من خلال حدث واجهة برمجة تطبيقات SetupPayload، لإعداد البيانات الأساسية للرسالة.

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

يؤثّر استدعاء Send() عندما يكون WeaveEchoClient في وضع الإرسال المتكرر (أي بسبب استدعاء سابق لـ SendDuplicateing()) في تسريع دورة الإرسال وإعادة ضبطها ولكنه لا يزيل WeaveEchoClient من وضع الإرسال المتكرر.

إرسال

WEAVE_ERROR Send(
  PacketBuffer *payloadBuf
)

أرسِل رسالة EchoRequest إلى الزملاء مع حمولة محددة.

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

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

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

يؤثّر استدعاء Send() عندما يكون WeaveEchoClient في وضع الإرسال المتكرر (أي بسبب استدعاء سابق لـ SendDuplicateing()) في تسريع دورة الإرسال وإعادة ضبطها ولكنه لا يزيل WeaveEchoClient من وضع الإرسال المتكرر.

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

تكرار

WEAVE_ERROR SendRepeating(
  uint32_t sendIntervalMS
)

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

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

عند استدعاء SendDuplicateing()، تُدخل WeaveEchoClient وضع تكرار الإرسال حيث يتم البقاء حتى يتم استدعاء Stop() أو يحدث خطأ ربط. ويؤدّي استدعاء SendDuplicateing() عدة مرّات إلى إعادة ضبط دورة الإرسال وتعديل الفاصل الزمني.

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

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

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

ضبط CallEvent

void SetEventCallback(
  EventCallback eventCallback
)

تضبط دالة رد الاتصال لواجهة برمجة التطبيقات على العنصر WeaveEchoClient.

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

void Shutdown(
  void
)

يجب إيقاف العنصر WeaveEchoClient الذي تم إعداده من قبل.

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

إيقاف

void Stop(
  void
)

لإيقاف أي تبادل Echo قيد التقدم وإلغاء وضع تكرار الإرسال.

WeaveEchoClient

 WeaveEchoClient(
  void
)

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

مؤشر الحدث التلقائي

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

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

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

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