TCP

המודול הזה כולל פונקציות השולטות בתקשורת TCP.

סיכום

מספור
anonymous enum טיפוסים בני מנייה (enum)
הגדרת הסימונים שהועברו אל otTcpConnect().
anonymous enum טיפוסים בני מנייה (enum)
מגדיר סימונים שהועברו אל otTcpSendByReference.
otTcpDisconnectedReason טיפוסים בני מנייה (enum)
otTcpIncomingConnectionAction{
  OT_TCP_INCOMING_CONNECTION_ACTION_ACCEPT,
  OT_TCP_INCOMING_CONNECTION_ACTION_DEFER,
  OT_TCP_INCOMING_CONNECTION_ACTION_REFUSE
} 		טיפוסים בני מנייה (enum)
מגדיר את פעולות החיבור הנכנסות.

סוג שגיאות
otLinkedBuffer typedef
מבנה של מאגר נתונים זמני לשימוש עם TCP.
otTcpAcceptDone)(otTcpListener *aListener, otTcpEndpoint *aEndpoint, const otSockAddr *aPeer) typedef
void(*
קריאה חוזרת זו מציינת שחיבור ה-TCP מוכן כעת לתקשורת דו-כיוונית.
otTcpAcceptReady)(otTcpListener *aListener, const otSockAddr *aPeer, otTcpEndpoint **aAcceptInto) typedef
פונקציית הקריאה החוזרת הזו מציינת שהחיבור הנכנס שתואם למאזין ה-TCP הזה הגיע.
otTcpDisconnected)(otTcpEndpoint *aEndpoint, otTcpDisconnectedReason aReason) typedef
void(*
התקשרות חזרה זו מציינת שהחיבור נותק ואין להשתמש בו יותר, או שהחיבור נכנס למצב TIME-WAIT.
otTcpDisconnectedReason typedef
enum otTcpDisconnectedReason
otTcpEndpoint typedef
struct otTcpEndpoint
otTcpEndpointInitializeArgs typedef
מכיל ארגומנטים לפונקציה otTcpEndpointinitialize().
otTcpEstablished)(otTcpEndpoint *aEndpoint) typedef
void(*
הקריאה החוזרת הזו מודיעה לאפליקציה שלחיצת היד של TCP 3-כיוונית הושלמה ושעכשיו החיבור נוצר.
otTcpForwardProgress)(otTcpEndpoint *aEndpoint, size_t aInSendBuffer, size_t aBacklog) typedef
void(*
פונקציית הקריאה החוזרת מודיעה לאפליקציה אם התקדמת בתהליך העברת הנתונים ממאגר הנתונים של השליחה לנמען.
otTcpIncomingConnectionAction typedef
מגדיר את פעולות החיבור הנכנסות.
otTcpListener typedef
struct otTcpListener
otTcpListenerInitializeArgs typedef
מכיל ארגומנטים לפונקציה otTcpListenerFirstize().
otTcpReceiveAvailable)(otTcpEndpoint *aEndpoint, size_t aBytesAvailable, bool aEndOfStream, size_t aBytesRemaining) typedef
void(*
בקריאה החוזרת הזו מופיע מספר הבייטים הזמינים לצריכה ממאגר הנתונים הזמני של הקבלה.
otTcpSendDone)(otTcpEndpoint *aEndpoint, otLinkedBuffer *aData) typedef
void(*
הקריאה החוזרת הזו מודיעה לאפליקציה שנתונים ב-aData שסופקו אושרו על ידי העמית להשוואה, ושהאפליקציה והנתונים יכולים לכלול את aData ואת הנתונים שהיא מכילה.

פונקציות
otTcpAbort(otTcpEndpoint *aEndpoint)
מאלץ אילוץ של חיבור ה-TCP המשויך לנקודת הקצה הזו של TCP.
otTcpBind(otTcpEndpoint *aEndpoint, const otSockAddr *aSockName)
מחייבת את נקודת הקצה של TCP לכתובת IP וליציאה.
otTcpCommitReceive(otTcpEndpoint *aEndpoint, size_t aNumBytes, uint32_t aFlags)
פעולה זו מיידעת את מחסנית ה-TCP שבמהלכה האפליקציה סיימה לעבד נתונים של aNumBytes בייטים בתחילת האחסון הזמני, ושאין צורך במחסנית TCP להמשיך לתחזק את הבייטים האלה במאגר הנתונים הזמני.
otTcpConnect(otTcpEndpoint *aEndpoint, const otSockAddr *aSockName, uint32_t aFlags)
מתעדת את המארח והיציאה המרוחקים בחיבור הזה.
otTcpEndpointDeinitialize(otTcpEndpoint *aEndpoint)
הפעלת נקודת הקצה הזו ל-TCP.
otTcpEndpointGetContext(otTcpEndpoint *aEndpoint)
void *
קבלת מצביע ההקשר ששויך ל-aEndpoint עם האתחול.
otTcpEndpointGetInstance(otTcpEndpoint *aEndpoint)
קבלת ה-otInstance המשויך ל-aEndpoint בעת האתחול.
otTcpEndpointInitialize(otInstance *aInstance, otTcpEndpoint *aEndpoint, const otTcpEndpointInitializeArgs *aArgs)
מפעיל נקודת קצה מסוג TCP.
otTcpGetLocalAddress(const otTcpEndpoint *aEndpoint)
const otSockAddr *
קבלת מצביעים למארח וליציאה של נקודת קצה (endpoint) מקומית של TCP.
otTcpGetPeerAddress(const otTcpEndpoint *aEndpoint)
const otSockAddr *
קבלת מצביע למארח וליציאה של נקודת קצה של TCP בנקודת קצה.
otTcpListen(otTcpListener *aListener, const otSockAddr *aSockName)
המדיניות הזו גורמת לחיבורי TCP נכנסים התואמים לכתובת ה-IP וליציאה שצוינו, כדי להפעיל את הקריאה החוזרת (callback) של מאזין ה-TCP.
otTcpListenerDeinitialize(otTcpListener *aListener)
מאתחל את הקורא הזה של TCP.
otTcpListenerGetContext(otTcpListener *aListener)
void *
קבלת מצביע ההקשר ששויך ל-aListener עם האתחול.
otTcpListenerGetInstance(otTcpListener *aListener)
קבלת ה-otInstance המשויך ל-aListener בעת האתחול.
otTcpListenerInitialize(otInstance *aInstance, otTcpListener *aListener, const otTcpListenerInitializeArgs *aArgs)
מפעיל מאזין TCP.
otTcpReceiveByReference(otTcpEndpoint *aEndpoint, const otLinkedBuffer **aBuffer)
מספקת לאפליקציה שרשרת חוצץ מקושרת שמפנה לנתונים שנמצאים כרגע במאגר הנתונים הזמני.
otTcpReceiveContiguify(otTcpEndpoint *aEndpoint)
ארגון מחדש של מאגר הנתונים הזמני כך שהזיכרון יהיה רציף לחלוטין.
otTcpSendByExtension(otTcpEndpoint *aEndpoint, size_t aNumBytes, uint32_t aFlags)
המדיניות הזו מוסיפה נתונים למאגר הנתונים הזמני על ידי הארכת האורך של otLinkedBuffer במאגר הנתונים הזמני לשליחת הכמות שצוינה.
otTcpSendByReference(otTcpEndpoint *aEndpoint, otLinkedBuffer *aBuffer, uint32_t aFlags)
הפונקציה מוסיפה נתונים שהמאגר המקושר מפנה אליהם על ידי aBuffer למאגר הנתונים לשליחה.
otTcpSendEndOfStream(otTcpEndpoint *aEndpoint)
פעולה זו מודיעה לעמית לחיבור שנקודת הקצה הזו ב-TCP לא תשלח יותר נתונים.
otTcpStopListening(otTcpListener *aListener)
גורם לקורא TCP הזה להפסיק להאזין לחיבורים נכנסים.

מבנים
otLinkedBuffer

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

otTcpEndpoint

מייצג נקודת קצה מסוג TCP.

otTcpEndpointinitializeArgs

מכיל ארגומנטים לפונקציה otTcpEndpointinitialize().

otTcpListener

מייצג מאזין מסוג TCP.

otTcpListenerFirstizeArgs

מכיל ארגומנטים לפונקציה otTcpListenerFirstize().

מספור

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

 anonymous enum

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

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

 anonymous enum

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

otTcpמנותק סיבה

 otTcpDisconnectedReason

OTTcpIncomingConnectionAction

 otTcpIncomingConnectionAction

מגדיר את פעולות החיבור הנכנסות.

ההגדרה הזו משמשת בקריאה החוזרת (callback) של otTcpAcceptReady().

מאפיינים
OT_TCP_INCOMING_CONNECTION_ACTION_ACCEPT

אישור החיבור הנכנס.

OT_TCP_INCOMING_CONNECTION_ACTION_DEFER

דחיית החיבור הנכנס (ללא התעלמות).

OT_TCP_INCOMING_CONNECTION_ACTION_REFUSE

סירוב לחיבור הנכנס.

סוג שגיאות

OTLinkedBuffer

struct otLinkedBuffer otLinkedBuffer

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

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

OTTcpAcceptDone

void(* otTcpAcceptDone)(otTcpListener *aListener, otTcpEndpoint *aEndpoint, const otSockAddr *aPeer)

קריאה חוזרת זו מציינת שחיבור ה-TCP מוכן כעת לתקשורת דו-כיוונית.

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

פרטים
פרמטרים
[in] aListener
מאזין ה-TCP המתאים לחיבור הנכנס.
[in] aEndpoint
נקודת הקצה של TCP שאליה נכנס החיבור הנכנס.
[in] aPeer
המארח והיציאה שמהם הגיע החיבור הנכנס.

OTTcpAcceptReady

otTcpIncomingConnectionAction(* otTcpAcceptReady)(otTcpListener *aListener, const otSockAddr *aPeer, otTcpEndpoint **aAcceptInto)

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

התגובה האופיינית היא שהאפליקציה תקבל את החיבור הנכנס. לשם כך היא מאכלסת את aAcceptInto בהפניה ל-otTcpEndpoint שאליה מקבלת את החיבור הנכנס. יש לאתחל את ה-otTcpEndpoint באמצעות otTcpEndpointfirstize(). לאחר מכן, האפליקציה תחזיר OT_TCP_INCOMING_CONNECTION_ACTION_ACCEPT.

לחלופין, האפליקציה יכולה לסרב לקבל את החיבור הנכנס. יש שתי דרכים לעשות זאת. קודם כול, אם האפליקציה מחזירה את ההרשאה OT_TCP_INCOMING_CONNECTION_ACTION_DEFER, אז התכונה OpenThread מתעלמת באופן שקט מהבקשה ליצירת חיבור. סביר להניח שעמית החיבור יעביר את הבקשה, ובשלב הזה, הקריאה החוזרת (callback) תבוצע שוב. האפשרות הזו חשובה אם כרגע אין משאבים זמינים לחיבור, אבל הם יכולים להיות זמינים כשעמית החיבור מעביר את ניסיון ביסוס החיבור. שנית, אם היישום מחזיר את OT_TCP_INCOMING_CONNECTION_ACTION_REFUSE, OpenThread שולח הודעה "החיבור נדחה" למארח שניסה ליצור חיבור. אם האפליקציה דוחה את החיבור הנכנס, אין צורך לאכלס את aAcceptInto.

פרטים
פרמטרים
[in] aListener
מאזין ה-TCP המתאים לחיבור הנכנס.
[in] aPeer
המארח והיציאה שמהם הגיע החיבור הנכנס.
[out] aAcceptInto
נקודת הקצה של TCP שאליה יש לאשר את החיבור הנכנס.
החזרות
תיאור של אופן הטיפול בחיבור הנכנס.

OTTcp מנותק

void(* otTcpDisconnected)(otTcpEndpoint *aEndpoint, otTcpDisconnectedReason aReason)

התקשרות חזרה זו מציינת שהחיבור נותק ואין להשתמש בו יותר, או שהחיבור נכנס למצב TIME-WAIT.

מצב זה עלול להתרחש אם ניסיון ליצירת חיבור (ביוזמת קריאה ל-otTcpConnect()) נכשל, או לאחר מכן בנקודה כלשהי (למשל, אם הזמן הקצוב לתפוגה של החיבור מתנתק או אם מתקבל קטע RST מהעמית). כשהקריאה החוזרת הזו תופעל, ניתן יהיה לדרוש מחדש את כל המשאבים שהאפליקציה סיפקה לחיבור הזה (כלומר כל otLinkedBuffers והזיכרון שהם מפנים אליהם, אבל לא נקודת הקצה של TCP עצמה או מקום למאגרי הנתונים הזמניים). במקרה של חיבור שעובר למצב TIME-WAIT, הקריאה החוזרת הזו נקראת פעמיים, לאחר הכניסה למצב TIME-WAIT (עם OT_TCP_DISCONNECTED_REASON_TIME_WAIT, ופעם נוספת לאחר שהתוקף של TIME-WAIT פג (עם OT_TCP_DISCONNECTED_REASON_NORMAL).

פרטים
פרמטרים
[in] aEndpoint
נקודת הקצה של TCP שהחיבור שלה אבד.
[in] aReason
הסיבה לחיבור נותק.

otTcpמנותק סיבה

enum otTcpDisconnectedReason otTcpDisconnectedReason

נקודת OTTcpEndpoint

struct otTcpEndpoint otTcpEndpoint

otTcpEndpointinitializeArgs

struct otTcpEndpointInitializeArgs otTcpEndpointInitializeArgs

מכיל ארגומנטים לפונקציה otTcpEndpointinitialize().

OTTcp הרלוונטי

void(* otTcpEstablished)(otTcpEndpoint *aEndpoint)

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

פרטים
פרמטרים
[in] aEndpoint
נקודת הקצה של TCP שהחיבור שלה נוצר כעת.

OTTcpForwardProgress

void(* otTcpForwardProgress)(otTcpEndpoint *aEndpoint, size_t aInSendBuffer, size_t aBacklog)

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

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

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

הקריאה החוזרת (callback) מופעלת בתגובה לשני סוגי אירועים. ראשית, יכול להיות שהאזור 'בטיסה' של מאגר האחסון הזמני יוקטן (למשל, כשהנמען יאשר את הנתונים ששלחנו קודם). שנית, ייתכן שהאזור "loglog" של מאגר הנתונים הזמני יוקטן (למשל, נשלחו נתונים חדשים). שני התנאים האלה מתרחשים לעיתים קרובות בו-זמנית, בתגובה לפלח ACK מהעמית להשוואה, ולכן הם משולבים בקריאה חוזרת (callback) אחת.

מחסנית ה-TCP משתמשת רק בבייטים (aInSendBuffer) במרווח של האחסון הזמני לשליחה.כאשר aInSendBuffer פוחתת בסכום X, המשמעות היא ש-x בייטים נוספים שהיו בעבר בתחילת המאגר של השליחה, כבר לא נמצאים במאגר הנתונים הזמני של השליחה. ניתן לשחזר אותם עכשיו (כלומר, להחליף אותם). חשוב לשים לב למבנה של otLinkedBuffer, רק אחרי שהוא יקבל את כל הבייטים שהוא אינו חלק ממאגר הנתונים הזמני לשליחה שלו.

פונקציית הקריאה החוזרת הזו מסיקה את otTcpSendDone() במובן הבא: אפליקציות יכולות לקבוע מתי אפשר יהיה לדרוש חזרה במאגרי נתונים מקושרים על ידי השוואה בין aInSendBuffer למספר הבייטים בכל מאגר מקושר. עם זאת, אנחנו מצפים ש-otTcpSendDone(, שיעביר את הנתונים של otLinkedBuffers, יהיה קל יותר לשימוש. אם שתי הקריאות החוזרות (callback) רשומות ומופעלות על ידי אותו אירוע (למשל, אותו פלח ACK התקבל), הקריאה החוזרת (callTcpSendDone) תופעל תחילה ולאחר מכן הקריאה החוזרת תופיע.

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

אחרי קריאה ל-otTcpSendByReference() או ל-otTcpSendByExtension() עם מספר חיובי של בייטים, מובטח הקריאה החוזרת (callback) של otTcpForwardProgress(). היא מציינת מתי הבייטים שנוספו למאגר השליחה נשלחים. הקריאה ל-otTcpForwardProgress() עשויה להתבצע מיד לאחר הוספת הבייטים למאגר הנתונים לשליחה (אם חלק מהבייטים נשלחים באופן מיידי, מצמצמים את זמן הצבירה) או בעתיד (אחרי שהחיבור ישלח חלק מהנתונים או את כולם, תוך הפחתת התוצרים). המשמעות של "באופן מיידי" היא שהקריאה החוזרת (callback) מתוזמנת להתבצע באופן מיידי במשימה. כדי להימנע ממורכבות הקשורה להעברה חוזרת, הקריאה החוזרת (callback) otTcpForwardProgress() אף פעם לא מתבצעת ישירות מהפונקציות otTcpSendByReference() או otTcpSendByExtension().

פרטים
פרמטרים
[in] aEndpoint
נקודת הקצה ל-TCP עבור החיבור.
[in] aInSendBuffer
מספר הבייטים במאגר הנתונים הזמני לשליחת נתונים (הסכום של האזורים 'בטיסה' ו'באג').
[in] aBacklog
מספר הבייטים שממתינים בתור לשליחה אבל עדיין לא נשלחו (האזור 'loglog').

OTTcpIncomingConnectionAction

enum otTcpIncomingConnectionAction otTcpIncomingConnectionAction

מגדיר את פעולות החיבור הנכנסות.

ההגדרה הזו משמשת בקריאה החוזרת (callback) של otTcpAcceptReady().

OTTcpListener

struct otTcpListener otTcpListener

OTTcpListenerFirstizeArgs

struct otTcpListenerInitializeArgs otTcpListenerInitializeArgs

מכיל ארגומנטים לפונקציה otTcpListenerFirstize().

OTTcpReceive זמין

void(* otTcpReceiveAvailable)(otTcpEndpoint *aEndpoint, size_t aBytesAvailable, bool aEndOfStream, size_t aBytesRemaining)

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

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

פרטים
פרמטרים
[in] aEndpoint
נקודת הקצה ל-TCP עבור החיבור.
[in] aBytesAvailable
מספר הבייטים במאגר הנתונים הזמני של החיבור.
[in] aEndOfStream
מציין אם ניתן לקבל נתונים נוספים, מעבר למה שכבר נמצא במאגר הנתונים הזמני של החיבור.
[in] aBytesRemaining
מספר הבייטים הנוספים שניתן לקבל לפני שמאגר הנתונים הזמני מתמלא.

OTTcpSendDone

void(* otTcpSendDone)(otTcpEndpoint *aEndpoint, otLinkedBuffer *aData)

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

הפונקציה aData מובטחת שתהיה זהה לזו שמועברת אל TCP דרך otTcpSendByReference(), כולל תוספים שהופעלו דרך otTcpSendByExtension().

פרטים
פרמטרים
[in] aEndpoint
נקודת הקצה ל-TCP עבור החיבור.
[in] aData
מצביעים אל otLinkedBuffer שניתן לקבל חזרה עליו.

פונקציות

OTTcpAbort

otError otTcpAbort(
  otTcpEndpoint *aEndpoint
)

מאלץ אילוץ של חיבור ה-TCP המשויך לנקודת הקצה הזו של TCP.

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

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

OTTcpBind

otError otTcpBind(
  otTcpEndpoint *aEndpoint,
  const otSockAddr *aSockName
)

מחייבת את נקודת הקצה של TCP לכתובת IP וליציאה.

פרטים
פרמטרים
[in] aEndpoint
מצביע אל מבנה נקודת הקצה של TCP כדי לקשר.
[in] aSockName
הכתובת והיציאה שאליהן יש לקשר את נקודת הקצה הזו ל-TCP.
ערכי החזרה
OT_ERROR_NONE
בוצעה סגירה בהצלחה של נקודת הקצה של TCP.
OT_ERROR_FAILED
הקישור של נקודת הקצה מסוג TCP נכשל.

otTcpCommitReceive

otError otTcpCommitReceive(
  otTcpEndpoint *aEndpoint,
  size_t aNumBytes,
  uint32_t aFlags
)

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

פרטים
פרמטרים
[in] aEndpoint
מצביע למבנה של נקודת הקצה של TCP שמייצג את נקודת הקצה של TCP שעליה יתקבלו הנתונים.
[in] aNumBytes
מספר הבייטים שנצרכו.
[in] aFlags
סימונים המציינים אפשרויות לפעולה זו (עדיין לא).
ערכי החזרה
OT_ERROR_NONE
פעולת קבלת הנתונים הושלמה בהצלחה.
OT_ERROR_FAILED
השלמת פעולת הקבלה נכשלה.

OTTcpConnect

otError otTcpConnect(
  otTcpEndpoint *aEndpoint,
  const otSockAddr *aSockName,
  uint32_t aFlags
)

מתעדת את המארח והיציאה המרוחקים בחיבור הזה.

יש להפעיל או להשבית את האפשרות 'פתיחה מהירה של TCP' באמצעות aFlags. אם המאפיין מושבת, לחיצת היד של חיבור ה-TCP מופעלת באופן מיידי. אם הפונקציה מופעלת, הפונקציה הזו רק מתעדת את המארח המרוחק ואת היציאה, ולחיצת היד של חיבור ה-TCP מתקיימת רק בקריאה הראשונה ל-otTcpSendByReference().

אם האפשרות 'פתיחה מהירה של TCP' מושבתת, המתקשר חייב להמתין לקריאה החוזרת (callback) של otTcpEstablished שמציינת שלחיצת היד של חיבור TCP בוצעה לפני שניתן יהיה להתחיל לשלוח נתונים, לדוגמה, על ידי חיוג אל otTcpSendByReference().

פרטים
פרמטרים
[in] aEndpoint
מצביע אל מבנה נקודת הקצה של TCP כדי להתחבר.
[in] aSockName
כתובת ה-IP והיציאה של המארח שאליו יש להתחבר.
[in] aFlags
סימונים המציינים אפשרויות לפעולה זו (ראו ספירה למעלה).
ערכי החזרה
OT_ERROR_NONE
הפעולה הושלמה בהצלחה.
OT_ERROR_FAILED
השלמת הפעולה נכשלה.

otTcpEndpointDeinitialize

otError otTcpEndpointDeinitialize(
  otTcpEndpoint *aEndpoint
)

הפעלת נקודת הקצה הזו ל-TCP.

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

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

פרטים
פרמטרים
[in] aEndpoint
מצביע אל המבנה של נקודת הקצה מסוג TCP כדי לבטל את האתחול.
ערכי החזרה
OT_ERROR_NONE
ההפעלה של נקודת הקצה (TCP) הסתיימה בהצלחה.
OT_ERROR_FAILED
ההפעלה של נקודת הקצה מסוג TCP נכשלה.

otTcpEndpointGetContext

void * otTcpEndpointGetContext(
  otTcpEndpoint *aEndpoint
)

קבלת מצביע ההקשר ששויך ל-aEndpoint עם האתחול.

פרטים
פרמטרים
[in] aEndpoint
נקודת הקצה של TCP שיש לקבל עבורה הקשר.
החזרות
מצביע ההקשר המשויך אל aEndpoint.

otTcpEndpointGetInstance

otInstance * otTcpEndpointGetInstance(
  otTcpEndpoint *aEndpoint
)

קבלת ה-otInstance המשויך ל-aEndpoint בעת האתחול.

פרטים
פרמטרים
[in] aEndpoint
נקודת הקצה של TCP שיש לאתר את המופע שלה.
החזרות
מצביע ה-otInstance המשויך ל-aEndpoint.

otTcpEndpointinitialize

otError otTcpEndpointInitialize(
  otInstance *aInstance,
  otTcpEndpoint *aEndpoint,
  const otTcpEndpointInitializeArgs *aArgs
)

מפעיל נקודת קצה מסוג TCP.

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

פרטים
פרמטרים
[in] aInstance
מצביע למופע של OpenThread.
[in] aEndpoint
מצביע למבנה של נקודת קצה מסוג TCP.
[in] aArgs
מצביעים על מבנה ארגומנטים.
ערכי החזרה
OT_ERROR_NONE
נקודת הקצה TCP נפתחה בהצלחה.
OT_ERROR_FAILED
פתיחת נקודת הקצה של TCP נכשלה.

OTTcpGetLocalAddress

const otSockAddr * otTcpGetLocalAddress(
  const otTcpEndpoint *aEndpoint
)

קבלת מצביעים למארח וליציאה של נקודת קצה (endpoint) מקומית של TCP.

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

פרטים
פרמטרים
[in] aEndpoint
נקודת הקצה של TCP שיש להשיג את המארח המקומי ואת היציאה.
החזרות
המארח המקומי והיציאה של aEndpoint.

OTTcpGetPeerAddress

const otSockAddr * otTcpGetPeerAddress(
  const otTcpEndpoint *aEndpoint
)

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

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

פרטים
פרמטרים
[in] aEndpoint
נקודת הקצה מסוג TCP שיש לקבל את המארח והיציאה של העמית שלה.
החזרות
המארח והיציאה של שותף החיבור של aEndpoint.

OTTcpListen

otError otTcpListen(
  otTcpListener *aListener,
  const otSockAddr *aSockName
)

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

פרטים
פרמטרים
[in] aListener
מצביע למבנה ההאזנה TCP שאמור להתחיל להאזין.
[in] aSockName
הכתובת והיציאה שבהן יושמעו חיבורים נכנסים.
ערכי החזרה
OT_ERROR_NONE
ההאזנה הושלמה בהצלחה ב-TCP להאזנה.
OT_ERROR_FAILED
הפעלת ההאזנה ב-TCP נכשלה.

OTTcpListenerDeinitialize

otError otTcpListenerDeinitialize(
  otTcpListener *aListener
)

מאתחל את הקורא הזה של TCP.

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

אם מאזין ה-TCP מאזין כרגע, הוא מפסיק להאזין.

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

OTTcpListenerGetContext

void * otTcpListenerGetContext(
  otTcpListener *aListener
)

קבלת מצביע ההקשר ששויך ל-aListener עם האתחול.

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

OTTcpListenerGetInstance

otInstance * otTcpListenerGetInstance(
  otTcpListener *aListener
)

קבלת ה-otInstance המשויך ל-aListener בעת האתחול.

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

OTTcpListenerinitialize

otError otTcpListenerInitialize(
  otInstance *aInstance,
  otTcpListener *aListener,
  const otTcpListenerInitializeArgs *aArgs
)

מפעיל מאזין TCP.

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

פרטים
פרמטרים
[in] aInstance
מצביע למופע של OpenThread.
[in] aListener
מצביע למבנה listener של TCP.
[in] aArgs
מצביעים על מבנה ארגומנטים.
ערכי החזרה
OT_ERROR_NONE
פתחת את מאזין ה-TCP בהצלחה.
OT_ERROR_FAILED
נכשלה פתיחת המאזינים של TCP.

OTTcpReceiveByReference

otError otTcpReceiveByReference(
  otTcpEndpoint *aEndpoint,
  const otLinkedBuffer **aBuffer
)

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

שרשרת המאגר הזמני המקושרת תקפה עד לקריאה החוזרת (callback) של "get ready", או עד הקריאה הבאה אל otTcpReceiveContiguify() או אל otTcpCommitReceive().

פרטים
פרמטרים
[in] aEndpoint
מצביע למבנה של נקודת הקצה של TCP שמייצג את נקודת הקצה של TCP שעליה יתקבלו הנתונים.
[out] aBuffer
מצביע לשרשרת המאגר המקושר שמשויכת לנתונים שנמצאים כרגע במאגר הנתונים הזמני.
ערכי החזרה
OT_ERROR_NONE
הפעולה הושלמה בהצלחה.
OT_ERROR_FAILED
השלמת הפעולה נכשלה.

OTTcpReceiveContiguify

otError otTcpReceiveContiguify(
  otTcpEndpoint *aEndpoint
)

ארגון מחדש של מאגר הנתונים הזמני כך שהזיכרון יהיה רציף לחלוטין.

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

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

תוסף OTTcpSendByExtension

otError otTcpSendByExtension(
  otTcpEndpoint *aEndpoint,
  size_t aNumBytes,
  uint32_t aFlags
)

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

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

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

OTTSendSendByReference

otError otTcpSendByReference(
  otTcpEndpoint *aEndpoint,
  otLinkedBuffer *aBuffer,
  uint32_t aFlags
)

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

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

לתשומת ליבכם: אין לשרשר את aBuffer. השדה mNext שלו צריך להיות NULL. אם נתונים נוספים יתווספו מיד לאחר השיחה הזו, יש להשתמש בסימון OT_TCP_SEND_MORE_TO_COME כרמז להטמעה של TCP.

פרטים
פרמטרים
[in] aEndpoint
מצביע למבנה של נקודת הקצה של TCP שמייצג את נקודת הקצה של TCP שאליה יישלחו נתונים.
[in] aBuffer
מצביע לשרשרת המאגר המקושר שמקושרת לנתונים שיש להוסיף למאגר הנתונים לשליחה.
[in] aFlags
סימונים המציינים אפשרויות לפעולה זו (ראו ספירה למעלה).
ערכי החזרה
OT_ERROR_NONE
הנתונים נוספו למאגר הנתונים להעברה.
OT_ERROR_FAILED
הוספת הנתונים למאגר הנתונים הזמני נכשלה.

OTTSendSendEndOfStream

otError otTcpSendEndOfStream(
  otTcpEndpoint *aEndpoint
)

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

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

התנאי 'סוף השידור' חל רק אחרי כל הנתונים שסופקו בעבר לערימת ה-TCP לשליחה על ידי העמית לחיבור.

פרטים
פרמטרים
[in] aEndpoint
מצביע למבנה של נקודת הקצה מסוג TCP שמייצג את נקודת הקצה של TCP לכיבוי.
ערכי החזרה
OT_ERROR_NONE
נוסף בהצלחה התנאי 'סוף השידור' לשידור.
OT_ERROR_FAILED
לא ניתן להוסיף את התנאי 'סוף השידור' לשידור.

OTTcpStopListening

otError otTcpStopListening(
  otTcpListener *aListener
)

גורם לקורא TCP הזה להפסיק להאזין לחיבורים נכנסים.

פרטים
פרמטרים
[in] aListener
מצביע למבנה ההאזנה TCP שאמור להפסיק האזנה.
ערכי החזרה
OT_ERROR_NONE
האזנה בהצלחה בהאזנה באמצעות TCP.
OT_ERROR_FAILED
נכשל הניסיון להאזין ב-TCP להאזנה.

פקודות מאקרו

OT_TCP_ENDPOINTS_TCB_NUM_PTR

 OT_TCP_ENDPOINT_TCB_NUM_PTR 36

OT_TCP_ENDPOINTS_TCB_SIZE_BASE

 OT_TCP_ENDPOINT_TCB_SIZE_BASE 392

OT_TCP_ENDPOINTS_TCB_SIZE_BASE ו-OT_TCP_ENDPOINTS_TCB_NUM_POINTSERS נבחרו כך ששדה ה-mTcb של otTcpEndpoint יהיה באותו גודל כמו ה-tcpcb של ה-ב-TCPlp.

הפעולה הזו נדרשת כי השדה mTcb, למרות שהוא אטום בהצהרה, נחשב כ-tcpcb של מבנה בהטמעה של TCP.

OT_TCP_LISTENER_TCB_NUM_PTR

 OT_TCP_LISTENER_TCB_NUM_PTR 3

OT_TCP_LISTENER_TCB_SIZE_BASE

 OT_TCP_LISTENER_TCB_SIZE_BASE 16

OT_TCP_LISTENER_TCB_SIZE_BASE ו-OT_TCP_LISTENER_TCB_NUM_POINTSERS נבחרו כך ששדה ה-mTcbListener otTcpListener יהיה באותו גודל כמו מבנה tcpcb_listen ב-TCPlp.

הפעולה הזו נדרשת כי השדה mTcbListen, על אף שהוא אטום בהצהרה, נחשב כ-tcpcb של מבנה ב-TCP.

OT_TCP_RECEIVE_BUFFER_SIZE_FEW_HOPS

 OT_TCP_RECEIVE_BUFFER_SIZE_FEW_HOPS 2598

גודל מאגר הנתונים הזמני המומלץ עבור חיבורי TCP, שעוברים כ-3 מעברים אלחוטיים או פחות.

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

OT_TCP_RECEIVE_BUFFER_SIZE_MANY_HOPS

 OT_TCP_RECEIVE_BUFFER_SIZE_MANY_HOPS 4157

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

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

משאבים

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