TCP-Abstraktionen

Dieses Modul enthält zusätzlich zur TCP API einfach zu verwendende Abstraktionen.

Zusammenfassung

Aufzählungen
anonymous enum enum
Definiert an otTcpCircularSendBufferWrite übergebene Flags.

Typedefs
otTcpCircularSendBuffer typedef
Stellt einen zirkulären Sendepuffer zur Verwendung mit einem TCP-Endpunkt dar.
otTcpEndpointAndCircularSendBuffer typedef
Kontextstruktur zur Verwendung mit mbedtls_ssl_set_bio.

Funktionen
otTcpCircularSendBufferDeinitialize(otTcpCircularSendBuffer *aSendBuffer)
Deinitialisiert einen kreisförmigen TCP-Sendezwischenspeicher und trennt ihn, falls er angehängt ist.
otTcpCircularSendBufferForceDiscardAll(otTcpCircularSendBuffer *aSendBuffer)
void
Verwirft alle Daten im zirkulären Sendepuffer.
otTcpCircularSendBufferGetFreeSpace(const otTcpCircularSendBuffer *aSendBuffer)
size_t
Gibt den freien Speicherplatz im kreisförmigen TCP-Sendepuffer zurück.
otTcpCircularSendBufferHandleForwardProgress(otTcpCircularSendBuffer *aSendBuffer, size_t aInSendBuffer)
void
Führt eine zirkuläre Sendezwischenspeicher-spezifische Verarbeitung im otTcpForwardProgress-Callback durch.
otTcpCircularSendBufferInitialize(otTcpCircularSendBuffer *aSendBuffer, void *aDataBuffer, size_t aCapacity)
void
Initialisiert einen kreisförmigen TCP-Sendezwischenspeicher.
otTcpCircularSendBufferWrite(otTcpEndpoint *aEndpoint, otTcpCircularSendBuffer *aSendBuffer, const void *aData, size_t aLength, size_t *aWritten, uint32_t aFlags)
Sendet Daten über einen TCP-Endpunkt unter Verwendung des bereitgestellten kreisförmigen TCP-Sendepuffers, um die Zwischenspeicherung zu verwalten.
otTcpMbedTlsSslRecvCallback(void *aCtx, unsigned char *aBuf, size_t aLen)
int
Nicht blockierender Callback beim Empfang an mbedtls_ssl_set_bio.
otTcpMbedTlsSslSendCallback(void *aCtx, const unsigned char *aBuf, size_t aLen)
int
Nicht blockierender Callback wird an mbedtls_ssl_set_bio gesendet.

Strukturen
otTcpCircularSendBuffer

Stellt einen zirkulären Sendepuffer zur Verwendung mit einem TCP-Endpunkt dar.

otTcpEndpointAndCircularSendBuffer

Kontextstruktur zur Verwendung mit mbedtls_ssl_set_bio.

Aufzählungen

Anonyme Aufzählung

 anonymous enum

Definiert an otTcpCircularSendBufferWrite übergebene Flags.

Typedefs

otTcpCircularSendBuffer

struct otTcpCircularSendBuffer otTcpCircularSendBuffer

Stellt einen zirkulären Sendepuffer zur Verwendung mit einem TCP-Endpunkt dar.

Die Verwendung eines zirkulären Sendepuffers ist optional. Anwendungen können einen TCP-Endpunkt zum Senden von Daten verwenden, indem otLinkedBuffers direkt verwaltet wird. Für einige Anwendungen ist jedoch ein zirkulärer Sendepuffer möglicherweise praktischer. Solche Anwendungen können otTcpCircularSendBufferWrite() aufrufen, um einen zirkulären Sendepuffer an einen TCP-Endpunkt anzuhängen und Daten an diesen TCP-Endpunkt zu senden. Dabei wird der zirkuläre Sendepuffer zur Verwaltung der zugrunde liegenden otLinkedBuffers genutzt.

otTcpCircularSendBuffer wird zusätzlich zur auf otLinkedBuffer basierenden API implementiert, die von einem otTcpEndpoint bereitgestellt wird. Nach der Verknüpfung mit einem otTcpEndpoint übernimmt ein otTcpCircularSendBuffer die gesamte Verwaltung von otLinkedBuffers für die Verbindung. Wenn also ein otTcpCircularSendBuffer an einen otTcpEndpoint angehängt wurde, sollte die Anwendung otTcpSendByReference() oder otTcpSendByExtension() für diesen otTcpEndpoint nicht mehr aufrufen. Stattdessen sollte die Anwendung otTcpCircularSendBufferWrite() verwenden, um Daten in den Sendepuffer aufzunehmen.

Anhand des Callbacks otTcpForwardProgress() können Nutzer erfahren, wenn im zirkulären Sendepuffer Speicherplatz frei wird. Auf einem otTcpEndpoint, an den ein otTcpCircularSendBuffer angehängt ist, MUSS die Anwendung einen otTcpForwardProgress()-Callback installieren und otTcpCircularSendBufferHandleForwardProgress() für den angehängten otTcpCircularSendBuffer zu Beginn der Rückruffunktion aufrufen. Der Nutzer sollte NICHT einen otTcpSendDone()-Callback installieren, da die gesamte Verwaltung von otLinkedBuffers über den zirkulären Sendepuffer abgewickelt wird.

Die Anwendung sollte die Felder dieser Struktur nicht direkt prüfen, sondern nur über die TCP Circular Send Buffer API-Funktionen mit ihr interagieren, deren Signatur in dieser Datei bereitgestellt wird.

otTcpEndpointAndCircularSendBuffer

struct otTcpEndpointAndCircularSendBuffer otTcpEndpointAndCircularSendBuffer

Kontextstruktur zur Verwendung mit mbedtls_ssl_set_bio.

Funktionen

otTcpCircularSendBufferDeinitialize

otError otTcpCircularSendBufferDeinitialize(
  otTcpCircularSendBuffer *aSendBuffer
)

Deinitialisiert einen kreisförmigen TCP-Sendezwischenspeicher und trennt ihn, falls er angehängt ist.

Wenn der zirkuläre TCP-Sendezwischenspeicher nicht leer ist, schlägt dieser Vorgang fehl.

Details
Parameter
[in] aSendBuffer
Der zu deinitialisierende TCP-Kreispuffer für das Senden.
Rückgabewerte
OT_ERROR_NONE
Deinitialisieren des kreisförmigen TCP-Sendepuffers
OT_ERROR_BUSY
Der Kreispuffer enthält Daten und kann nicht deinitialisiert werden.

otTcpCircularSendBufferForceDiscardAll

void otTcpCircularSendBufferForceDiscardAll(
  otTcpCircularSendBuffer *aSendBuffer
)

Verwirft alle Daten im zirkulären Sendepuffer.

Es wird erwartet, dass die Anwendung diese Funktion aufruft, wenn eine TCP-Verbindung zu einem anderen Zeitpunkt beendet wird (z.B. wenn die Anwendung otTcpEndpointAbort() aufruft oder über den Rückruf „otTcpConnectionLost()“ über eine zurückgesetzte Verbindung informiert wird).

Der Aufruf dieser Funktion für einen nicht leeren, an einen TCP-Endpunkt angehängten, zirkulären TCP-Sendepuffer führt zu nicht definiertem Verhalten.

Details
Parameter
[in] aSendBuffer
Der kreisförmige TCP-Sendezwischenspeicher, dessen Daten verworfen werden sollen.

otTcpCircularSendBufferGetFreeSpace

size_t otTcpCircularSendBufferGetFreeSpace(
  const otTcpCircularSendBuffer *aSendBuffer
)

Gibt den freien Speicherplatz im kreisförmigen TCP-Sendepuffer zurück.

Dieser Vorgang ist immer erfolgreich.

Details
Parameter
[in] aSendBuffer
Ein Zeiger auf den kreisförmigen TCP-Sendepuffer, dessen freier Speicherplatz zurückgegeben werden soll.
Rückgabe
Der kostenlose Speicherplatz im Sendepuffer.

otTcpCircularSendBufferHandleForwardProgress

void otTcpCircularSendBufferHandleForwardProgress(
  otTcpCircularSendBuffer *aSendBuffer,
  size_t aInSendBuffer
)

Führt eine zirkuläre Sendezwischenspeicher-spezifische Verarbeitung im otTcpForwardProgress-Callback durch.

Es wird erwartet, dass die Anwendung einen otTcpForwardProgress()-Callback auf otTcpEndpoint installiert und diese Funktion zu Beginn der Callback-Funktion für eine zirkuläre „send-buffer“-spezifische Verarbeitung aufruft.

In der Callback-Funktion kann die Anwendung den freien Speicherplatz im zirkulären Sendepuffer durch Aufrufen von otTcpCircularSendBufferFreeSpace() oder durch Vergleichen von aInSendBuffer mit der Kapazität des Sendepuffers bestimmen, die vom Nutzer beim Aufrufen von otTcpCircularSendBufferInitialize() ausgewählt wurde.

Details
Parameter
[in] aSendBuffer
Ein Zeiger auf den kreisförmigen TCP-Sendepuffer für den Endpunkt, für den otTcpForwardProgress() aufgerufen wurde.
[in] aInSendBuffer
Der Wert aInSendBuffer wird an den Rückruf otTcpForwardProgress() übergeben.

otTcpCircularSendBufferInitialize

void otTcpCircularSendBufferInitialize(
  otTcpCircularSendBuffer *aSendBuffer,
  void *aDataBuffer,
  size_t aCapacity
)

Initialisiert einen kreisförmigen TCP-Sendezwischenspeicher.

Details
Parameter
[in] aSendBuffer
Ein Zeiger auf den kreisförmigen TCP-Sendepuffer für die Initialisierung.
[in] aDataBuffer
Ein Zeiger auf den Arbeitsspeicher, der zum Speichern von Daten im kreisförmigen TCP-Sendepuffer verwendet wird.
[in] aCapacity
Die Kapazität des kreisförmigen TCP-Sendepuffers in Byte, die der Größe des Arbeitsspeichers entsprechen muss, auf den aDataBuffer verweist .

otTcpCircularSendBufferWrite

otError otTcpCircularSendBufferWrite(
  otTcpEndpoint *aEndpoint,
  otTcpCircularSendBuffer *aSendBuffer,
  const void *aData,
  size_t aLength,
  size_t *aWritten,
  uint32_t aFlags
)

Sendet Daten über einen TCP-Endpunkt unter Verwendung des bereitgestellten kreisförmigen TCP-Sendepuffers, um die Zwischenspeicherung zu verwalten.

Sobald diese Funktion aufgerufen wird, gelten aSendBuffer und aEndpoint als „verbunden“. Während sie angehängt sind, müssen ALLE Sendevorgänge für aEndpoint mit aSendBuffer erfolgen und ALLE Vorgänge in aSendBuffer müssen mit aEndpoint verknüpft sein .

Die einzige Möglichkeit, einen kreisförmigen TCP-Sendezwischenspeicher und einen TCP-Endpunkt zu "trennen", besteht darin, darauf zu warten, dass der Sendepuffer vollständig leer ist. Dies kann auf zwei Arten geschehen: (1) Alle Daten im Sendepuffer werden im normalen Verlauf des TCP-Protokollvorgangs gesendet und bestätigt oder (2) die Verbindung wird beendet.

Das empfohlene Nutzungsmuster ist die Verwendung eines einzelnen kreisförmigen TCP-Sendepuffers mit einem TCP-Endpunkt und das Senden von Daten an diesem TCP-Endpunkt nur über den zugehörigen kreisförmigen TCP-Zwischenspeicher. Bei diesem empfohlenen Nutzungsmuster werden die oben beschriebenen Probleme umgangen, da ein TCP-Endpunkt und ein kreislaufförmiger TCP-Sendezwischenspeicher immer zusammen verwendet werden.

Wenn der zirkuläre Sendepuffer die Kapazität erreicht, wird nur ein Präfix der bereitgestellten Daten in den zirkulären Sendepuffer kopiert.

Details
Parameter
[in] aEndpoint
Der TCP-Endpunkt, an den Daten gesendet werden sollen.
[in] aSendBuffer
Der TCP-Zirkelbezugspuffer, in den Daten kopiert werden sollen.
[in] aData
Ein Zeiger auf Daten, die in den kreisförmigen TCP-Sendezwischenspeicher kopiert werden sollen.
[in] aLength
Die Länge der Daten, auf die aData verweist, um sie in den kreisförmigen TCP-Sendezwischenspeicher zu kopieren.
[out] aWritten
Wird mit der in den Sendepuffer kopierten Datenmenge gefüllt, die möglicherweise kleiner als aLength ist, wenn der Sendepuffer die Kapazität erreicht.
[in] aFlags
Flags, die Optionen für diesen Vorgang angeben (siehe die obige Aufzählung).
Rückgabewerte
OT_ERROR_NONE
Daten wurden in den Sendepuffer kopiert und an den TCP-Endpunkt gesendet.
OT_ERROR_FAILED
Daten konnten nicht über den TCP-Endpunkt gesendet werden.

otTcpMbedTlsSslRecvCallback

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

Nicht blockierender Callback beim Empfang an mbedtls_ssl_set_bio.

Details
Parameter
[in] aCtx
Ein Zeiger auf einen otTcpEndpointAndCircularSendBuffer.
[out] aBuf
Der Puffer, in den Daten empfangen werden sollen.
[in] aLen
Die maximale Datenmenge, die empfangen werden kann.
Rückgabe
Die Anzahl der empfangenen Byte oder ein mbedtls-Fehlercode.

otTcpMbedTlsSslSendCallback

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

Nicht blockierender Callback wird an mbedtls_ssl_set_bio gesendet.

Details
Parameter
[in] aCtx
Ein Zeiger auf einen otTcpEndpointAndCircularSendBuffer.
[in] aBuf
Die Daten, die dem Sendepuffer hinzugefügt werden sollen.
[in] aLen
Die Datenmenge, die dem Sendepuffer hinzugefügt werden soll.
Rückgabe
Die Anzahl der gesendeten Byte oder ein mbedtls-Fehlercode.

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.