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 משתמש באובייקט Binding של Weave, שמשמש לזיהוי וליצירה של תקשורת עם הנמען המיועד של בקשות ההד. אפשר להגדיר ולהכין את ה-Binding לפני האתחול של האובייקט WeaveEchoClient, או להשאיר אותו לא מוכן. במקרה כזה, ה-WeaveEchoClient יבקש מ-WeaveEchoClient לבקש הכנה לפי דרישה של הקישור (פרטים נוספים זמינים במאמר Binding::RequestPrepare()).

אם תהליך ההכנה של הקישור ייכשל אחרי המעבר למצב 'מוכן', תישלח גם בקשה להכנה לפי דרישה.

מצב שליחה חוזרת

ניתן להשתמש במתודה SendRepeating() כדי להעביר את ה-WeaveEchoClient למצב SendRepeating. במצב הזה, אובייקט הלקוח שולח רצף חוזר של הודעות EchoRequest לעמיתים במרווח זמן שהוגדר. אפשר לבטל את מצב SendRepeating באמצעות קריאה ל-method Stop().

שידורים מרובים ורחבים

ניתן להשתמש באובייקט WeaveEchoClient כדי לשלוח EchoRequests לנמענים מרובים בו-זמנית, על ידי הגדרת האובייקט Binding עם כתובת multicast מתאימה של IPv6 או כתובת שידור מקומית של IPv4 (255.255.255.255). כשהאובייקט WeaveEchoClient מזהה כתובת של פרוטוקול Multicast או של רשת שכנה, הוא עובר באופן אוטומטי למצב MultiResponse בעת שליחת ה-EchoRequest.

במצב הזה, האובייקט ממשיך להאזין לכל הודעות EchoResponse הנכנסות ולשלוח אותן, שמגיעות באותה פלטפורמת Exchange. האובייקט נשאר במצב MultiResponse עד: 1) האפליקציה קוראת ל-Stop() או Send(), 2) במצב SendRepeating, הזמן מגיע לשליחת בקשה נוספת, או 3) לא מתקבלת תגובה והזמן הקצוב לתפוגה של קבלה פג.

אירועי API

במהלך הפעילות שלו, האובייקט WeaveEchoClient יקרא לאפליקציה כדי לבקש פעולות ספציפיות או לשלוח התראות על אירועים חשובים. הקריאות האלה לאירועי API מתבצעות לפונקציית הקריאה החוזרת שמוגדרת כרגע באובייקט הלקוח. אלא אם צוין אחרת, האפליקציות יכולות לשנות את מצב הלקוח במהלך קריאה חוזרת של אירוע. יוצא הדופן היחיד הוא שיטת Shutdown() של האובייקט, והיא לא יכולה להתבצע אף פעם במהלך קריאה חוזרת.

אירועי ה-API הבאים מוגדרים:

PreparePayload

ה-WeaveEchoClient עומד ליצור הודעת EchoRequest ומבקש מהאפליקציה לספק מטען ייעודי (payload). אם האפליקציה רוצה, היא עשויה להחזיר PacketBuffer חדש שמכיל את נתוני המטען הייעודי (payload). אם האפליקציה לא מטפלת באירוע הזה, יישלח אוטומטית EchoRequest עם מטען ייעודי (payload) באורך אפס. ייתכן שהאפליקציה לא תשנה את המצב של WeaveEchoClient במהלך הקריאה החוזרת (callback) הזו.

RequestSent

הודעת EchoRequest נשלחה לעמית.

ResponseReceived

התקבלה הודעת EchoResponse מהעמית. הארגומנטים לאירוע מכילים את המטען הייעודי (payload) של התגובה ומטא-מידע לגבי הודעת התשובה.

CommunicationError

אירעה שגיאה במהלך יצירה או שליחה של EchoRequest, או בזמן ההמתנה לתגובה. דוגמאות לשגיאות שעשויות להתרחש בזמן ההמתנה לתשובה הן שגיאות חשובות או סגירה לא צפויה של החיבור. הארגומנטים לאירוע מכילים את סיבת השגיאה.

ResponseTimeout

תגובת EchoResponse לא התקבלה בזמן שהוקצב. הזמן הקצוב לתפוגה של תגובה נקבע על ידי המאפיין DefaultResponseTimeout באובייקט Binding.

RequestAborted

חילופי הד בפעולה בוטלה כי נשלחה בקשה לשלוח 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
} 		טיפוסים בני מנייה (enum)
State{
  kState_NotInitialized = 0,
  kState_Idle = 1,
  kState_PreparingBinding = 2,
  kState_RequestInProgress = 3,
  kState_WaitingToSend = 4
} 		טיפוסים בני מנייה (enum)

מאפיינים ציבוריים
AppState
void *
מצביע לנתונים ספציפיים לאפליקציה.

פונקציות ציבוריות
GetBinding(void) const
מחזירה מצביע לאובייקט Binding המשויך ל-WeaveEchoClient.
GetEventCallback(void) const
EventCallback
הפונקציה מחזירה מצביע לפונקציית הקריאה החוזרת של אירוע ה-API שמוגדרת כרגע באובייקט WeaveEchoClient.
GetState(void) const
מאחזרים את המצב הנוכחי של האובייקט WeaveEchoClient.
Init(Binding *binding, EventCallback eventCallback, void *appState)
מאתחלים אובייקט WeaveEchoClient.
IsSendRrepeating() const
bool
הפונקציה מחזירה true אם האובייקט WeaveEchoClient נמצא כרגע במצב שליחה חוזרת.
RequestInProgress() const
bool
הפונקציה מחזירה true אם נשלח EchoRequest והאובייקט WeaveEchoClient ממתין לתגובה.
Send(void)
שליחת הודעת EchoRequest לעמיתים.
Send(PacketBuffer *payloadBuf)
שליחת הודעת EchoRequest לעמיתים עם מטען ייעודי (payload) ספציפי.
SendRepeating(uint32_t sendIntervalMS)
התחלת שליחה של רצף חוזר של הודעות EchoRequest לעמית.
SetEventCallback(EventCallback eventCallback)
void
מגדירה את פונקציית הקריאה החוזרת של אירוע ה-API באובייקט WeaveEchoClient.
Shutdown(void)
void
כיבוי של אובייקט WeaveEchoClient שאותחל קודם לכן.
Stop(void)
void
הפסקת כל החלפה של ההד שמתבצעת וביטול מצב החזרה על ההד.

פונקציות סטטיות ציבוריות
DefaultEventHandler(void *appState, EventType eventType, const InEventParam & inParam, OutEventParam & outParam)
void
handler ברירת מחדל לאירועי API של WeaveEchoClient.

מבנים
nl::Weave::Profiles::Echo_Next::WeaveEchoClient::InEventParam

צריך להזין פרמטרים לאירוע WeaveEchoClient של API.

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

פרמטרים של פלט לאירוע WeaveEchoClient של API.

סוגים ציבוריים

EventCallback

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

EventType

 EventType
מאפיינים
kEvent_CommunicationError

אירעה שגיאת תקשורת בעת שליחת EchoRequest או המתנה לתגובה.

kEvent_DefaultCheck

משמש לאימות הטיפול הנכון באירועים באפליקציה כברירת מחדל.

kEvent_PreparePayload

האפליקציה מבקשת להכין את המטען הייעודי (payload) לבקשת ה-Echo.

kEvent_RequestAborted

חילופי הד שמתנהלים בוטלו כי נשלחה בקשה להתחלת החלפה נוספת.

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

הפונקציה מחזירה מצביע לפונקציית הקריאה החוזרת של אירוע ה-API שמוגדרת כרגע באובייקט WeaveEchoClient.

GetState

State GetState(
  void
) const

מאחזרים את המצב הנוכחי של האובייקט WeaveEchoClient.

Init

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

מאתחלים אובייקט WeaveEchoClient.

לאתחל אובייקט WeaveEchoClient כהכנה לשליחת הודעות הד לעמיתים.

פרטים
פרמטרים
[in] binding
אובייקט Binding שישמש ליצירת תקשורת עם הצומת של האפליקציה להשוואה.
[in] eventCallback
מצביע אל פונקציה שתיקרא על ידי האובייקט WeaveEchoClient, כדי להעביר אירועי API לאפליקציה.
[in] appState
מצביע אל אובייקט בהגדרת אפליקציה שיועבר חזרה לאפליקציה בכל פעם שיתרחש אירוע API.

IsSendRrepeating

bool IsSendRrepeating() const

הפונקציה מחזירה true אם האובייקט WeaveEchoClient נמצא כרגע במצב שליחה חוזרת.

RequestInProgress

bool RequestInProgress() const

הפונקציה מחזירה true אם נשלח EchoRequest והאובייקט WeaveEchoClient ממתין לתגובה.

שליחה

WEAVE_ERROR Send(
  void
)

שליחת הודעת EchoRequest לעמיתים.

שיטה זו מפעילה את התהליך של שליחת הודעת EchoRequest לצומת של השכנה. אם וכאשר תתקבל הודעת EchoResponse תואמת, היא תימסר לאפליקציה דרך אירוע ResponseReceived API.

כשיוצרים את ההודעה EchoRequest, ה-WeaveEchoClient שולח בקשה לאפליקציה, באמצעות האירוע PreparePayload API, כדי להכין את המטען הייעודי (payload) של ההודעה.

אם האובייקט Binding לא נמצא במצב Ready (מוכן) לשיטה הזו, תישלח בקשה למתודה Binding::RequestPrepare() כדי להתחיל הכנה לפי דרישה. פעולת השליחה תיכנס לתור עד לסיום התהליך. העומק המקסימלי של התור הזה הוא אחד. לכן, כל קריאה ל-Send() בזמן שיש שליחה קודמת בתור, תוביל לשליחת EchoRequest בלבד.

קריאה ל-Send() בזמן ש-WeaveEchoClient נמצא במצב שליחה חוזרת (כלומר, בגלל קריאה קודמת ל-SendRepeating()) משפיעה על האצה ואיפוס של מחזור השליחה, אבל לא מוציאה את WeaveEchoClient ממצב שליחה חוזרת.

שליחה

WEAVE_ERROR Send(
  PacketBuffer *payloadBuf
)

שליחת הודעת EchoRequest לעמיתים עם מטען ייעודי (payload) ספציפי.

שיטה זו מפעילה את התהליך של שליחת הודעת EchoRequest לצומת של השכנה. התוכן של מאגר הנתונים הזמני שסופק יישלח לעמית בתור המטען הייעודי (payload) של הודעת EchoRequest. אם וכאשר תתקבל הודעת EchoResponse תואמת, היא תימסר לאפליקציה דרך אירוע ResponseReceived API.

לאחר קריאה לשיטה הזו, הבעלות על מאגר הנתונים הזמני שסופק עוברת לאובייקט WeaveEchoClient, והוא באחריות לשחרר אותו. הדבר נכון בין אם ה-method הושלמה בהצלחה ובין אם עם שגיאה.

אם האובייקט Binding לא נמצא במצב Ready (מוכן) לשיטה הזו, תישלח בקשה למתודה Binding::RequestPrepare() כדי להתחיל הכנה לפי דרישה. פעולת השליחה תיכנס לתור עד שהתהליך יושלם. העומק המקסימלי של התור הזה הוא אחד. לכן, כל קריאה ל-Send() בזמן שיש שליחה קודמת בתור, תוביל לשליחת EchoRequest בלבד.

קריאה ל-Send() בזמן ש-WeaveEchoClient נמצא במצב שליחה חוזרת (כלומר, בגלל קריאה קודמת ל-SendRepeating()) משפיעה על האצה ואיפוס של מחזור השליחה, אבל לא מוציאה את WeaveEchoClient ממצב שליחה חוזרת.

פרטים
פרמטרים
[in] payloadBuf
אובייקט PacketBuffer שמכיל נתוני מטען ייעודי (payload) שיישלחו לעמית. הבעלות על מאגר הנתונים הזמני מועברת לאובייקט WeaveEchoClient בכל המקרים.

SendRepeating

WEAVE_ERROR SendRepeating(
  uint32_t sendIntervalMS
)

התחלת שליחה של רצף חוזר של הודעות EchoRequest לעמית.

השיטה הזו מפעילה תהליך חוזר של שליחת הודעות EchoRequest לעמית. מאחר שהודעות EchoResponse מתקבלות מהעמית, הן נשלחות לאפליקציה דרך אירוע ResponseReceived API.

כשמתבצעת קריאה ל-SendRepeating(), ה-WeaveEchoClient עובר למצב שליחה חוזרת שבו הוא נשאר עד לקריאה של Stop() או עד שמתרחשת שגיאת Binding. קריאה ל-SendRepeating() מספר פעמים משפיעה על איפוס מחזור השליחה ועדכון המרווח.

השליחה הראשונית של רצף מתרחשת בזמן הקריאה ל-SendRepeating(), או בכל פעם שה-Binding מוכן אחרי הקריאה ל-SendRepeating() (ראו בהמשך). השליחות הבאות מתבצעות לאחר מכן במרווח הזמן שצוין.

בכל פעם שמתרחשת שליחה, ה-WeaveEchoClient שולח בקשה לאפליקציה, באמצעות האירוע PreparePayload API, כדי להכין את המטען הייעודי (payload) של ההודעה.

אם האובייקט Binding לא נמצא במצב Ready (מוכן) כשמגיע הזמן לשלוח הודעה, תישלח בקשה למתודה Binding::RequestPrepare() כדי להתחיל הכנה לפי דרישה. הודעות חוזרות נוספות יושהו עד שהתהליך יסתיים. תקלה במהלך הכנת הקישור על פי דרישה תגרום ל-WeaveEchoClient לצאת ממצב השליחה החוזרת.

SetEventCallback

void SetEventCallback(
  EventCallback eventCallback
)

מגדירה את פונקציית הקריאה החוזרת של אירוע ה-API באובייקט WeaveEchoClient.

כיבוי

void Shutdown(
  void
)

כיבוי של אובייקט WeaveEchoClient שאותחל קודם לכן.

שימו לב שאפשר לקרוא לשיטה הזו רק אם היא נקראה בעבר לשיטה Init().

עצירה

void Stop(
  void
)

הפסקת כל חילופי הד שמתבצעות וביטול מצב השליחה החוזרת.

WeaveEchoClient

 WeaveEchoClient(
  void
)

פונקציות סטטיות ציבוריות

DefaultEventHandler

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

handler ברירת מחדל לאירועי API של WeaveEchoClient.

אפליקציות נדרשות לקרוא ל-method הזה לכל אירועי API שהם לא מזהים או לא מטפלים בהם. הפרמטרים שסופקו חייבים להיות זהים לפרמטרים שמועברים על ידי אובייקט הלקוח אל פונקציית המטפל באירועים של האפליקציה.

פרטים
פרמטרים
[in] appState
מצביע אל פרטי מצב בהגדרת אפליקציה שמשויכים לאובייקט הלקוח.
[in] eventType
מזהה האירוע שהועבר על ידי הקריאה החוזרת של האירוע
[in] inParam
הפניה לפרמטרים של קלט מסוג אירוע שמועברים על-ידי הקריאה החוזרת של האירוע
[in] outParam
הפניה לפרמטרים של אירוע פלט שהועברו על ידי הקריאה החוזרת של האירוע (callback)