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 التطبيق لطلب إجراءات محدّدة أو إرسال إشعارات بالأحداث المهمة. يتم إجراء استدعاءات أحداث واجهة برمجة التطبيقات هذه إلى دالة رد الاتصال التي تم ضبطها حاليًا على كائن العميل. باستثناء ما هو مذكور، إنّ التطبيقات مجانية لتغيير حالة العميل أثناء استدعاء الحدث. والاستثناء العام هو أسلوب إيقاف التشغيل() الكائن'، والذي قد لا يتم استدعاؤه مطلقًا أثناء معاودة الاتصال.
يتم تحديد أحداث واجهة برمجة التطبيقات التالية:
تجهيز الحمولة
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)
|
typedefvoid(*
|
EventType{
|
تعداد |
State{
|
تعداد |
السمات العامة |
|
---|---|
AppState
|
void *
مؤشر للبيانات الخاصة بالتطبيق.
|
وظائف عامة |
|
---|---|
GetBinding(void) const
|
Binding *
لعرض مؤشر على العنصر 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:: |
إدخال معلَمات إلى حدث واجهة برمجة التطبيقات WeaveEchoClient. |
nl:: |
مَعلمات إخراج إلى حدث واجهة برمجة التطبيقات 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 استعدادًا لإرسال رسائل صدى الصوت إلى نظير.
التفاصيل | |||||||
---|---|---|---|---|---|---|---|
المعلَمات |
|
تكرار إرسال 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 من وضع الإرسال المتكرر.
التفاصيل | |||
---|---|---|---|
المعلَمات |
|
تكرار
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.
التفاصيل | |||||||||
---|---|---|---|---|---|---|---|---|---|
المعلَمات |
|