הסכמות ב-TCP

המודול הזה כולל הפשטות קלות לשימוש בנוסף ל-TCP API הבסיסי.

סיכום

מספור
anonymous enum טיפוסים בני מנייה (enum)
מגדיר סימונים שהועברו אל otTcpCircularSendBufferWrite.

סוג שגיאות
otTcpCircularSendBuffer typedef
מייצגת אחסון זמני בעיגול לשימוש עם נקודת קצה TCP.
otTcpEndpointAndCircularSendBuffer typedef
מבנה הקשר לשימוש עם mbedtls_ssl_set_bio.

פונקציות
otTcpCircularSendBufferDeinitialize(otTcpCircularSendBuffer *aSendBuffer)
מפעילה מחדש אחסון זמני לשליחה מעגלית של TCP, ומנתקת אותו אם הוא מצורף.
otTcpCircularSendBufferForceDiscardAll(otTcpCircularSendBuffer *aSendBuffer)
void
מאלץ אילוץ של כל הנתונים במאגר הנתונים הזמני של השליחה.
otTcpCircularSendBufferGetFreeSpace(const otTcpCircularSendBuffer *aSendBuffer)
size_t
מחזירה את כמות המקום הפנוי במאגר הנתונים הזמני של מעגלי TCP.
otTcpCircularSendBufferHandleForwardProgress(otTcpCircularSendBuffer *aSendBuffer, size_t aInSendBuffer)
void
מבצעת טיפול ספציפי מעגלי-send-buffer בקריאה החוזרת (otTcpForwardProgress).
otTcpCircularSendBufferInitialize(otTcpCircularSendBuffer *aSendBuffer, void *aDataBuffer, size_t aCapacity)
void
הפעלה של אחסון זמני בעיגול של TCP.
otTcpCircularSendBufferWrite(otTcpEndpoint *aEndpoint, otTcpCircularSendBuffer *aSendBuffer, const void *aData, size_t aLength, size_t *aWritten, uint32_t aFlags)
שולחת נתונים בנקודת קצה מסוג TCP, באמצעות מאגר הנתונים הזמני של TCP מעגלי, לניהול האחסון הזמני.
otTcpMbedTlsSslRecvCallback(void *aCtx, unsigned char *aBuf, size_t aLen)
int
קריאה חוזרת (callback) ללא חסימה היא העברה ל-mbedtls_ssl_set_bio.
otTcpMbedTlsSslSendCallback(void *aCtx, const unsigned char *aBuf, size_t aLen)
int
ביטול הקריאה החוזרת (callback) כדי לא לעבור אל mbedtls_ssl_set_bio.

מבנים
otTcpCirularSendBuffer

מייצגת אחסון זמני בעיגול לשימוש עם נקודת קצה TCP.

otTcpEndpointAndCirularSendBuffer

מבנה הקשר לשימוש עם mbedtls_ssl_set_bio.

מספור

טיפוס אנונימי

 anonymous enum

מגדיר סימונים שהועברו אל otTcpCircularSendBufferWrite.

סוג שגיאות

otTcpCirularSendBuffer

struct otTcpCircularSendBuffer otTcpCircularSendBuffer

מייצגת אחסון זמני בעיגול לשימוש עם נקודת קצה TCP.

השימוש במאגר נתונים זמני הוא אופציונלי. אפליקציות יכולות להשתמש בנקודת קצה של TCP כדי לשלוח נתונים על ידי ניהול ישיר של otLinkedBuffers. עם זאת, בחלק מהאפליקציות יותר קל יותר ליצור מאגר אחסון זמני מעגלי. אפליקציות כאלה יכולות לבצע קריאה ל-otTcpCirularSendBufferWrite() כדי "לחבר" אחסון זמני מעגלי לנקודת קצה של TCP ולשלוח נתונים בנקודת הקצה הזו של TCP, תוך הסתמכות על המאגר הזמני של שליחת הנתונים כדי לנהל את ה-otLinkedBuffers.

הפרמטר otTcpCirularSendBuffer מוטמע בנוסף ל-API המבוסס על otLinkedBuffer ומסופק על ידי otTcpEndpoint. לאחר החיבור אל otTcpEndpoint, otTcpCirularSendBuffer מבצע את כל העבודה על ניהול otLinkedBuffer עבור החיבור. כלומר, אחרי חיבור של otTcpCirularSendBuffer אל otTcpEndpoint, אסור להפעיל את האפליקציה otTcpSendByReference() או otTcpSendByExtension() ב-otTcpEndpoint. במקום זאת, האפליקציה צריכה להשתמש בפונקציה otTcpCirularSendBufferWrite() כדי להוסיף נתונים למאגר הנתונים להעברה.

הקריאה החוזרת (callback) של otTcpForwardProgress() היא הדרך הרצויה עבור המשתמשים ללמוד מתי יש מקום פנוי במאגר הנתונים הזמני של השליחה. ב-otTcpEndpoint שאליו מצורף otTcpCirularSendBuffer, האפליקציה חייבת להתקין callTcpForwardProgress() ולחזור על הקריאה לפעולה otTcpCirularSendBufferHandleForwardProgress() ב-otTcpCirularSendBuffer בתחילת פונקציית הקריאה החוזרת. מומלץ שהמשתמש לא יתקין קריאה חוזרת (callback) מסוג otTcpSendDone(), כי כל הניהול של otLinkedBuffers מטופל על ידי האחסון הזמני העגול.

האפליקציה לא צריכה לבדוק ישירות את השדות של המבנה הזה, אלא רק לבצע איתו פעולות באמצעות פונקציות ה-API של מעגלי TCP Buffer, שהחתימה שלהן מסופקת בקובץ הזה.

otTcpEndpointAndCirularSendBuffer

struct otTcpEndpointAndCircularSendBuffer otTcpEndpointAndCircularSendBuffer

מבנה הקשר לשימוש עם mbedtls_ssl_set_bio.

פונקציות

otTcpCirularSendBufferDeinitialize

otError otTcpCircularSendBufferDeinitialize(
  otTcpCircularSendBuffer *aSendBuffer
)

מפעילה מחדש אחסון זמני לשליחה מעגלית של TCP, ומנתקת אותו אם הוא מצורף.

אם מאגר השליחה העגולה של TCP לא ריק, הפעולה תיכשל.

פרטים
פרמטרים
[in] aSendBuffer
העיגול של TCP שולח את המאגר לצורך אתחול.
ערכי החזרה
OT_ERROR_NONE
האתחול של אחסון הנתונים העגול של TCP אותחל בהצלחה.
OT_ERROR_BUSY
מאגר נתונים זמני מעגלי מכיל נתונים ולא ניתן לאתחל אותו.

otTcpCirularSendBufferForceDiscardAll

void otTcpCircularSendBufferForceDiscardAll(
  otTcpCircularSendBuffer *aSendBuffer
)

מאלץ אילוץ של כל הנתונים במאגר הנתונים הזמני של השליחה.

האפליקציה צפויה לקרוא לפונקציה הזו כשחיבור TCP מסתיים ללא משמעות (למשל, אם האפליקציה מתקשרת ל-otTcpEndpointAbort() או שמתקבלת הודעה על חיבור מאופס דרך הקריאה החוזרת (otTcpConnectionLost()).

קריאת הפונקציה הזו לעיגול זמני של TCP לשליחה מעגלית שאינה מצורפת לנקודת קצה של TCP, מובילה להתנהגות לא מוגדרת.

פרטים
פרמטרים
[in] aSendBuffer
העיגול של TCP שולח את האחסון הזמני של הנתונים שלו.

otTcpCirularSendBufferGetFreeSpace

size_t otTcpCircularSendBufferGetFreeSpace(
  const otTcpCircularSendBuffer *aSendBuffer
)

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

הפעולה הזו תמיד תצליח.

פרטים
פרמטרים
[in] aSendBuffer
מצביע לעיגול ה-TCP שולח את המרווח הפנוי להחזרה.
החזרות
כמות המקום הפנוי במאגר הנתונים הזמני.

otTcpCirularSendBufferHandleForwardProgress

void otTcpCircularSendBufferHandleForwardProgress(
  otTcpCircularSendBuffer *aSendBuffer,
  size_t aInSendBuffer
)

מבצעת טיפול ספציפי מעגלי-send-buffer בקריאה החוזרת (otTcpForwardProgress).

האפליקציה אמורה להתקין קריאה חוזרת (callback) מסוג otTcpForwardProgress() ב-otTcpEndpoint, ולקריאה לפונקציה הזו בתחילת פונקציית הקריאה החוזרת, לעיבוד ספציפי לעיגול-שליחה-במאגר.

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

פרטים
פרמטרים
[in] aSendBuffer
מצביע למאגר הנתונים הזמני של TCP לשליחת נקודות קצה (endpoint) שבגינן מופעל otTcpForwardProgress().
[in] aInSendBuffer
הערך של aInSendBuffer הועבר אל הקריאה החוזרת (callback) של otTcpForwardProgress().

otTcpCirularSendBufferInitialize

void otTcpCircularSendBufferInitialize(
  otTcpCircularSendBuffer *aSendBuffer,
  void *aDataBuffer,
  size_t aCapacity
)

הפעלה של אחסון זמני בעיגול של TCP.

פרטים
פרמטרים
[in] aSendBuffer
מצביע אל העיגול של TCP לשליחה למאגר הנתונים הזמני.
[in] aDataBuffer
מצביע לזיכרון שבו יש להשתמש כדי לאחסן נתונים מעגלי TCP לשליחה.
[in] aCapacity
הקיבולת, בבייטים, של האחסון הזמני המעוגל של TCP, שחייב להיות שווה לגודל הזיכרון שאליו מפנה aDataBuffer .

otTcpCirularSendBufferWrite

otError otTcpCircularSendBufferWrite(
  otTcpEndpoint *aEndpoint,
  otTcpCircularSendBuffer *aSendBuffer,
  const void *aData,
  size_t aLength,
  size_t *aWritten,
  uint32_t aFlags
)

שולחת נתונים בנקודת קצה מסוג TCP, באמצעות מאגר הנתונים הזמני של TCP מעגלי, לניהול האחסון הזמני.

לאחר קריאה לפונקציה הזו, aSendBuffer ו-aEndpoint נחשבות זו לזו. כאשר הם מצורפים, כל פעולות השליחה עבור aEndpoint חייבות להתבצע באמצעות aSendBuffer וכל הפעולות ב-aSendBuffer חייבות להיות משויכות אל aEndpoint .

הדרך היחידה "לנתק" אחסון זמני של מעגלי TCP ונקודת קצה של TCP היא להמתין עד שמאגר השליחה יהיה ריק לחלוטין. יש שתי דרכים לעשות זאת: (1) כל הנתונים במאגר הנתונים הזמני נשלחים ואושרים בדרך הרגילה של פעולת פרוטוקול TCP, או (2) החיבור מופסק.

דפוס השימוש המומלץ הוא להשתמש במאגר זמני של TCP עם נקודת קצה (endpoint) של TCP, ולשלוח נתונים בנקודת הקצה הזו של TCP רק דרך המאגר הזמני העגול של TCP. דפוס השימוש המומלץ הזה מבטל את הבעיות המתוארות למעלה, על ידי שימוש תמיד בנקודת קצה של TCP ובמאגר בקרה זמני ל-TCP.

אם האחסון הזמני העגול מגיע לקיבולת, רק קידומת של הנתונים שסופקו מועתקת למאגר הנתונים העגול של השליחה.

פרטים
פרמטרים
[in] aEndpoint
נקודת הקצה של TCP שאליה יישלחו הנתונים.
[in] aSendBuffer
העגול של ה-TCP שולח את המאגר שאליו יש להעתיק את הנתונים.
[in] aData
מצביע לנתונים שיש להעתיק אל מאגר הנתונים הזמני של TCP.
[in] aLength
אורך הנתונים ש-aData מפנה אליהם כדי להעתיק אותם למאגר הנתונים הזמני של TCP.
[out] aWritten
מאוכלסים בכמות הנתונים שהועתקו למאגר הנתונים לשליחה, שיכול להיות קטן מ-aLength אם המאגר לשליחה מגיע לקיבולת.
[in] aFlags
סימונים המציינים אפשרויות לפעולה זו (ראו ספירה למעלה).
ערכי החזרה
OT_ERROR_NONE
הנתונים הועתקו למאגר הנתונים להעברה ושלחו אותו בנקודת הקצה של TCP.
OT_ERROR_FAILED
שליחת הנתונים בנקודת הקצה של TCP נכשלה.

otTcpMbedTlsSslRecvCallback

int otTcpMbedTlsSslRecvCallback(
  void *aCtx,
  unsigned char *aBuf,
  size_t aLen
)

קריאה חוזרת (callback) ללא חסימה היא העברה ל-mbedtls_ssl_set_bio.

פרטים
פרמטרים
[in] aCtx
[out] aBuf
האחסון הזמני שאליו יש לקבל נתונים.
[in] aLen
כמות הנתונים המקסימלית שניתן לקבל.
החזרות
מספר הבייטים שהתקבלו או קוד שגיאה של mbedtls.

otTcpMbedTlsSslSendCallback

int otTcpMbedTlsSslSendCallback(
  void *aCtx,
  const unsigned char *aBuf,
  size_t aLen
)

ביטול הקריאה החוזרת (callback) כדי לא לעבור אל mbedtls_ssl_set_bio.

פרטים
פרמטרים
[in] aCtx
[in] aBuf
הנתונים שיש להוסיף למאגר הנתונים להעברה.
[in] aLen
כמות הנתונים להוספה למאגר הנתונים לשליחה.
החזרות
מספר הבייטים שנשלחו או קוד שגיאה של mbedtls.

משאבים

הנושאים של קובצי העזר של OpenThread API מגיעים מקוד המקור, והם זמינים ב-GitHub. למידע נוסף או כדי לתרום למסמכי התיעוד שלנו, יש לעיין בקטע משאבים.