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

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

מבנים
otLinkedBuffer	מבנה מאגר נתונים מקושר לשימוש עם TCP.
otTcpEndpoint	מייצג נקודת קצה (endpoint) של TCP.
otTcpEndpointInitializeArgs	מכילה ארגומנטים לפונקציה otTcpEndpointInitialize().
otTcpListener	מייצג מעבד TCP.
otTcpListenerInitializeArgs	מכיל ארגומנטים לפונקציה otTcpListenerInitialize().

ספירות

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

 anonymous enum

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

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

 anonymous enum

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

otTcpDisconnectedReason

 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)

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

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

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

otTcpAcceptReady

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

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

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

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

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

otTcpDisconnected

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

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

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

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

otTcpDisconnectedReason

enum otTcpDisconnectedReason otTcpDisconnectedReason

otTcpEndpoint

struct otTcpEndpoint otTcpEndpoint

otTcpEndpointInitializeArgs

struct otTcpEndpointInitializeArgs otTcpEndpointInitializeArgs

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

otTcpEstablished

void(* otTcpEstablished)(otTcpEndpoint *aEndpoint)

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

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

otTcpForwardProgress

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

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

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

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

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

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

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

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

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

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

otTcpIncomingConnectionAction

enum otTcpIncomingConnectionAction otTcpIncomingConnectionAction

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

נעשה שימוש בערך הזה בקריאה חוזרת (callback) otTcpAcceptReady().

otTcpListener

struct otTcpListener otTcpListener

otTcpListenerInitializeArgs

struct otTcpListenerInitializeArgs otTcpListenerInitializeArgs

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

otTcpReceiveAvailable

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

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

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

מאתחלת נקודת קצה (endpoint) של TCP.

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

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

otTcpGetLocalAddress

const otSockAddr * otTcpGetLocalAddress(
  const otTcpEndpoint *aEndpoint
)

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

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

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

otTcpGetPeerAddress

const otSockAddr * otTcpGetPeerAddress(
  const otTcpEndpoint *aEndpoint
)

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

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

פרטים
פרמטרים	[in] aEndpoint נקודת הקצה של TCP שיש לקבל את המארח והיציאה של העמיתים.
החזרות	המארח והיציאה של קישור בין רשתות שכנות (peering) של 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 מצביע למבנה של מאזין TCP. [in] aArgs מצביע למבנה של ארגומנטים.
ערכים מוחזרים	OT_ERROR_NONE מאזין ה-TCP נפתח. OT_ERROR_FAILED פתיחת מאזין ה-TCP נכשלה.

otTcpReceiveByReference

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

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

רשת מאגר הנתונים הזמני המקושר תהיה בתוקף עד שהקריאה החוזרת 'קבלת מוכנה' תופעל בפעם הבאה, או עד הקריאה הבאה ל-otTcpReceiveContiguify() או ל-otTcpCommitReceive().

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

otTcpReceiveContiguify

otError otTcpReceiveContiguify(
  otTcpEndpoint *aEndpoint
)

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

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

פרטים
פרמטרים	[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 הוספת הנתונים למאגר הנתונים הזמני נכשלה.

otTcpSendByReference

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

הוספה של נתונים למאגר הנתונים הזמני שאליו מפנה מאגר הנתונים הזמני שאליו מפנה aBuffer.

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

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

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

otTcpSendEndOfStream

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_ENDPOINT_TCB_NUM_PTR

 OT_TCP_ENDPOINT_TCB_NUM_PTR 36

OT_TCP_ENDPOINT_TCB_SIZE_BASE

 OT_TCP_ENDPOINT_TCB_SIZE_BASE 392

OT_TCP_ENDPOINT_TCB_SIZE_BASE ו-OT_TCP_ENDPOINT_TCB_NUM_POINTERS נבחרים כך ששדה ה-mTcb של otTcpEndpoint יהיה זהה לגודל של struct tcpcb ב-TCPlp.

הדבר נדרש כי השדה mTcb, למרות שהוא אטום בהצהרה, מטופל כ-struct 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_POINTERS נבחרו כך שהשדה mTcbListener של otTcpListener זהה לגודלו של struct tcpcb_listen ב-TCPlp.

פעולה זו נדרשת כי השדה mTcbListen, למרות אטום בהצהרה שלו, מטופל כ-struct 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. אפשר לקרוא מידע נוסף או לתרום למסמכי התיעוד שלנו בדף מקורות מידע.