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 יבקש הכנה לפי דרישה של הקישור (לפרטים, עיינו ב-Binding::RequestPrepare()).

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

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

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

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

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

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

אירועי API

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

אירועי ה-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
מגדירה את פונקציית הקריאה החוזרת (callback) של אירוע ה-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

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

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

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

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

EventCallback

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

EventType

 EventType
תכונות
kEvent_CommunicationError

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

kEvent_DefaultCheck

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

kEvent_PreparePayload

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

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.

הפעלה

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

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

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

פרטים
פרמטרים
[in] 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 לא במצב 'מוכן' כשמתבצעת קריאה לשיטה הזו, תישלח בקשה למתודה Binding::RequestPrepare() כדי להתחיל בהכנה על פי דרישה. פעולת השליחה תמתין בתור עד לסיום התהליך. העומק המקסימלי של התור הזה הוא אחד. לכן, כל קריאה ל-Send() בזמן שיש שליחה קודמת בתור, תביא לשליחה של EchoRequest אחד בלבד.

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

שליחה

WEAVE_ERROR Send(
  PacketBuffer *payloadBuf
)

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

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

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

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

SetEventCallback

void SetEventCallback(
  EventCallback eventCallback
)

מגדירה את פונקציית הקריאה החוזרת (callback) של אירוע ה-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.

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

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