אבסטרקטיות TCP

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

סיכום

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

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

פונקציות
otTcpCircularSendBufferDeinitialize(otTcpCircularSendBuffer *aSendBuffer)	otError מבטל את האתחול של מאגר נתונים זמני של 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)	otError שולח נתונים בנקודת קצה של 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 מצביע ל-otTcpEndpointAndCircularSendBuffer. [out] aBuf המאגר שאליו יש לקבל את הנתונים. [in] aLen כמות הנתונים המקסימלית שאפשר לקבל.
החזרות	מספר הבייטים שהתקבלו, או קוד שגיאה של mbedtls.

otTcpMbedTlsSslSendCallback

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

ללא חסימה שולחים קריאה חוזרת (callback) כדי לעבור אל mbedtls_ssl_set_bio.

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

מקורות מידע

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