Astrazioni TCP

Questo modulo include astrazioni facili da usare in aggiunta all'API TCP di base.

Riepilogo

Enumerazioni
anonymous enum enum
Definisce i flag passati a otTcpCircularSendBufferWrite.

Typedef
otTcpCircularSendBuffer typedef
Rappresenta un buffer di invio circolare da utilizzare con un endpoint TCP.
otTcpEndpointAndCircularSendBuffer typedef
Struttura del contesto da utilizzare con mbedtls_ssl_set_bio.

Funzioni
otTcpCircularSendBufferDeinitialize(otTcpCircularSendBuffer *aSendBuffer)
Deinizializza un buffer di invio circolare TCP, scollegandolo se collegato.
otTcpCircularSendBufferForceDiscardAll(otTcpCircularSendBuffer *aSendBuffer)
void
Ignora forzatamente tutti i dati nel buffer di invio circolare.
otTcpCircularSendBufferGetFreeSpace(const otTcpCircularSendBuffer *aSendBuffer)
size_t
Restituisce la quantità di spazio libero nel buffer di invio circolare TCP.
otTcpCircularSendBufferHandleForwardProgress(otTcpCircularSendBuffer *aSendBuffer, size_t aInSendBuffer)
void
Esegue la gestione specifica del buffer circolare-send-nel callback otTcpForwardProgress.
otTcpCircularSendBufferInitialize(otTcpCircularSendBuffer *aSendBuffer, void *aDataBuffer, size_t aCapacity)
void
Inizializza un buffer di invio circolare TCP.
otTcpCircularSendBufferWrite(otTcpEndpoint *aEndpoint, otTcpCircularSendBuffer *aSendBuffer, const void *aData, size_t aLength, size_t *aWritten, uint32_t aFlags)
Invia i dati su un endpoint TCP, utilizzando il buffer di invio circolare TCP fornito per gestire il buffering.
otTcpMbedTlsSslRecvCallback(void *aCtx, unsigned char *aBuf, size_t aLen)
int
Il callback di ricezione non bloccato per passare a mbedtls_ssl_set_bio.
otTcpMbedTlsSslSendCallback(void *aCtx, const unsigned char *aBuf, size_t aLen)
int
Invia callback senza blocco per passare a mbedtls_ssl_set_bio.

Strutture
otTcpCircularSendBuffer

Rappresenta un buffer di invio circolare da utilizzare con un endpoint TCP.

otTcpEndpointAndCircularSendBuffer

Struttura del contesto da utilizzare con mbedtls_ssl_set_bio.

Enumerazioni

enum anonimo

 anonymous enum

Definisce i flag passati a otTcpCircularSendBufferWrite.

Typedef

otTcpCircularSendBuffer

struct otTcpCircularSendBuffer otTcpCircularSendBuffer

Rappresenta un buffer di invio circolare da utilizzare con un endpoint TCP.

L'utilizzo di un buffer di invio circolare è facoltativo. Le applicazioni possono utilizzare un endpoint TCP per inviare i dati gestendo direttamente otLinkedBuffers. Tuttavia, alcune applicazioni potrebbero trovare più conveniente avere un buffer di invio circolare; tali applicazioni possono chiamare otTcpCircularSendBufferWrite() per "collegare" un buffer di invio circolare a un endpoint TCP e inviare dati su tale endpoint TCP, affidandosi al buffer di invio circolare per gestire i valori otLinkedBuffers sottostanti.

otTcpCircularSendBuffer viene implementato sulla parte superiore dell'API basata su otLinkedBuffer fornita da otTcpEndpoint. Una volta collegato a un otTcpEndpoint, un otTcpCircularSendBuffer esegue tutto il lavoro di gestione di otLinkedBuffers per la connessione. Ciò significa che, una volta che un otTcpCircularSendBuffer è collegato a un otTcpEndpoint, l'applicazione non deve chiamare otTcpSendByReference() o otTcpSendByExtension() su tale otTcpEndpoint. L'applicazione dovrebbe invece usare otTcpCircularSendBufferWrite() per aggiungere dati al buffer di invio.

Il callback otTcpForwardProgress() è il modo in cui gli utenti imparano quando diventa disponibile spazio nel buffer di invio circolare. Su un otTcpEndpoint a cui è collegato un otTcpCircularSendBuffer, l'applicazione DEVE installare un callback otTcpForwardProgress() e chiamare otTcpCircularSendBufferHandleForwardProgress() sull'otTcpCircularSendBuffer collegato all'inizio della funzione di callback. È consigliabile che l'utente NON installi un callback otTcpSendDone(), poiché tutta la gestione di otLinkedBuffers viene gestita dal buffer di invio circolare.

L'applicazione non deve ispezionare direttamente i campi di questa struttura; deve interagire con essa solo tramite le funzioni dell'API TCP Circular Send Buffer la cui firma è fornita in questo file.

otTcpEndpointAndCircularSendBuffer

struct otTcpEndpointAndCircularSendBuffer otTcpEndpointAndCircularSendBuffer

Struttura del contesto da utilizzare con mbedtls_ssl_set_bio.

Funzioni

otTcpCircularSendBufferDeinitialize

otError otTcpCircularSendBufferDeinitialize(
  otTcpCircularSendBuffer *aSendBuffer
)

Deinizializza un buffer di invio circolare TCP, scollegandolo se collegato.

Se il buffer di invio circolare TCP non è vuoto, l'operazione non andrà a buon fine.

Dettagli
Parametri
[in] aSendBuffer
Il buffer di invio circolare TCP da annullare l'inizializzazione.
Valori restituiti
OT_ERROR_NONE
Deinizializza correttamente il buffer di invio circolare TCP.
OT_ERROR_BUSY
Il buffer circolare contiene dati e non può essere deselezionato.

otTcpCircularSendBufferForceDiscardAll

void otTcpCircularSendBufferForceDiscardAll(
  otTcpCircularSendBuffer *aSendBuffer
)

Ignora forzatamente tutti i dati nel buffer di invio circolare.

L'applicazione dovrebbe chiamare questa funzione quando una connessione TCP viene terminata senza cerimonie (ad esempio, se l'applicazione chiama otTcpEndpointAbort() o viene informata di una connessione di reimpostazione tramite il callback otTcpConnectionLost()).

Chiamare questa funzione su un buffer di invio circolare TCP non vuoto collegato a un endpoint TCP determina un comportamento indefinito.

Dettagli
Parametri
[in] aSendBuffer
Il buffer di invio circolare TCP di cui eliminare i dati.

otTcpCircularSendBufferGetFreeSpace

size_t otTcpCircularSendBufferGetFreeSpace(
  const otTcpCircularSendBuffer *aSendBuffer
)

Restituisce la quantità di spazio libero nel buffer di invio circolare TCP.

Questa operazione avrà sempre esito positivo.

Dettagli
Parametri
[in] aSendBuffer
Un puntatore al buffer di invio circolare TCP la cui quantità di spazio libero da restituire.
Restituisce
La quantità di spazio libero nel buffer di invio.

otTcpCircularSendBufferHandleForwardProgress

void otTcpCircularSendBufferHandleForwardProgress(
  otTcpCircularSendBuffer *aSendBuffer,
  size_t aInSendBuffer
)

Esegue la gestione specifica del buffer circolare-send-nel callback otTcpForwardProgress.

L'applicazione dovrebbe installare un callback otTcpForwardProgress() sull'otTcpEndpoint e dovrebbe chiamare questa funzione all'inizio della funzione di callback per l'elaborazione specifica di Cir-send-buffer.

Nella funzione di callback, l'applicazione può determinare la quantità di spazio libero nel buffer di invio circolare chiamando otTcpCircularSendBufferFreeSpace() o confrontando aInSendBuffer con la capacità del buffer di invio, scelta dall'utente durante la chiamata a otTcpCircularSendBufferInitialize().

Dettagli
Parametri
[in] aSendBuffer
Un puntatore al buffer di invio circolare TCP per l'endpoint per il quale è stato richiamato otTcpForwardProgress().
[in] aInSendBuffer
Valore di aInSendBuffer passato al callback otTcpForwardProgress().

otTcpCircularSendBufferInitialize

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

Inizializza un buffer di invio circolare TCP.

Dettagli
Parametri
[in] aSendBuffer
Un puntatore al buffer di invio circolare TCP da inizializzare.
[in] aDataBuffer
Un puntatore alla memoria da utilizzare per memorizzare i dati nel buffer di invio circolare TCP.
[in] aCapacity
La capacità, in byte, del buffer di invio circolare TCP, che deve corrispondere alle dimensioni della memoria a cui punta aDataBuffer .

otTcpCircularSendBufferWrite

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

Invia i dati su un endpoint TCP, utilizzando il buffer di invio circolare TCP fornito per gestire il buffering.

Una volta chiamata questa funzione, aSendBuffer e aEndpoint vengono considerati "collegati" l'uno all'altro. Finché sono allegati, TUTTE le operazioni di invio per aEndpoint devono essere eseguite utilizzando aSendBuffer e TUTTE le operazioni su aSendBuffer devono essere associate a aEndpoint .

L'unico modo per "scollegare" un buffer di invio circolare TCP e un endpoint TCP è attendere che il buffer di invio diventi completamente vuoto. Questo può accadere in due modi: (1) tutti i dati nel buffer di invio vengono inviati e confermati nel normale corso del funzionamento del protocollo TCP oppure (2) la connessione viene terminata.

Il modello di utilizzo consigliato consiste nell'utilizzare un singolo buffer di invio circolare TCP con un endpoint TCP e nell'inviare i dati su quell'endpoint TCP solo tramite il buffer circolare TCP associato. Questo pattern di utilizzo consigliato evita i problemi descritti sopra utilizzando sempre un endpoint TCP e un buffer di invio circolare TCP insieme.

Se il buffer di invio circolare raggiunge la capacità massima, nel buffer circolare di invio viene copiato solo un prefisso dei dati forniti.

Dettagli
Parametri
[in] aEndpoint
L'endpoint TCP su cui inviare i dati.
[in] aSendBuffer
Il buffer di invio circolare TCP in cui copiare i dati.
[in] aData
Un puntatore ai dati da copiare nel buffer di invio circolare TCP.
[in] aLength
La lunghezza dei dati a cui punta aData da copiare nel buffer di invio circolare TCP.
[out] aWritten
Compilato con la quantità di dati copiati nel buffer di invio, che potrebbe essere inferiore a aLength se il buffer di invio raggiunge la capacità.
[in] aFlags
Flag che specificano le opzioni per questa operazione (vedi l'enumerazione sopra).
Valori restituiti
OT_ERROR_NONE
I dati sono stati copiati nel buffer di invio e li sono stati inviati all'endpoint TCP.
OT_ERROR_FAILED
Impossibile inviare i dati sull'endpoint TCP.

otTcpMbedTlsSslRecvCallback

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

Il callback di ricezione non bloccato per passare a mbedtls_ssl_set_bio.

Dettagli
Parametri
[in] aCtx
[out] aBuf
Il buffer in cui ricevere i dati.
[in] aLen
La quantità massima di dati che può essere ricevuta.
Restituisce
Il numero di byte ricevuti o un codice di errore mbedtls.

otTcpMbedTlsSslSendCallback

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

Invia callback senza blocco per passare a mbedtls_ssl_set_bio.

Dettagli
Parametri
[in] aCtx
[in] aBuf
I dati da aggiungere al buffer di invio.
[in] aLen
La quantità di dati da aggiungere al buffer di invio.
Restituisce
Il numero di byte inviati o un codice di errore mbedtls.

Risorse

Gli argomenti di riferimento dell'API OpenThread provengono dal codice sorgente, disponibile su GitHub. Per saperne di più o per contribuire alla nostra documentazione, consulta la sezione Risorse.