אבסטרקטיות TCP

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

סיכום

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

מבנים
otTcpCircularSendBuffer

מייצג מאגר שליחה מעגלי לשימוש עם נקודת קצה של TCP.

otTcpEndpointAndCircularSendBuffer

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

ספירות

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

 anonymous enum

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

ערכי דף

otTcpCircularSendBuffer

struct otTcpCircularSendBuffer otTcpCircularSendBuffer

מייצג מאגר שליחה מעגלי לשימוש עם נקודת קצה של TCP.

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

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

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

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

otTcpEndpointAndCircularSendBuffer

struct otTcpEndpointAndCircularSendBuffer otTcpEndpointAndCircularSendBuffer

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

פונקציות

otTcpCircularSendBufferDeinitialize

otError otTcpCircularSendBufferDeinitialize(
  otTcpCircularSendBuffer *aSendBuffer
)

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

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

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

otTcpCircularSendBufferForceDiscardAll

void otTcpCircularSendBufferForceDiscardAll(
  otTcpCircularSendBuffer *aSendBuffer
)

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

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

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

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

otTcpCircularSendBufferGetFreeSpace

size_t otTcpCircularSendBufferGetFreeSpace(
  const otTcpCircularSendBuffer *aSendBuffer
)

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

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

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

otTcpCircularSendBufferHandleForwardProgress

void otTcpCircularSendBufferHandleForwardProgress(
  otTcpCircularSendBuffer *aSendBuffer,
  size_t aInSendBuffer
)

מבצע טיפול ספציפי בשליחה של מאגר נתונים זמני בקריאה חוזרת (callback) מסוג otTcpForwardProgress.

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

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

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

otTcpCircularSendBufferInitialize

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

מפעיל מאגר שליחה מעגלי של TCP.

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

otTcpCircularSendBufferWrite

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

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

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

הדרך היחידה "לנתק" מאגר שליחה מעגלי של TCP ונקודת קצה (endpoint) של 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. אפשר לקרוא מידע נוסף או לתרום למסמכי התיעוד שלנו בדף מקורות מידע.