TCP
המודול הזה כולל פונקציות השולטות בתקשורת TCP.
סיכום
מספור |
|
---|---|
anonymous enum
|
טיפוסים בני מנייה (enum) הגדרת הסימונים שהועברו אל otTcpConnect(). |
anonymous enum
|
טיפוסים בני מנייה (enum) מגדיר סימונים שהועברו אל otTcpSendByReference . |
otTcpDisconnectedReason
|
טיפוסים בני מנייה (enum) |
otTcpIncomingConnectionAction{
|
טיפוסים בני מנייה (enum) מגדיר את פעולות החיבור הנכנסות. |
סוג שגיאות |
|
---|---|
otLinkedBuffer
|
typedefstruct otLinkedBuffer
מבנה של מאגר נתונים זמני לשימוש עם TCP. |
otTcpAcceptDone)(otTcpListener *aListener, otTcpEndpoint *aEndpoint, const otSockAddr *aPeer)
|
typedefvoid(*
קריאה חוזרת זו מציינת שחיבור ה-TCP מוכן כעת לתקשורת דו-כיוונית. |
otTcpAcceptReady)(otTcpListener *aListener, const otSockAddr *aPeer, otTcpEndpoint **aAcceptInto)
|
typedef פונקציית הקריאה החוזרת הזו מציינת שהחיבור הנכנס שתואם למאזין ה-TCP הזה הגיע. |
otTcpDisconnected)(otTcpEndpoint *aEndpoint, otTcpDisconnectedReason aReason)
|
typedefvoid(*
התקשרות חזרה זו מציינת שהחיבור נותק ואין להשתמש בו יותר, או שהחיבור נכנס למצב TIME-WAIT. |
otTcpDisconnectedReason
|
typedefenum otTcpDisconnectedReason
|
otTcpEndpoint
|
typedefstruct otTcpEndpoint
|
otTcpEndpointInitializeArgs
|
typedefstruct otTcpEndpointInitializeArgs
מכיל ארגומנטים לפונקציה otTcpEndpointinitialize(). |
otTcpEstablished)(otTcpEndpoint *aEndpoint)
|
typedefvoid(*
הקריאה החוזרת הזו מודיעה לאפליקציה שלחיצת היד של TCP 3-כיוונית הושלמה ושעכשיו החיבור נוצר. |
otTcpForwardProgress)(otTcpEndpoint *aEndpoint, size_t aInSendBuffer, size_t aBacklog)
|
typedefvoid(*
פונקציית הקריאה החוזרת מודיעה לאפליקציה אם התקדמת בתהליך העברת הנתונים ממאגר הנתונים של השליחה לנמען. |
otTcpIncomingConnectionAction
|
typedef מגדיר את פעולות החיבור הנכנסות. |
otTcpListener
|
typedefstruct otTcpListener
|
otTcpListenerInitializeArgs
|
typedefstruct otTcpListenerInitializeArgs
מכיל ארגומנטים לפונקציה otTcpListenerFirstize(). |
otTcpReceiveAvailable)(otTcpEndpoint *aEndpoint, size_t aBytesAvailable, bool aEndOfStream, size_t aBytesRemaining)
|
typedefvoid(*
בקריאה החוזרת הזו מופיע מספר הבייטים הזמינים לצריכה ממאגר הנתונים הזמני של הקבלה. |
otTcpSendDone)(otTcpEndpoint *aEndpoint, otLinkedBuffer *aData)
|
typedefvoid(*
הקריאה החוזרת הזו מודיעה לאפליקציה שנתונים ב- 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
מגדיר סימונים שהועברו אל 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.
פרטים | |||||||
---|---|---|---|---|---|---|---|
פרמטרים |
|
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
.
פרטים | |||||||
---|---|---|---|---|---|---|---|
פרמטרים |
|
||||||
החזרות |
תיאור של אופן הטיפול בחיבור הנכנס.
|
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).
פרטים | |||||
---|---|---|---|---|---|
פרמטרים |
|
otTcpמנותק סיבה
enum otTcpDisconnectedReason otTcpDisconnectedReason
נקודת OTTcpEndpoint
struct otTcpEndpoint otTcpEndpoint
otTcpEndpointinitializeArgs
struct otTcpEndpointInitializeArgs otTcpEndpointInitializeArgs
מכיל ארגומנטים לפונקציה otTcpEndpointinitialize().
OTTcp הרלוונטי
void(* otTcpEstablished)(otTcpEndpoint *aEndpoint)
הקריאה החוזרת הזו מודיעה לאפליקציה שלחיצת היד של TCP 3-כיוונית הושלמה ושעכשיו החיבור נוצר.
פרטים | |||
---|---|---|---|
פרמטרים |
|
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().
פרטים | |||||||
---|---|---|---|---|---|---|---|
פרמטרים |
|
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
מציין כמה קיבולת נשארת במאגר הנתונים הזמני כדי להכיל נתונים נוספים שיתקבלו.
פרטים | |||||||||
---|---|---|---|---|---|---|---|---|---|
פרמטרים |
|
OTTcpSendDone
void(* otTcpSendDone)(otTcpEndpoint *aEndpoint, otLinkedBuffer *aData)
הקריאה החוזרת הזו מודיעה לאפליקציה שנתונים ב-aData
שסופקו אושרו על ידי העמית להשוואה, ושהאפליקציה והנתונים יכולים לכלול את aData
ואת הנתונים שהיא מכילה.
הפונקציה aData
מובטחת שתהיה זהה לזו שמועברת אל TCP דרך otTcpSendByReference(), כולל תוספים שהופעלו דרך otTcpSendByExtension().
פרטים | |||||
---|---|---|---|---|---|
פרמטרים |
|
פונקציות
OTTcpAbort
otError otTcpAbort( otTcpEndpoint *aEndpoint )
מאלץ אילוץ של חיבור ה-TCP המשויך לנקודת הקצה הזו של TCP.
פעולה זו הופכת את נקודת הקצה של TCP ללא תשלום לשימוש בחיבור אחר, ומוחקת את השליחה והמאגר של הנתונים, ומעבירה את הבעלות על הנתונים שסופקו על ידי האפליקציה בקריאות otTcpSendByReference() ו-otTcpSendByExtension(). הקריאה החוזרת (callback) של הזיכרון ונקודת הקצה של TCP למאגר הנתונים הזמני של ה-TCP משויכות לנקודת הקצה של TCP.
פרטים | |||||
---|---|---|---|---|---|
פרמטרים |
|
||||
ערכי החזרה |
|
OTTcpBind
otError otTcpBind( otTcpEndpoint *aEndpoint, const otSockAddr *aSockName )
מחייבת את נקודת הקצה של TCP לכתובת IP וליציאה.
פרטים | |||||
---|---|---|---|---|---|
פרמטרים |
|
||||
ערכי החזרה |
|
otTcpCommitReceive
otError otTcpCommitReceive( otTcpEndpoint *aEndpoint, size_t aNumBytes, uint32_t aFlags )
פעולה זו מיידעת את מחסנית ה-TCP שבמהלכה האפליקציה סיימה לעבד נתונים של aNumBytes
בייטים בתחילת האחסון הזמני, ושאין צורך במחסנית TCP להמשיך לתחזק את הבייטים האלה במאגר הנתונים הזמני.
פרטים | |||||||
---|---|---|---|---|---|---|---|
פרמטרים |
|
||||||
ערכי החזרה |
|
OTTcpConnect
otError otTcpConnect( otTcpEndpoint *aEndpoint, const otSockAddr *aSockName, uint32_t aFlags )
מתעדת את המארח והיציאה המרוחקים בחיבור הזה.
יש להפעיל או להשבית את האפשרות 'פתיחה מהירה של TCP' באמצעות aFlags
. אם המאפיין מושבת, לחיצת היד של חיבור ה-TCP מופעלת באופן מיידי. אם הפונקציה מופעלת, הפונקציה הזו רק מתעדת את המארח המרוחק ואת היציאה, ולחיצת היד של חיבור ה-TCP מתקיימת רק בקריאה הראשונה ל-otTcpSendByReference()
.
אם האפשרות 'פתיחה מהירה של TCP' מושבתת, המתקשר חייב להמתין לקריאה החוזרת (callback) של otTcpEstablished
שמציינת שלחיצת היד של חיבור TCP בוצעה לפני שניתן יהיה להתחיל לשלוח נתונים, לדוגמה, על ידי חיוג אל otTcpSendByReference()
.
פרטים | |||||||
---|---|---|---|---|---|---|---|
פרמטרים |
|
||||||
ערכי החזרה |
|
otTcpEndpointDeinitialize
otError otTcpEndpointDeinitialize( otTcpEndpoint *aEndpoint )
הפעלת נקודת הקצה הזו ל-TCP.
פירוש הדבר הוא ש-OpenThread לא עוקב יותר אחרי נקודת הקצה הזו ב-TCP, ומאתר כל המשאבים שהוא הקצה באופן פנימי עבור נקודת הקצה הזו ב-TCP. האפליקציה יכולה לעשות שימוש חוזר בזיכרון שמגבה את נקודת הקצה של TCP, כרצונך.
אם היא תואמת לחיבור TCP פעיל, החיבור מסתיים ללא משמעות (כמו ב-otTcpAbort()). כל המשאבים שהאפליקציה סיפקה לנקודת הקצה הזו של TCP (מאגרים זמניים למאגר הנתונים לשליחה, זיכרון למאגר הנתונים הזמני, המבנה aEndpoint
וכו') מוחזרים מיד לאפליקציה.
פרטים | |||||
---|---|---|---|---|---|
פרמטרים |
|
||||
ערכי החזרה |
|
otTcpEndpointGetContext
void * otTcpEndpointGetContext( otTcpEndpoint *aEndpoint )
קבלת מצביע ההקשר ששויך ל-aEndpoint
עם האתחול.
פרטים | |||
---|---|---|---|
פרמטרים |
|
||
החזרות |
מצביע ההקשר המשויך אל
aEndpoint . |
otTcpEndpointGetInstance
otInstance * otTcpEndpointGetInstance( otTcpEndpoint *aEndpoint )
קבלת ה-otInstance המשויך ל-aEndpoint
בעת האתחול.
פרטים | |||
---|---|---|---|
פרמטרים |
|
||
החזרות |
מצביע ה-otInstance המשויך ל-
aEndpoint . |
otTcpEndpointinitialize
otError otTcpEndpointInitialize( otInstance *aInstance, otTcpEndpoint *aEndpoint, const otTcpEndpointInitializeArgs *aArgs )
מפעיל נקודת קצה מסוג TCP.
קריאה לפונקציה הזו גורמת ל-OpenThread לעקוב אחרי נקודת הקצה של TCP ולאחסן ולאחזר נתוני TCP בתוך aEndpoint
. יש להימנע מהאפליקציה לגשת ישירות לשדות ב-aEndpoint
או לשנות אותם. אם האפליקציה צריכה להפעיל מחדש את גיבוי הזיכרון (aEndpoint
), היא אמורה לקרוא ל-otTcpEndpointDeinitialize().
פרטים | |||||||
---|---|---|---|---|---|---|---|
פרמטרים |
|
||||||
ערכי החזרה |
|
OTTcpGetLocalAddress
const otSockAddr * otTcpGetLocalAddress( const otTcpEndpoint *aEndpoint )
קבלת מצביעים למארח וליציאה של נקודת קצה (endpoint) מקומית של TCP.
יכול להיות שתוכן המארח והיציאה לא פעיל אם השקע הזה לא במצב מחובר ולא כובש לאחר הניתוק האחרון.
פרטים | |||
---|---|---|---|
פרמטרים |
|
||
החזרות |
המארח המקומי והיציאה של
aEndpoint . |
OTTcpGetPeerAddress
const otSockAddr * otTcpGetPeerAddress( const otTcpEndpoint *aEndpoint )
קבלת מצביע למארח וליציאה של נקודת קצה של TCP בנקודת קצה.
ייתכן שתוכן המארח והיציאה לא עדכני אם השקע הזה לא במצב מחובר.
פרטים | |||
---|---|---|---|
פרמטרים |
|
||
החזרות |
המארח והיציאה של שותף החיבור של
aEndpoint . |
OTTcpListen
otError otTcpListen( otTcpListener *aListener, const otSockAddr *aSockName )
המדיניות הזו גורמת לחיבורי TCP נכנסים התואמים לכתובת ה-IP וליציאה שצוינו, כדי להפעיל את הקריאה החוזרת (callback) של מאזין ה-TCP.
פרטים | |||||
---|---|---|---|---|---|
פרמטרים |
|
||||
ערכי החזרה |
|
OTTcpListenerDeinitialize
otError otTcpListenerDeinitialize( otTcpListener *aListener )
מאתחל את הקורא הזה של TCP.
פירוש הדבר הוא ש-OpenThread לא עוקב יותר אחרי ה-TCP של ההאזנה הזו ומאתר את כל המשאבים שהוא הקצה באופן פנימי למאזין ה-TCP הזה. האפליקציה יכולה לעשות שימוש חוזר בזיכרון המגבה עבור מאזינים ל-TCP, כרצונך.
אם מאזין ה-TCP מאזין כרגע, הוא מפסיק להאזין.
פרטים | |||||
---|---|---|---|---|---|
פרמטרים |
|
||||
ערכי החזרה |
|
OTTcpListenerGetContext
void * otTcpListenerGetContext( otTcpListener *aListener )
קבלת מצביע ההקשר ששויך ל-aListener
עם האתחול.
פרטים | |||
---|---|---|---|
פרמטרים |
|
||
החזרות |
מצביע ההקשר המשויך אל
aListener . |
OTTcpListenerGetInstance
otInstance * otTcpListenerGetInstance( otTcpListener *aListener )
קבלת ה-otInstance המשויך ל-aListener
בעת האתחול.
פרטים | |||
---|---|---|---|
פרמטרים |
|
||
החזרות |
מצביע ה-otInstance המשויך ל-
aListener . |
OTTcpListenerinitialize
otError otTcpListenerInitialize( otInstance *aInstance, otTcpListener *aListener, const otTcpListenerInitializeArgs *aArgs )
מפעיל מאזין TCP.
קריאה לפונקציה הזו גורמת ל-OpenThread לעקוב אחרי מאזינים TCP ולאחסן ולאחזר נתוני TCP בתוך aListener
. יש להימנע מהאפליקציה לגשת ישירות לשדות ב-aListener
או לשנות אותם. אם האפליקציה צריכה להחזיר את זיכרון הגיבוי aListener
, היא אמורה לקרוא ל-otTcpListenerDeinitialize().
פרטים | |||||||
---|---|---|---|---|---|---|---|
פרמטרים |
|
||||||
ערכי החזרה |
|
OTTcpReceiveByReference
otError otTcpReceiveByReference( otTcpEndpoint *aEndpoint, const otLinkedBuffer **aBuffer )
מספקת לאפליקציה שרשרת חוצץ מקושרת שמפנה לנתונים שנמצאים כרגע במאגר הנתונים הזמני.
שרשרת המאגר הזמני המקושרת תקפה עד לקריאה החוזרת (callback) של "get ready", או עד הקריאה הבאה אל otTcpReceiveContiguify() או אל otTcpCommitReceive().
פרטים | |||||
---|---|---|---|---|---|
פרמטרים |
|
||||
ערכי החזרה |
|
OTTcpReceiveContiguify
otError otTcpReceiveContiguify( otTcpEndpoint *aEndpoint )
ארגון מחדש של מאגר הנתונים הזמני כך שהזיכרון יהיה רציף לחלוטין.
פעולה זו היא אופציונלית. אפליקציה יכולה פשוט לעבור את שרשרת המאגר המקושרת שנוצרה על ידי קריאה ל-otTcpReceiveByReference
. יכול להיות שחלק מהאפליקציות יבקשו להפעיל את הפונקציה הזו כדי ש מאגר הנתונים הזמני יהיה רציף כדי לעבד את הנתונים בצורה פשוטה יותר, אבל זה בא על חשבון הזמן של המעבד כדי לסדר מחדש את הנתונים במאגר הנתונים הזמני.
פרטים | |||||
---|---|---|---|---|---|
פרמטרים |
|
||||
ערכי החזרה |
|
תוסף OTTcpSendByExtension
otError otTcpSendByExtension( otTcpEndpoint *aEndpoint, size_t aNumBytes, uint32_t aFlags )
המדיניות הזו מוסיפה נתונים למאגר הנתונים הזמני על ידי הארכת האורך של otLinkedBuffer במאגר הנתונים הזמני לשליחת הכמות שצוינה.
אם האחסון הזמני של השליחה ריק, הפעולה תיכשל.
פרטים | |||||||
---|---|---|---|---|---|---|---|
פרמטרים |
|
||||||
ערכי החזרה |
|
OTTSendSendByReference
otError otTcpSendByReference( otTcpEndpoint *aEndpoint, otLinkedBuffer *aBuffer, uint32_t aFlags )
הפונקציה מוסיפה נתונים שהמאגר המקושר מפנה אליהם על ידי aBuffer
למאגר הנתונים לשליחה.
אחרי קריאה מוצלחת לפונקציה הזו, המאגר המקושר והנתונים שאליהם הוא מפנה הם בבעלות מחסנית TCP; אין לשנות אותם באפליקציה עד שהקריאה החוזרת "שליחה בוצעה" תחזיר את הבעלות על האובייקטים האלה לאפליקציה. אפשר לקרוא לפונקציה הזו כדי להוסיף עוד מאגר מקושר ל'הבאים בתור' לשליחה, גם אם הקריאה החוזרת ('call) הסתיימה' עבור הפעלה קודמת של הפונקציה הזו עדיין לא הופעלה.
לתשומת ליבכם: אין לשרשר את aBuffer
. השדה mNext שלו צריך להיות NULL. אם נתונים נוספים יתווספו מיד לאחר השיחה הזו, יש להשתמש בסימון OT_TCP_SEND_MORE_TO_COME כרמז להטמעה של TCP.
פרטים | |||||||
---|---|---|---|---|---|---|---|
פרמטרים |
|
||||||
ערכי החזרה |
|
OTTSendSendEndOfStream
otError otTcpSendEndOfStream( otTcpEndpoint *aEndpoint )
פעולה זו מודיעה לעמית לחיבור שנקודת הקצה הזו ב-TCP לא תשלח יותר נתונים.
יש להשתמש בהגדרה זו כאשר אין לאפליקציה יותר נתונים לשליחה לעמית לחיבור. עבור חיבור זה, קריאות עתידיות אצל העמיתים לחיבור יסתיימו במצב 'סוף השידור', וכתיבה עתידית בנקודת הקצה הזו תיכשל.
התנאי 'סוף השידור' חל רק אחרי כל הנתונים שסופקו בעבר לערימת ה-TCP לשליחה על ידי העמית לחיבור.
פרטים | |||||
---|---|---|---|---|---|
פרמטרים |
|
||||
ערכי החזרה |
|
OTTcpStopListening
otError otTcpStopListening( otTcpListener *aListener )
גורם לקורא 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. למידע נוסף או כדי לתרום למסמכי התיעוד שלנו, יש לעיין בקטע משאבים.