TCP

Dieses Modul enthält Funktionen, die die TCP-Kommunikation steuern.

Zusammenfassung

Aufzählungen
anonymous enum enum
Definiert Flags, die an otTcpConnect() übergeben werden.
anonymous enum enum
Definiert an otTcpSendByReference übergebene Flags.
otTcpDisconnectedReason enum
otTcpIncomingConnectionAction{
  OT_TCP_INCOMING_CONNECTION_ACTION_ACCEPT,
  OT_TCP_INCOMING_CONNECTION_ACTION_DEFER,
  OT_TCP_INCOMING_CONNECTION_ACTION_REFUSE
} 		enum
Definiert eingehende Verbindungsaktionen.

Typedefs
otLinkedBuffer typedef
Eine verknüpfte Pufferstruktur zur Verwendung mit TCP.
otTcpAcceptDone)(otTcpListener *aListener, otTcpEndpoint *aEndpoint, const otSockAddr *aPeer) typedef
void(*
Dieser Callback zeigt an, dass die TCP-Verbindung jetzt für die Zwei-Wege-Kommunikation bereit ist.
otTcpAcceptReady)(otTcpListener *aListener, const otSockAddr *aPeer, otTcpEndpoint **aAcceptInto) typedef
Dieser Callback gibt an, dass eine eingehende Verbindung, die mit diesem TCP-Listener übereinstimmt, angekommen ist.
otTcpDisconnected)(otTcpEndpoint *aEndpoint, otTcpDisconnectedReason aReason) typedef
void(*
Dieser Callback zeigt an, dass die Verbindung unterbrochen wurde und nicht mehr verwendet werden sollte oder dass eine Verbindung in den Status TIME-WAIT gewechselt ist.
otTcpDisconnectedReason typedef
enum otTcpDisconnectedReason
otTcpEndpoint typedef
struct otTcpEndpoint
otTcpEndpointInitializeArgs typedef
Enthält Argumente für die Funktion otTcpEndpointInitialize().
otTcpEstablished)(otTcpEndpoint *aEndpoint) typedef
void(*
Dieser Callback informiert die Anwendung, dass der 3-Wege-Handshake abgeschlossen ist und die Verbindung nun hergestellt ist.
otTcpForwardProgress)(otTcpEndpoint *aEndpoint, size_t aInSendBuffer, size_t aBacklog) typedef
void(*
Dieser Callback informiert die Anwendung darüber, ob bei der Übertragung von Daten aus dem Sendepuffer an den Empfänger Fortschritte gemacht wurden.
otTcpIncomingConnectionAction typedef
Definiert eingehende Verbindungsaktionen.
otTcpListener typedef
struct otTcpListener
otTcpListenerInitializeArgs typedef
Enthält Argumente für die Funktion otTcpListenerInitialize().
otTcpReceiveAvailable)(otTcpEndpoint *aEndpoint, size_t aBytesAvailable, bool aEndOfStream, size_t aBytesRemaining) typedef
void(*
Dieser Callback gibt die Anzahl der Byte an, die für den Verbrauch aus dem Empfangspuffer verfügbar sind.
otTcpSendDone)(otTcpEndpoint *aEndpoint, otLinkedBuffer *aData) typedef
void(*
Dieser Callback informiert die Anwendung, dass die Daten im bereitgestellten aData vom Verbindungs-Peer bestätigt wurden und dass aData und die darin enthaltenen Daten von der Anwendung zurückgefordert werden können.

Funktionen
otTcpAbort(otTcpEndpoint *aEndpoint)
Beendet die mit diesem TCP-Endpunkt verknüpfte TCP-Verbindung zwangsweise.
otTcpBind(otTcpEndpoint *aEndpoint, const otSockAddr *aSockName)
Bindet den TCP-Endpunkt an eine IP-Adresse und einen Port.
otTcpCommitReceive(otTcpEndpoint *aEndpoint, size_t aNumBytes, uint32_t aFlags)
Informiert den TCP-Stack, dass die Anwendung aNumBytes Byte an Daten zu Beginn des Empfangspuffers verarbeitet hat und dass der TCP-Stack diese Byte nicht mehr im Empfangspuffer beibehalten muss.
otTcpConnect(otTcpEndpoint *aEndpoint, const otSockAddr *aSockName, uint32_t aFlags)
Zeichnet den Remote-Host und -Port für diese Verbindung auf.
otTcpEndpointDeinitialize(otTcpEndpoint *aEndpoint)
Deinitialisiert diesen TCP-Endpunkt.
otTcpEndpointGetContext(otTcpEndpoint *aEndpoint)
void *
Ruft den Kontextzeiger ab, der bei der Initialisierung mit aEndpoint verknüpft wurde.
otTcpEndpointGetInstance(otTcpEndpoint *aEndpoint)
Ruft die otInstance ab, die bei der Initialisierung mit aEndpoint verknüpft wurde.
otTcpEndpointInitialize(otInstance *aInstance, otTcpEndpoint *aEndpoint, const otTcpEndpointInitializeArgs *aArgs)
Initialisiert einen TCP-Endpunkt.
otTcpGetLocalAddress(const otTcpEndpoint *aEndpoint)
const otSockAddr *
Ruft einen Zeiger auf den lokalen Host und den Port eines TCP-Endpunkts ab.
otTcpGetPeerAddress(const otTcpEndpoint *aEndpoint)
const otSockAddr *
Ruft einen Zeiger auf den Host und Port des Peers eines TCP-Endpunkts ab.
otTcpListen(otTcpListener *aListener, const otSockAddr *aSockName)
Veranlasst, dass eingehende TCP-Verbindungen, die der angegebenen IP-Adresse und dem angegebenen Port entsprechen, die Callbacks dieses TCP-Listeners auslösen.
otTcpListenerDeinitialize(otTcpListener *aListener)
Deinitialisiert diesen TCP-Listener.
otTcpListenerGetContext(otTcpListener *aListener)
void *
Ruft den Kontextzeiger ab, der bei der Initialisierung mit aListener verknüpft wurde.
otTcpListenerGetInstance(otTcpListener *aListener)
Ruft die otInstance ab, die bei der Initialisierung mit aListener verknüpft wurde.
otTcpListenerInitialize(otInstance *aInstance, otTcpListener *aListener, const otTcpListenerInitializeArgs *aArgs)
Initialisiert einen TCP-Listener.
otTcpReceiveByReference(otTcpEndpoint *aEndpoint, const otLinkedBuffer **aBuffer)
Stellt der Anwendung eine verknüpfte Pufferkette bereit, die auf Daten verweist, die sich derzeit im TCP-Empfangspuffer befinden.
otTcpReceiveContiguify(otTcpEndpoint *aEndpoint)
Ordnet den Empfangspuffer neu an, sodass er im Speicher vollständig zusammenhängend ist.
otTcpSendByExtension(otTcpEndpoint *aEndpoint, size_t aNumBytes, uint32_t aFlags)
Fügt Daten zum Sendepuffer hinzu, indem die Länge des endgültigen otLinkedBuffer im Sendepuffer um die angegebene Menge erweitert wird.
otTcpSendByReference(otTcpEndpoint *aEndpoint, otLinkedBuffer *aBuffer, uint32_t aFlags)
Fügt dem Sendepuffer Daten hinzu, auf die vom verknüpften Puffer verwiesen wird, auf den aBuffer verweist.
otTcpSendEndOfStream(otTcpEndpoint *aEndpoint)
Informiert den Verbindungs-Peer, dass dieser TCP-Endpunkt keine weiteren Daten sendet.
otTcpStopListening(otTcpListener *aListener)
Bewirkt, dass dieser TCP-Listener eingehende Verbindungen nicht mehr überwacht.

Strukturen
otLinkedBuffer

Eine verknüpfte Pufferstruktur zur Verwendung mit TCP.

otTcpEndpoint

Stellt einen TCP-Endpunkt dar.

otTcpEndpointInitializeArgs

Enthält Argumente für die Funktion otTcpEndpointInitialize().

otTcpListener

Stellt einen TCP-Listener dar.

otTcpListenerInitializeArgs

Enthält Argumente für die Funktion otTcpListenerInitialize().

Aufzählungen

Anonyme Aufzählung

 anonymous enum

Definiert Flags, die an otTcpConnect() übergeben werden.

Anonyme Aufzählung

 anonymous enum

Definiert an otTcpSendByReference übergebene Flags.

otTcpDisconnectedReason

 otTcpDisconnectedReason

otTcpIncomingConnectionAction

 otTcpIncomingConnectionAction

Definiert eingehende Verbindungsaktionen.

Wird im otTcpAcceptReady()-Callback verwendet.

Attribute
OT_TCP_INCOMING_CONNECTION_ACTION_ACCEPT

Akzeptieren Sie die eingehende Verbindung.

OT_TCP_INCOMING_CONNECTION_ACTION_DEFER

Eingehende Verbindung zurückstellen (ohne Ton ignorieren)

OT_TCP_INCOMING_CONNECTION_ACTION_REFUSE

Lehnen Sie die eingehende Verbindung ab.

Typedefs

otLinkedBuffer

struct otLinkedBuffer otLinkedBuffer

Eine verknüpfte Pufferstruktur zur Verwendung mit TCP.

Eine einzelne otLinkedBuffer-Struktur verweist über mData und mLength auf ein Array von Byte im Speicher. Das Feld „mNext“ wird verwendet, um eine Kette von otLinkedBuffer-Strukturen zu bilden.

otTcpAcceptDone

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

Dieser Callback zeigt an, dass die TCP-Verbindung jetzt für die Zwei-Wege-Kommunikation bereit ist.

Im Fall von TCP Fast Open kann dies geschehen, bevor der TCP-Verbindungs-Handshake tatsächlich abgeschlossen ist. Die Anwendung erhält die Kontextzeiger sowohl für den TCP-Listener, der die Verbindung akzeptiert hat, als auch für den TCP-Endpunkt, an dem sie akzeptiert wurde. Der bereitgestellte Kontext ist der Kontext, der dem TCP-Listener zugeordnet ist.

Details
Parameter
[in] aListener
Der TCP-Listener, der der eingehenden Verbindung entspricht.
[in] aEndpoint
Der TCP-Endpunkt, zu dem die eingehende Verbindung angenommen wurde.
[in] aPeer
Host und Port, von dem die eingehende Verbindung stammt.

otTcpAcceptReady

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

Dieser Callback gibt an, dass eine eingehende Verbindung, die mit diesem TCP-Listener übereinstimmt, angekommen ist.

In der Regel akzeptiert die Anwendung die eingehende Verbindung. Dazu wird aAcceptInto mit einem Zeiger auf den otTcpEndpoint gefüllt, in den die eingehende Verbindung akzeptiert wird. Dieser otTcpEndpoint muss bereits mit otTcpEndpointInitialize() initialisiert sein. Die Anwendung gibt dann OT_TCP_INCOMING_CONNECTION_ACTION_ACCEPT zurück.

Alternativ kann die Anwendung die Annahme der eingehenden Verbindung ablehnen. Die Anwendung kann dies auf zwei Arten tun. Erstens: Wenn die Anwendung OT_TCP_INCOMING_CONNECTION_ACTION_DEFER zurückgibt, ignoriert OpenThread die Anfrage zum Aufbau der Verbindung ohne Rückmeldung. Der Verbindungs-Peer wird die Anfrage wahrscheinlich noch einmal übertragen, woraufhin der Callback noch einmal aufgerufen wird. Dies ist nützlich, wenn Ressourcen derzeit nicht für die Verbindung zur Verfügung stehen, aber möglicherweise verfügbar sind, wenn der Verbindungs-Peer den Verbindungsversuch noch einmal überträgt. Zweitens: Wenn die Anwendung OT_TCP_INCOMING_CONNECTION_ACTION_REFUSE zurückgibt, sendet OpenThread eine „Verbindung verweigert“-Nachricht an den Host, der versucht hat, eine Verbindung herzustellen. Wenn die Anwendung die eingehende Verbindung ablehnt, muss aAcceptInto nicht ausgefüllt werden.

Details
Parameter
[in] aListener
Der TCP-Listener, der der eingehenden Verbindung entspricht.
[in] aPeer
Der Host und der Port, von dem die eingehende Verbindung stammt.
[out] aAcceptInto
Der TCP-Endpunkt, zu dem die eingehende Verbindung angenommen werden soll.
Rückgabe
Beschreibung der Handhabung der eingehenden Verbindung.

otTcpDisconnected

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

Dieser Callback zeigt an, dass die Verbindung unterbrochen wurde und nicht mehr verwendet werden sollte oder dass eine Verbindung in den Status TIME-WAIT gewechselt ist.

Sie kann auftreten, wenn ein Versuch zum Aufbau der Verbindung (durch Aufrufen von otTcpConnect() initiiert) fehlschlägt oder an einem beliebigen Punkt danach (z.B. wenn die Verbindung abläuft oder ein RST-Segment vom Verbindungs-Peer empfangen wird). Sobald dieser Callback ausgelöst wird, können alle Ressourcen freigegeben werden, die die Anwendung für diese Verbindung bereitgestellt hat (d.h. alle otLinkedBuffers und Arbeitsspeicher, auf die sie verweisen, aber nicht der TCP-Endpunkt selbst oder Speicherplatz für die Empfangspuffer). Bei einer Verbindung, die in den Status TIME-WAIT übergeht, wird dieser Callback zweimal aufgerufen: einmal beim Eintritt in den TIME-WAIT-Status (mit OT_TCP_DISCONNECTED_REASON_TIME_WAIT und ein weiteres Mal, wenn der Status TIME-WAIT abläuft (mit OT_TCP_DISCONNECTED_REASON_NORMAL).

Details
Parameter
[in] aEndpoint
Der TCP-Endpunkt, dessen Verbindung unterbrochen wurde.
[in] aReason
Der Grund, warum die Verbindung unterbrochen wurde.

otTcpDisconnectedReason

enum otTcpDisconnectedReason otTcpDisconnectedReason

otTcpEndpoint

struct otTcpEndpoint otTcpEndpoint

otTcpEndpointInitializeArgs

struct otTcpEndpointInitializeArgs otTcpEndpointInitializeArgs

Enthält Argumente für die Funktion otTcpEndpointInitialize().

otTcpEstablished

void(* otTcpEstablished)(otTcpEndpoint *aEndpoint)

Dieser Callback informiert die Anwendung, dass der 3-Wege-Handshake abgeschlossen ist und die Verbindung nun hergestellt ist.

Details
Parameter
[in] aEndpoint
Der TCP-Endpunkt, dessen Verbindung jetzt hergestellt ist.

otTcpForwardProgress

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

Dieser Callback informiert die Anwendung darüber, ob bei der Übertragung von Daten aus dem Sendepuffer an den Empfänger Fortschritte gemacht wurden.

Dieser Callback ist für einen korrekten TCP-Vorgang nicht erforderlich. Die meisten Anwendungen können sich einfach auf den otTcpSendDone()-Callback verlassen, um verknüpfte Puffer zurückzufordern, sobald der TCP-Stack diese nicht mehr verwendet hat. Zweck dieses Callbacks ist die Unterstützung erweiterter Anwendungen, die von detaillierteren Informationen darüber profitieren, wie die Verbindung bei der Datenübertragung zum Verbindungs-Peer voranschreitet.

Die Operation dieses Callbacks ist eng mit dem Sendepuffer von TCP verbunden. Der Sendepuffer umfasst zwei Regionen. Zuerst befindet sich die „In-Flight“-Region am Anfang des Sendepuffers (vorne). Sie entspricht Daten, die an den Empfänger gesendet, aber noch nicht bestätigt wurden. Zweitens gibt es die Region „Backlog“, die aus allen Daten im Sendepuffer besteht, die sich nicht in der Region „In-Flight“ befinden. Der Bereich „Rückstand“ entspricht den Daten, die zum Senden in die Warteschlange gestellt, aber noch nicht gesendet wurden.

Der Callback wird als Reaktion auf zwei Ereignistypen aufgerufen. Erstens: Die „In-Flight“-Region des Sendepuffers kann kleiner werden, z.B. wenn der Empfänger Daten bestätigt, die wir zuvor gesendet haben. Zweitens kann der „Backlog“-Bereich des Sendepuffers kleiner werden (z.B., weil neue Daten gesendet wurden). Diese beiden Bedingungen treten häufig gleichzeitig als Reaktion auf ein ACK-Segment des Verbindungs-Peers auf, weshalb sie in einem einzigen Callback kombiniert werden.

Der TCP-Stack verwendet nur die aInSendBuffer Byte am Ende des Sendepuffers. Wenn aInSendBuffer um den Wert x sinkt, bedeutet dies, dass x zusätzliche Byte, die zuvor am Anfang des Sendepuffers standen, nicht mehr Teil des Sendepuffers sind und jetzt von der Anwendung zurückgefordert (d. h. überschrieben) werden können. Die Struktur otLinkedBuffer kann erst zurückgefordert werden, wenn alle Byte, auf die sie verweist, nicht mehr Teil des Sendepuffers sind.

Dieser Rückruf umfasst otTcpSendDone() in folgendem Sinne: Anwendungen können bestimmen, wann verknüpfte Puffer zurückgefordert werden können, indem aInSendBuffer mit der Anzahl der Byte in jedem verknüpften Puffer verglichen wird. Wir gehen jedoch davon aus, dass otTcpSendDone(), das direkt angibt, welche otLinkedBuffers zurückgefordert werden können, wesentlich einfacher zu verwenden ist. Wenn beide Callbacks registriert und durch dasselbe Ereignis ausgelöst werden (z.B. dasselbe ACK-Segment empfangen), wird zuerst der otTcpSendDone()-Callback und dann dieser Callback ausgelöst.

Außerdem liefert dieser Callback aBacklog, der angibt, wie viele Byte an Daten im Sendepuffer noch nicht in Bearbeitung sind. Bei Anwendungen, die dem Sendepuffer nur dann Daten hinzufügen möchten, wenn sicher ist, dass sie bald versendet werden, ist es möglicherweise sinnvoll, nur dann Daten zu senden, wenn aBacklog ausreichend klein ist (0 oder nahe 0). Beispielsweise kann eine Anwendung aBacklog verwenden, um auf Warteschlangenaufbau zu reagieren, indem sie Daten löscht oder aggregiert, um einen Datenrückstand zu vermeiden.

Nach einem Aufruf von otTcpSendByReference() oder otTcpSendByExtension() mit einer positiven Bytezahl wird der Callback otTcpForwardProgress() garantiert aufgerufen, um anzuzeigen, wann die zum Sendepuffer hinzugefügten Byte gesendet werden. Der Aufruf von otTcpForwardProgress() kann direkt nach dem Hinzufügen der Byte zum Sendepuffer (wenn einige dieser Byte sofort gesendet werden, wodurch der Rückstand verringert wird) oder zu einem späteren Zeitpunkt erfolgen (wenn die Verbindung einige oder alle Daten sendet, wodurch der Rückstand reduziert wird). Mit "immediately" (sofort) meinen wir, dass der Callback sofort für die Ausführung in einem Tasklet geplant ist. Um die Komplexität des Callbacks zu vermeiden, wird der Callback otTcpForwardProgress() nie direkt über die Funktionen otTcpSendByReference() oder otTcpSendByExtension() aufgerufen.

Details
Parameter
[in] aEndpoint
Der TCP-Endpunkt für die Verbindung.
[in] aInSendBuffer
Die Anzahl der Byte im Sendepuffer (Summe der „In-Flight“- und „Backlog“-Regionen).
[in] aBacklog
Die Anzahl der Byte, die zum Senden in die Warteschlange gestellt, aber noch nicht gesendet wurden (Region „Backlog“).

otTcpIncomingConnectionAction

enum otTcpIncomingConnectionAction otTcpIncomingConnectionAction

Definiert eingehende Verbindungsaktionen.

Wird im otTcpAcceptReady()-Callback verwendet.

otTcpListener

struct otTcpListener otTcpListener

otTcpListenerInitializeArgs

struct otTcpListenerInitializeArgs otTcpListenerInitializeArgs

Enthält Argumente für die Funktion otTcpListenerInitialize().

otTcpReceiveAvailable

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

Dieser Callback gibt die Anzahl der Byte an, die für den Verbrauch aus dem Empfangspuffer verfügbar sind.

Sie wird immer dann aufgerufen, wenn Bytes zum Empfangspuffer hinzugefügt werden und wenn das Ende des Streams erreicht ist. Wenn das Ende des Streams erreicht wurde (d.h., wenn keine weiteren Daten zum Lesen verfügbar werden, weil der Verbindungs-Peer das Ende der Verbindung für den Schreibvorgang geschlossen hat), ist aEndOfStream „true“. aBytesRemaining gibt schließlich an, wie viel Kapazität im Empfangspuffer noch vorhanden ist, um zusätzliche eingehende Daten aufzunehmen.

Details
Parameter
[in] aEndpoint
Der TCP-Endpunkt für die Verbindung.
[in] aBytesAvailable
Die Anzahl der Byte im Empfangspuffer der Verbindung.
[in] aEndOfStream
Gibt an, ob zusätzliche Daten empfangen werden können, die über die Daten im Empfangspuffer der Verbindung hinausgehen.
[in] aBytesRemaining
Die Anzahl zusätzlicher Byte, die empfangen werden können, bevor der Empfangspuffer voll ist.

otTcpSendDone

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

Dieser Callback informiert die Anwendung, dass die Daten im bereitgestellten aData vom Verbindungs-Peer bestätigt wurden und dass aData und die darin enthaltenen Daten von der Anwendung zurückgefordert werden können.

Die aData sind garantiert identisch mit denen, die über otTcpSendByReference() an TCP übergeben werden, einschließlich aller Erweiterungen, die über otTcpSendByExtension() betroffen sind.

Details
Parameter
[in] aEndpoint
Der TCP-Endpunkt für die Verbindung.
[in] aData
Ein Zeiger auf otLinkedBuffer, der zurückgefordert werden kann.

Funktionen

otTcpAbort

otError otTcpAbort(
  otTcpEndpoint *aEndpoint
)

Beendet die mit diesem TCP-Endpunkt verknüpfte TCP-Verbindung zwangsweise.

Dadurch kann der TCP-Endpunkt sofort für eine andere Verbindung verwendet werden und der Sende- und Empfangspuffer wird geleert. Die Eigentümerschaft an allen von der Anwendung in otTcpSendByReference()- und otTcpSendByExtension()-Aufrufen bereitgestellten Daten wird an die Anwendung zurückübertragen. Die Callbacks und der Arbeitsspeicher des TCP-Endpunkts für den Empfangspuffer bleiben mit dem TCP-Endpunkt verknüpft.

Details
Parameter
[in] aEndpoint
Ein Zeiger auf die TCP-Endpunktstruktur, die den abbrechenden TCP-Endpunkt darstellt.
Rückgabewerte
OT_ERROR_NONE
Die Verbindung des TCP-Endpunkts wurde abgebrochen.
OT_ERROR_FAILED
Die Verbindung des TCP-Endpunkts konnte nicht abgebrochen werden.

otTcpBind

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

Bindet den TCP-Endpunkt an eine IP-Adresse und einen Port.

Details
Parameter
[in] aEndpoint
Ein Zeiger auf die zu bindende TCP-Endpunktstruktur.
[in] aSockName
Die Adresse und der Port, an die dieser TCP-Endpunkt gebunden werden soll.
Rückgabewerte
OT_ERROR_NONE
TCP-Endpunkt wurde gebunden.
OT_ERROR_FAILED
TCP-Endpunkt konnte nicht gebunden werden.

otTcpCommitReceive

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

Informiert den TCP-Stack, dass die Anwendung aNumBytes Byte an Daten zu Beginn des Empfangspuffers verarbeitet hat und dass der TCP-Stack diese Byte nicht mehr im Empfangspuffer beibehalten muss.

Details
Parameter
[in] aEndpoint
Ein Zeiger auf die TCP-Endpunktstruktur, die den TCP-Endpunkt darstellt, auf dem Daten empfangen werden sollen.
[in] aNumBytes
Die Anzahl der verbrauchten Byte.
[in] aFlags
Flags, die Optionen für diesen Vorgang angeben (noch keine).
Rückgabewerte
OT_ERROR_NONE
Der Empfangsvorgang wurde erfolgreich abgeschlossen.
OT_ERROR_FAILED
Der Empfangsvorgang konnte nicht abgeschlossen werden.

otTcpConnect

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

Zeichnet den Remote-Host und -Port für diese Verbindung auf.

TCP Fast Open muss mit aFlags aktiviert oder deaktiviert werden. Ist sie deaktiviert, wird der Handshake für den TCP-Verbindungsaufbau sofort initiiert. Wenn sie aktiviert ist, zeichnet diese Funktion lediglich den Remote-Host und den Port auf. Der Handshake der TCP-Verbindung erfolgt nur beim ersten Aufruf von otTcpSendByReference().

Wenn TCP Fast Open deaktiviert ist, muss der Aufrufer auf den otTcpEstablished-Callback warten, der angibt, dass der Handshake der TCP-Verbindung abgeschlossen ist, bevor er mit dem Senden von Daten beginnen kann, z.B. durch Aufrufen von otTcpSendByReference().

Details
Parameter
[in] aEndpoint
Ein Zeiger auf die TCP-Endpunktstruktur, zu der eine Verbindung hergestellt werden soll.
[in] aSockName
Die IP-Adresse und der Port des Hosts, zu dem eine Verbindung hergestellt werden soll.
[in] aFlags
Flags, die Optionen für diesen Vorgang angeben (siehe die obige Aufzählung).
Rückgabewerte
OT_ERROR_NONE
Der Vorgang wurde erfolgreich abgeschlossen.
OT_ERROR_FAILED
Der Vorgang konnte nicht abgeschlossen werden.

otTcpEndpointDeinitialize

otError otTcpEndpointDeinitialize(
  otTcpEndpoint *aEndpoint
)

Deinitialisiert diesen TCP-Endpunkt.

Das bedeutet, dass OpenThread diesen TCP-Endpunkt nicht mehr verfolgt und die Zuweisung aller Ressourcen aufhebt, die er intern für diesen TCP-Endpunkt zugewiesen hat. Die Anwendung kann den Arbeitsspeicher, der den TCP-Endpunkt sichert, nach Bedarf wiederverwenden.

Wenn sie einer Live-TCP-Verbindung entspricht, wird die Verbindung ohne Ankündigung beendet (wie in otTcpAbort()). Alle Ressourcen, die die Anwendung für diesen TCP-Endpunkt bereitgestellt hat (verknüpfte Puffer für den Sendepuffer, Speicher für den Empfangspuffer, die aEndpoint-Struktur selbst usw.), werden sofort an die Anwendung zurückgegeben.

Details
Parameter
[in] aEndpoint
Ein Zeiger auf die TCP-Endpunktstruktur, die deinitialisiert werden soll.
Rückgabewerte
OT_ERROR_NONE
Der TCP-Endpunkt wurde deinitialisiert.
OT_ERROR_FAILED
Der TCP-Endpunkt konnte nicht deinitialisiert werden.

otTcpEndpointGetContext

void * otTcpEndpointGetContext(
  otTcpEndpoint *aEndpoint
)

Ruft den Kontextzeiger ab, der bei der Initialisierung mit aEndpoint verknüpft wurde.

Details
Parameter
[in] aEndpoint
Der TCP-Endpunkt, dessen Kontext abgerufen werden soll.
Rückgabe
Der mit aEndpoint verknüpfte Kontextzeiger.

otTcpEndpointGetInstance

otInstance * otTcpEndpointGetInstance(
  otTcpEndpoint *aEndpoint
)

Ruft die otInstance ab, die bei der Initialisierung mit aEndpoint verknüpft wurde.

Details
Parameter
[in] aEndpoint
Der TCP-Endpunkt, dessen Instanz abgerufen werden soll.
Rückgabe
Der mit aEndpoint verknüpfte otInstance-Zeiger.

otTcpEndpointInitialize

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

Initialisiert einen TCP-Endpunkt.

Der Aufruf dieser Funktion führt dazu, dass OpenThread den TCP-Endpunkt verfolgt und TCP-Daten im aEndpoint speichert und abruft. Die Anwendung sollte nicht direkt auf die Felder in aEndpoint zugreifen oder diese ändern. Wenn die Anwendung den Speicher-aEndpoint zurückfordern muss, sollte sie otTcpEndpointDeinitialize() aufrufen.

Details
Parameter
[in] aInstance
Ein Zeiger auf eine OpenThread-Instanz.
[in] aEndpoint
Ein Zeiger auf eine TCP-Endpunktstruktur.
[in] aArgs
Ein Zeiger auf eine Struktur von Argumenten.
Rückgabewerte
OT_ERROR_NONE
TCP-Endpunkt wurde geöffnet.
OT_ERROR_FAILED
Der TCP-Endpunkt konnte nicht geöffnet werden.

otTcpGetLocalAddress

const otSockAddr * otTcpGetLocalAddress(
  const otTcpEndpoint *aEndpoint
)

Ruft einen Zeiger auf den lokalen Host und den Port eines TCP-Endpunkts ab.

Der Inhalt des Hosts und des Ports kann veraltet sein, wenn dieser Socket keinen Verbindungsstatus hat und nach der letzten Verbindung nicht gebunden wurde.

Details
Parameter
[in] aEndpoint
Der TCP-Endpunkt, dessen lokaler Host und Port abgerufen werden sollen.
Rückgabe
Der lokale Host und Port von aEndpoint.

otTcpGetPeerAddress

const otSockAddr * otTcpGetPeerAddress(
  const otTcpEndpoint *aEndpoint
)

Ruft einen Zeiger auf den Host und Port des Peers eines TCP-Endpunkts ab.

Die Inhalte des Hosts und des Ports können veraltet sein, wenn der Socket nicht verbunden ist.

Details
Parameter
[in] aEndpoint
Der TCP-Endpunkt, dessen Peer-Host und Port abgerufen werden sollen.
Rückgabe
Host und Port des Verbindungs-Peers von aEndpoint.

otTcpListen

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

Veranlasst, dass eingehende TCP-Verbindungen, die der angegebenen IP-Adresse und dem angegebenen Port entsprechen, die Callbacks dieses TCP-Listeners auslösen.

Details
Parameter
[in] aListener
Ein Zeiger auf die TCP-Listener-Struktur, die mit dem Monitoring beginnen soll.
[in] aSockName
Die Adresse und der Port, über die eingehende Verbindungen überwacht werden sollen.
Rückgabewerte
OT_ERROR_NONE
Überwachen des TCP-Listeners erfolgreich eingeleitet.
OT_ERROR_FAILED
Überwachen des TCP-Listeners konnte nicht initiiert werden.

otTcpListenerDeinitialize

otError otTcpListenerDeinitialize(
  otTcpListener *aListener
)

Deinitialisiert diesen TCP-Listener.

Das bedeutet, dass OpenThread diesen TCP-Listener nicht mehr verfolgt und die Zuweisung aller Ressourcen aufhebt, die er intern für diesen TCP-Listener zugewiesen hat. Die Anwendung kann den Arbeitsspeicher, der den TCP-Listener unterstützt, nach Bedarf wiederverwenden.

Wenn der TCP-Listener aktuell aktiv ist, wird er nicht mehr überwacht.

Details
Parameter
[in] aListener
Ein Zeiger auf die TCP-Listener-Struktur, die deinitialisiert werden soll.
Rückgabewerte
OT_ERROR_NONE
TCP-Listener wurde deinitialisiert.
OT_ERROR_FAILED
Der TCP-Listener konnte nicht deaktiviert werden.

otTcpListenerGetContext

void * otTcpListenerGetContext(
  otTcpListener *aListener
)

Ruft den Kontextzeiger ab, der bei der Initialisierung mit aListener verknüpft wurde.

Details
Parameter
[in] aListener
Der TCP-Listener, dessen Kontext abgerufen werden soll.
Rückgabe
Der mit aListener verknüpfte Kontextzeiger.

otTcpListenerGetInstance

otInstance * otTcpListenerGetInstance(
  otTcpListener *aListener
)

Ruft die otInstance ab, die bei der Initialisierung mit aListener verknüpft wurde.

Details
Parameter
[in] aListener
Der TCP-Listener, dessen Instanz abgerufen werden soll.
Rückgabe
Der mit aListener verknüpfte otInstance-Zeiger.

otTcpListenerInitialize

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

Initialisiert einen TCP-Listener.

Der Aufruf dieser Funktion führt dazu, dass OpenThread den TCP-Listener verfolgt und TCP-Daten in aListener speichert und abruft. Die Anwendung sollte nicht direkt auf die Felder in aListener zugreifen oder diese ändern. Wenn die Anwendung die speicherstützende aListener zurückfordern muss, sollte sie otTcpListenerDeinitialize() aufrufen.

Details
Parameter
[in] aInstance
Ein Zeiger auf eine OpenThread-Instanz.
[in] aListener
Ein Zeiger auf eine TCP-Listener-Struktur.
[in] aArgs
Ein Zeiger auf eine Struktur von Argumenten.
Rückgabewerte
OT_ERROR_NONE
TCP-Listener wurde geöffnet.
OT_ERROR_FAILED
TCP-Listener konnte nicht geöffnet werden.

otTcpReceiveByReference

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

Stellt der Anwendung eine verknüpfte Pufferkette bereit, die auf Daten verweist, die sich derzeit im TCP-Empfangspuffer befinden.

Die verknüpfte Pufferkette ist gültig, bis der Rückruf "empfang bereit" das nächste Mal aufgerufen wird oder bis zum nächsten Aufruf von otTcpReceiveContiguify() oder otTcpCommitReceive().

Details
Parameter
[in] aEndpoint
Ein Zeiger auf die TCP-Endpunktstruktur, die den TCP-Endpunkt darstellt, auf dem Daten empfangen werden sollen.
[out] aBuffer
Ein Zeiger auf die verknüpfte Pufferkette, der auf Daten verweist, die sich derzeit im Empfangspuffer befinden.
Rückgabewerte
OT_ERROR_NONE
Der Vorgang wurde erfolgreich abgeschlossen.
OT_ERROR_FAILED
Der Vorgang konnte nicht abgeschlossen werden.

otTcpReceiveContiguify

otError otTcpReceiveContiguify(
  otTcpEndpoint *aEndpoint
)

Ordnet den Empfangspuffer neu an, sodass er im Speicher vollständig zusammenhängend ist.

Dies ist optional. Eine Anwendung kann einfach die verknüpfte Pufferkette durchlaufen, die durch Aufrufen von otTcpReceiveByReference abgerufen wird. Einige Anwendungen möchten diese Funktion möglicherweise aufrufen, um den Empfangspuffer zusammenhängend zu machen, um ihre Datenverarbeitung zu vereinfachen. Dies geht jedoch auf Kosten der CPU-Zeit, um die Daten im Empfangspuffer neu zu organisieren.

Details
Parameter
[in] aEndpoint
Ein Zeiger auf den TCP-Endpunkt, dessen Empfangspuffer neu organisiert werden soll.
Rückgabewerte
OT_ERROR_NONE
Der Vorgang wurde erfolgreich abgeschlossen.
OT_ERROR_FAILED
Der Vorgang konnte nicht abgeschlossen werden.

otTcpSendByExtension

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

Fügt Daten zum Sendepuffer hinzu, indem die Länge des endgültigen otLinkedBuffer im Sendepuffer um die angegebene Menge erweitert wird.

Wenn der Sendepuffer leer ist, schlägt der Vorgang fehl.

Details
Parameter
[in] aEndpoint
Ein Zeiger auf die TCP-Endpunktstruktur, die den TCP-Endpunkt darstellt, an den Daten gesendet werden sollen.
[in] aNumBytes
Die Anzahl der Byte, um die die Länge des endgültig verknüpften Puffers erweitert werden soll.
[in] aFlags
Flags, die Optionen für diesen Vorgang angeben (siehe die obige Aufzählung).
Rückgabewerte
OT_ERROR_NONE
Daten wurden dem Sendepuffer hinzugefügt.
OT_ERROR_FAILED
Fehler beim Hinzufügen von Daten zum Sendepuffer.

otTcpSendByReference

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

Fügt dem Sendepuffer Daten hinzu, auf die vom verknüpften Puffer verwiesen wird, auf den aBuffer verweist.

Bei einem erfolgreichen Aufruf dieser Funktion gehören der verknüpfte Zwischenspeicher und die Daten, auf die er verweist, zum TCP-Stack. Sie sollten von der Anwendung erst geändert werden, wenn ein „send done“-Callback die Inhaberschaft dieser Objekte an die Anwendung zurückgibt. Es ist zulässig, diese Funktion aufzurufen, um der Sendewarteschlange einen weiteren verknüpften Puffer hinzuzufügen, auch wenn der Rückruf "Senden abgeschlossen" für einen vorherigen Aufruf dieser Funktion noch nicht ausgelöst wurde.

aBuffer darf nicht verkettet sein. Das Feld „mNext“ sollte NULL sein. Wenn direkt nach diesem Aufruf zusätzliche Daten hinzugefügt werden, sollte das Flag OT_TCP_SEND_MORE_TO_COME als Hinweis für die TCP-Implementierung verwendet werden.

Details
Parameter
[in] aEndpoint
Ein Zeiger auf die TCP-Endpunktstruktur, die den TCP-Endpunkt darstellt, an den Daten gesendet werden sollen.
[in] aBuffer
Ein Zeiger auf die verknüpfte Zwischenspeicherkette, der auf Daten verweist, die dem Sendepuffer hinzugefügt werden sollen.
[in] aFlags
Flags, die Optionen für diesen Vorgang angeben (siehe die obige Aufzählung).
Rückgabewerte
OT_ERROR_NONE
Daten wurden dem Sendepuffer hinzugefügt.
OT_ERROR_FAILED
Fehler beim Hinzufügen von Daten zum Sendepuffer.

otTcpSendEndOfStream

otError otTcpSendEndOfStream(
  otTcpEndpoint *aEndpoint
)

Informiert den Verbindungs-Peer, dass dieser TCP-Endpunkt keine weiteren Daten sendet.

Dieser Parameter sollte verwendet werden, wenn die Anwendung keine weiteren Daten zum Senden an den Verbindungs-Peer hat. Bei dieser Verbindung führen zukünftige Lesevorgänge auf dem Verbindungs-Peer zur Bedingung „Ende des Streams“ und zukünftige Schreibvorgänge auf diesem Verbindungsendpunkt schlagen fehl.

Die Bedingung „Ende des Streams“ wird nur angewendet, wenn alle zuvor an den TCP-Stack zum Senden bereitgestellten Daten vom Verbindungs-Peer empfangen wurden.

Details
Parameter
[in] aEndpoint
Ein Zeiger auf die TCP-Endpunktstruktur, die den herunterzufahrenden TCP-Endpunkt darstellt.
Rückgabewerte
OT_ERROR_NONE
Die Bedingung "Ende des Streams" wurde für die Übertragung in die Warteschlange gestellt.
OT_ERROR_FAILED
Die Bedingung "Ende des Streams" konnte nicht in die Warteschlange für die Übertragung gestellt werden.

otTcpStopListening

otError otTcpStopListening(
  otTcpListener *aListener
)

Bewirkt, dass dieser TCP-Listener eingehende Verbindungen nicht mehr überwacht.

Details
Parameter
[in] aListener
Ein Zeiger auf die TCP-Listener-Struktur, die nicht mehr überwachen soll.
Rückgabewerte
OT_ERROR_NONE
Überwachung des TCP-Listeners erfolgreich beendet.
OT_ERROR_FAILED
Überwachung des TCP-Listeners konnte nicht beendet werden.

Makros

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 und OT_TCP_ENDPOINT_TCB_NUM_POINTERS wurden so ausgewählt, dass das mTcb-Feld von otTcpEndpoint die gleiche Größe wie die Struktur tcpcb in TCPlp hat.

Das ist erforderlich, da das Feld „mTcb“ in der TCP-Implementierung als „Struct tcpcb“ behandelt wird, auch wenn es in seiner Deklaration undurchsichtig ist.

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 und OT_TCP_LISTENER_TCB_NUM_POINTERS werden so ausgewählt, dass das mTcbListener-Feld von otTcpListener die gleiche Größe wie die Struktur tcpcb_listen in TCPlp hat.

Dies ist erforderlich, da das Feld „mTcbListen“, auch wenn es in seiner Deklaration nicht transparent ist, in der TCP-Implementierung als „Struct tcpcb“ behandelt wird.

OT_TCP_RECEIVE_BUFFER_SIZE_FEW_HOPS

 OT_TCP_RECEIVE_BUFFER_SIZE_FEW_HOPS 2598

Empfohlene Puffergröße für TCP-Verbindungen, die ca. 3 Wireless-Hops oder weniger durchlaufen.

Auf Plattformen, auf denen der Speicher besonders begrenzt ist, und in Situationen, in denen keine hohe Bandbreite erforderlich ist, kann es sinnvoll sein, manuell eine kleinere Puffergröße auszuwählen.

OT_TCP_RECEIVE_BUFFER_SIZE_MANY_HOPS

 OT_TCP_RECEIVE_BUFFER_SIZE_MANY_HOPS 4157

Empfohlene Puffergröße für TCP-Verbindungen, die viele WLAN-Hops durchlaufen.

Wenn die TCP-Verbindung eine sehr große Anzahl von Hops (mehr als 6 oder mehr) durchläuft, ist es möglicherweise ratsam, manuell eine große Puffergröße auszuwählen.

Ressourcen

OpenThread API-Referenzthemen stammen aus dem Quellcode, der auf GitHub verfügbar ist. Weitere Informationen finden Sie unter Ressourcen. Dort können Sie auch einen Beitrag zu unserer Dokumentation leisten.