This module includes functions that control TCP communication.

Classes
struct	otLinkedBuffer
	A linked buffer structure for use with TCP.

struct	otTcpEndpoint
	This structure represents a TCP endpoint.

struct	otTcpEndpointInitializeArgs
	This structure contains arguments to the otTcpEndpointInitialize() function.

struct	otTcpListener
	This structure represents a TCP listener.

struct	otTcpListenerInitializeArgs
	This structure contains arguments to the otTcpListenerInitialize() function.

Macros
#define	OT_TCP_RECEIVE_BUFFER_SIZE_FEW_HOPS 2599
	Recommended buffer size for TCP connections that traverse about 3 wireless hops or fewer.

#define	OT_TCP_RECEIVE_BUFFER_SIZE_MANY_HOPS 4158
	Recommended buffer size for TCP connections that traverse many wireless hops.

Typedefs
typedef struct otLinkedBuffer	otLinkedBuffer
	A linked buffer structure for use with TCP.

typedef struct otTcpEndpoint	otTcpEndpoint

typedef void(*	otTcpEstablished ) ( otTcpEndpoint *aEndpoint)
	This callback informs the application that the TCP 3-way handshake is complete and that the connection is now established.

typedef void(*	otTcpSendDone ) ( otTcpEndpoint aEndpoint, otLinkedBuffer aData)
	This callback informs the application that data in the provided `aData` have been acknowledged by the connection peer and that `aData` and the data it contains can be reclaimed by the application.

typedef void(*	otTcpBytesAcked ) ( otTcpEndpoint *aEndpoint, size_t aNumBytes)
	This callback informs the application that the first `aNumBytes` in the send buffer have been acknowledged by the connection peer and that their underlying memory can be reclaimed by the application.

typedef void(*	otTcpSendReady ) ( otTcpEndpoint *aEndpoint)
	This callback informs the application that if data is added to the send buffer, some of it will be transmitted immediately without delay, as opposed to being queued for transmission once the peer ACKs some data.

typedef void(*	otTcpReceiveAvailable ) ( otTcpEndpoint *aEndpoint, size_t aBytesAvailable, bool aEndOfStream, size_t aBytesRemaining)
	This callback indicates the number of bytes available for consumption from the receive buffer.

typedef enum otTcpDisconnectedReason	otTcpDisconnectedReason

typedef void(*	otTcpDisconnected ) ( otTcpEndpoint *aEndpoint, otTcpDisconnectedReason aReason)
	This callback indicates that the connection was broken and should no longer be used, or that a connection has entered the TIME-WAIT state.

typedef struct otTcpEndpointInitializeArgs	otTcpEndpointInitializeArgs
	This structure contains arguments to the otTcpEndpointInitialize() function.

typedef struct otTcpListener	otTcpListener

typedef enum otTcpIncomingConnectionAction	otTcpIncomingConnectionAction
	This enumeration defines incoming connection actions.

typedef otTcpIncomingConnectionAction (*	otTcpAcceptReady ) ( otTcpListener aListener, const otSockAddr aPeer, otTcpEndpoint **aAcceptInto)
	This callback indicates that an incoming connection that matches this TCP listener has arrived.

typedef void(*	otTcpAcceptDone ) ( otTcpListener aListener, otTcpEndpoint aEndpoint, const otSockAddr *aPeer)
	This callback indicates that the TCP connection is now ready for two-way communication.

typedef struct otTcpListenerInitializeArgs	otTcpListenerInitializeArgs
	This structure contains arguments to the otTcpListenerInitialize() function.

Enumerations
enum	otTcpDisconnectedReason { OT_TCP_DISCONNECTED_REASON_NORMAL , OT_TCP_DISCONNECTED_REASON_REFUSED , OT_TCP_DISCONNECTED_REASON_RESET , OT_TCP_DISCONNECTED_REASON_TIME_WAIT , OT_TCP_DISCONNECTED_REASON_TIMED_OUT }

enum	{ OT_TCP_CONNECT_NO_FAST_OPEN = 1 << 0 }
	This enumeration defines flags passed to otTcpConnect() .

enum	{ OT_TCP_SEND_MORE_TO_COME = 1 << 0 }
	This enumeration defines flags passed to `otTcpSendByReference` .

enum	otTcpIncomingConnectionAction { OT_TCP_INCOMING_CONNECTION_ACTION_ACCEPT , OT_TCP_INCOMING_CONNECTION_ACTION_DEFER , OT_TCP_INCOMING_CONNECTION_ACTION_REFUSE }
	This enumeration defines incoming connection actions.

Functions
otError	otTcpEndpointInitialize ( otInstance aInstance, otTcpEndpoint aEndpoint, otTcpEndpointInitializeArgs *aArgs)
	Initializes a TCP endpoint.

otInstance *	otTcpEndpointGetInstance ( otTcpEndpoint *aEndpoint)
	Obtains the otInstance that was associated with `aEndpoint` upon initialization.

void *	otTcpEndpointGetContext ( otTcpEndpoint *aEndpoint)
	Obtains the context pointer that was associated with `aEndpoint` upon initialization.

const otSockAddr *	otTcpGetLocalAddress (const otTcpEndpoint *aEndpoint)
	Obtains a pointer to a TCP endpoint's local host and port.

const otSockAddr *	otTcpGetPeerAddress (const otTcpEndpoint *aEndpoint)
	Obtains a pointer to a TCP endpoint's peer's host and port.

otError	otTcpBind ( otTcpEndpoint aEndpoint, const otSockAddr aSockName)
	Binds the TCP endpoint to an IP address and port.

otError	otTcpConnect ( otTcpEndpoint aEndpoint, const otSockAddr aSockName, uint32_t aFlags)
	Records the remote host and port for this connection.

otError	otTcpSendByReference ( otTcpEndpoint aEndpoint, otLinkedBuffer aBuffer, uint32_t aFlags)
	Adds data referenced by the linked buffer pointed to by `aBuffer` to the send buffer.

otError	otTcpSendByExtension ( otTcpEndpoint *aEndpoint, size_t aNumBytes, uint32_t aFlags)
	Adds data to the send buffer by extending the length of the final otLinkedBuffer in the send buffer by the specified amount.

otError	otTcpReceiveByReference (const otTcpEndpoint aEndpoint, const otLinkedBuffer *aBuffer)
	Provides the application with a linked buffer chain referencing data currently in the TCP receive buffer.

otError	otTcpReceiveContiguify ( otTcpEndpoint *aEndpoint)
	Reorganizes the receive buffer to be entirely contiguous in memory.

otError	otTcpCommitReceive ( otTcpEndpoint *aEndpoint, size_t aNumBytes, uint32_t aFlags)
	Informs the TCP stack that the application has finished processing `aNumBytes` bytes of data at the start of the receive buffer and that the TCP stack need not continue maintaining those bytes in the receive buffer.

otError	otTcpSendEndOfStream ( otTcpEndpoint *aEndpoint)
	Informs the connection peer that this TCP endpoint will not send more data.

otError	otTcpAbort ( otTcpEndpoint *aEndpoint)
	Forcibly ends the TCP connection associated with this TCP endpoint.

otError	otTcpEndpointDeinitialize ( otTcpEndpoint *aEndpoint)
	Deinitializes this TCP endpoint.

otError	otTcpListenerInitialize ( otInstance aInstance, otTcpListener aListener, otTcpListenerInitializeArgs *aArgs)
	Initializes a TCP listener.

otInstance *	otTcpListenerGetInstance ( otTcpListener *aListener)
	Obtains the otInstance that was associated with `aListener` upon initialization.

void *	otTcpListenerGetContext ( otTcpListener *aListener)
	Obtains the context pointer that was associated with `aListener` upon initialization.

otError	otTcpListen ( otTcpListener aListener, const otSockAddr aSockName)
	Causes incoming TCP connections that match the specified IP address and port to trigger this TCP listener's callbacks.

otError	otTcpStopListening ( otTcpListener *aListener)
	Causes this TCP listener to stop listening for incoming connections.

otError	otTcpListenerDeinitialize ( otTcpListener *aListener)
	Deinitializes this TCP listener.

Detailed Description

This module includes functions that control TCP communication.

Macro Definition Documentation

◆ OT_TCP_RECEIVE_BUFFER_SIZE_FEW_HOPS

#define OT_TCP_RECEIVE_BUFFER_SIZE_FEW_HOPS 2599

Recommended buffer size for TCP connections that traverse about 3 wireless hops or fewer.

On platforms where memory is particularly constrained and in situations where high bandwidth is not necessary, it may be desirable to manually select a smaller buffer size.

◆ OT_TCP_RECEIVE_BUFFER_SIZE_MANY_HOPS

#define OT_TCP_RECEIVE_BUFFER_SIZE_MANY_HOPS 4158

Recommended buffer size for TCP connections that traverse many wireless hops.

If the TCP connection traverses a very large number of hops (more than 6 or so), then it may be advisable to select a large buffer size manually.

Typedef Documentation

◆ otLinkedBuffer

typedef struct otLinkedBuffer otLinkedBuffer

A linked buffer structure for use with TCP.

A single otLinkedBuffer structure references an array of bytes in memory, via mData and mLength. The mNext field is used to form a chain of otLinkedBuffer structures.

◆ otTcpAcceptDone

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

This callback indicates that the TCP connection is now ready for two-way communication.

In the case of TCP Fast Open, this may be before the TCP connection handshake has actually completed. The application is provided with the context pointers both for the TCP listener that accepted the connection and the TCP endpoint into which it was accepted. The provided context is the one associated with the TCP listener.

Parameters

[in]	`aListener`	The TCP listener that matches the incoming connection.
[in]	`aEndpoint`	The TCP endpoint into which the incoming connection was accepted.
[in]	`aPeer`	the host and port from which the incoming connection originated.

◆ otTcpAcceptReady

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

This callback indicates that an incoming connection that matches this TCP listener has arrived.

The typical response is for the application to accept the incoming connection. It does so by populating aAcceptInto with a pointer to the otTcpEndpoint into which to accept the incoming connection. This otTcpEndpoint must already be initialized using otTcpEndpointInitialize() . Then, the application returns OT_TCP_INCOMING_CONNECTION_ACTION_ACCEPT.

Alternatively, the application can decline to accept the incoming connection. There are two ways for the application to do this. First, if the application returns OT_TCP_INCOMING_CONNECTION_ACTION_DEFER, then OpenThread silently ignores the connection establishment request; the connection peer will likely retransmit the request, at which point the callback will be called again. This is valuable if resources are not presently available to accept the connection, but they may be available when the connection peer retransmits its connection establishment attempt. Second, if the application returns OT_TCP_INCOMING_CONNECTION_ACTION_REFUSE, then OpenThread sends a "connection refused" message to the host that attempted to establish a connection. If the application declines the incoming connection, it is not required to populate aAcceptInto .

Parameters

[in]	`aListener`	The TCP listener that matches the incoming connection.
[in]	`aPeer`	The host and port from which the incoming connection originates.
[out]	`aAcceptInto`	The TCP endpoint into which to accept the incoming connection.

Returns: Description of how to handle the incoming connection.

◆ otTcpBytesAcked

typedef void(* otTcpBytesAcked) ( otTcpEndpoint *aEndpoint, size_t aNumBytes)

This callback informs the application that the first aNumBytes in the send buffer have been acknowledged by the connection peer and that their underlying memory can be reclaimed by the application.

This callback is not necessary for correct TCP operation. Most applications can just rely on the otTcpSendDone() callback. If an application wants fine-grained feedback as memory in the send buffer becomes available again (instead of waiting for an entire linked buffer's worth of data becomes available) or some indication as to whether the connection is making forward progress, it can register this callback.

Parameters

[in]	`aEndpoint`	The TCP endpoint for the connection.
[in]	`aNumBytes`	The number of bytes newly acknowledged by the connection peer.

◆ otTcpDisconnected

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

This callback indicates that the connection was broken and should no longer be used, or that a connection has entered the TIME-WAIT state.

It can occur if a connection establishment attempt (initiated by calling otTcpConnect() ) fails, or any point thereafter (e.g., if the connection times out or an RST segment is received from the connection peer). Once this callback fires, all resources that the application provided for this connection (i.e., any otLinkedBuffers and memory they reference, but not the TCP endpoint itself or space for the receive buffers) can be reclaimed. In the case of a connection entering the TIME-WAIT state, this callback is called twice, once upon entry into the TIME-WAIT state (with OT_TCP_DISCONNECTED_REASON_TIME_WAIT, and again when the TIME-WAIT state expires (with OT_TCP_DISCONNECTED_REASON_NORMAL).

Parameters

[in]	`aEndpoint`	The TCP endpoint whose connection has been lost.
[in]	`aReason`	The reason why the connection was lost.

◆ otTcpEstablished

typedef void(* otTcpEstablished) ( otTcpEndpoint *aEndpoint)

This callback informs the application that the TCP 3-way handshake is complete and that the connection is now established.

Parameters

[in] aEndpoint The TCP endpoint whose connection is now established.

◆ otTcpIncomingConnectionAction

typedef enum otTcpIncomingConnectionAction otTcpIncomingConnectionAction

This enumeration defines incoming connection actions.

This is used in otTcpAcceptReady() callback.

◆ otTcpReceiveAvailable

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

This callback indicates the number of bytes available for consumption from the receive buffer.

It is called whenever bytes are added to the receive buffer and when the end of stream is reached. If the end of the stream has been reached (i.e., if no more data will become available to read because the connection peer has closed their end of the connection for writing), then aEndOfStream is true. Finally, aBytesRemaining indicates how much capacity is left in the receive buffer to hold additional data that arrives.

Parameters

[in]	`aEndpoint`	The TCP endpoint for the connection.
[in]	`aBytesAvailable`	The number of bytes in the connection's receive buffer.
[in]	`aEndOfStream`	Indicates if additional data, beyond what is already in the connection's receive buffer, can be received.
[in]	`aBytesRemaining`	The number of additional bytes that can be received before the receive buffer becomes full.

◆ otTcpSendDone

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

This callback informs the application that data in the provided aData have been acknowledged by the connection peer and that aData and the data it contains can be reclaimed by the application.

The aData are guaranteed to be identical to those passed in to TCP via otTcpSendByReference() , including any extensions effected via otTcpSendByExtension() .

Parameters

[in]	`aEndpoint`	The TCP endpoint for the connection.
[in]	`aData`	A pointer to the otLinkedBuffer that can be reclaimed.

◆ otTcpSendReady

typedef void(* otTcpSendReady) ( otTcpEndpoint *aEndpoint)

This callback informs the application that if data is added to the send buffer, some of it will be transmitted immediately without delay, as opposed to being queued for transmission once the peer ACKs some data.

After a call to otTcpSendByReference() or otTcpSendByExtension() , the otTcpSendReady() callback is guaranteed to be called, either immediately (if the connection is already ready) or sometime in the future (once the connection becomes ready for more data).

This callback is not necessary for correct TCP operation. If more data is added to the send buffer than can be transmitted without delay, it will simply be queued for transmission at a later time. This callback should be used only in cases where some assurance is desired that data added to the send buffer will be sent soon (e.g., TCP won't wait for the recipient to ACK some other data first before sending this data out). For example, you may use this callback if you'd rather have your data be dropped than develop a backlog of data in your send buffer. But for most applications, where this isn't a concern, it's expected that one would not use this callback at all.

Parameters

[in] aEndpoint The TCP endpoint for the connection.

Enumeration Type Documentation

◆ otTcpIncomingConnectionAction

enum otTcpIncomingConnectionAction

This enumeration defines incoming connection actions.

This is used in otTcpAcceptReady() callback.

Enumerator
OT_TCP_INCOMING_CONNECTION_ACTION_ACCEPT	Accept the incoming connection.
OT_TCP_INCOMING_CONNECTION_ACTION_DEFER	Defer (silently ignore) the incoming connection.
OT_TCP_INCOMING_CONNECTION_ACTION_REFUSE	Refuse the incoming connection.

Function Documentation

◆ otTcpAbort()

otError otTcpAbort ( otTcpEndpoint * aEndpoint )

Forcibly ends the TCP connection associated with this TCP endpoint.

This immediately makes the TCP endpoint free for use for another connection and empties the send and receive buffers, transferring ownership of any data provided by the application in otTcpSendByReference() calls back to the application. The TCP endpoint's callbacks and memory for the receive buffer remain associated with the TCP endpoint.

Parameters

[in] aEndpoint A pointer to the TCP endpoint structure representing the TCP endpoint to abort.

Return values

`OT_ERROR_NONE`	Successfully aborted the TCP endpoint's connection.
`OT_ERROR_FAILED`	Failed to abort the TCP endpoint's connection.

◆ otTcpBind()

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

Binds the TCP endpoint to an IP address and port.

Parameters

[in]	`aEndpoint`	A pointer to the TCP endpoint structure to bind.
[in]	`aSockName`	The address and port to which to bind this TCP endpoint.

Return values

`OT_ERROR_NONE`	Successfully bound the TCP endpoint.
`OT_ERROR_FAILED`	Failed to bind the TCP endpoint.

◆ otTcpCommitReceive()

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

Informs the TCP stack that the application has finished processing aNumBytes bytes of data at the start of the receive buffer and that the TCP stack need not continue maintaining those bytes in the receive buffer.

Parameters

[in]	`aEndpoint`	A pointer to the TCP endpoint structure representing the TCP endpoint on which to receive data.
[in]	`aNumBytes`	The number of bytes consumed.
[in]	`aFlags`	Flags specifying options for this operation (none yet).

Return values

`OT_ERROR_NONE`	Successfully completed the receive operation.
`OT_ERROR_FAILED`	Failed to complete the receive operation.

◆ otTcpConnect()

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

Records the remote host and port for this connection.

By default TCP Fast Open is used. This means that this function merely records the remote host and port, and that the TCP connection establishment handshake only happens on the first call to otTcpSendByReference() . TCP Fast Open can be explicitly disabled using aFlags , in which case the TCP connection establishment handshake is initiated immediately.

Parameters

[in]	`aEndpoint`	A pointer to the TCP endpoint structure to connect.
[in]	`aSockName`	The IP address and port of the host to which to connect.
[in]	`aFlags`	Flags specifying options for this operation (see enumeration above).

Return values

`OT_ERROR_NONE`	Successfully completed the operation.
`OT_ERROR_FAILED`	Failed to complete the operation.

◆ otTcpEndpointDeinitialize()

otError otTcpEndpointDeinitialize ( otTcpEndpoint * aEndpoint )

Deinitializes this TCP endpoint.

This means that OpenThread no longer keeps track of this TCP endpoint and deallocates all resources it has internally allocated for this TCP endpoint. The application can reuse the memory backing the TCP endpoint as it sees fit.

If it corresponds to a live TCP connection, the connection is terminated unceremoniously (as in otTcpAbort() ). All resources the application has provided for this TCP endpoint (linked buffers for the send buffer, memory for the receive buffer, the aEndpoint structure itself, etc.) are immediately returned to the application.

Parameters

[in] aEndpoint A pointer to the TCP endpoint structure to deinitialize.

Return values

`OT_ERROR_NONE`	Successfully deinitialized the TCP endpoint.
`OT_ERROR_FAILED`	Failed to deinitialize the TCP endpoint.

◆ otTcpEndpointGetContext()

void* otTcpEndpointGetContext ( otTcpEndpoint * aEndpoint )

Obtains the context pointer that was associated with aEndpoint upon initialization.

Parameters

[in] aEndpoint The TCP endpoint whose context to obtain.

Returns: The context pointer associated with aEndpoint .

◆ otTcpEndpointGetInstance()

otInstance * otTcpEndpointGetInstance ( otTcpEndpoint * aEndpoint )

Obtains the otInstance that was associated with aEndpoint upon initialization.

Parameters

[in] aEndpoint The TCP endpoint whose instance to obtain.

Returns: The otInstance pointer associated with aEndpoint .

◆ otTcpEndpointInitialize()

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

Initializes a TCP endpoint.

Calling this function causes OpenThread to keep track of the TCP endpoint and store and retrieve TCP data inside the aEndpoint . The application should refrain from directly accessing or modifying the fields in aEndpoint . If the application needs to reclaim the memory backing aEndpoint , it should call otTcpEndpointDeinitialize() .

Parameters

[in]	`aInstance`	A pointer to an OpenThread instance.
[in]	`aEndpoint`	A pointer to a TCP endpoint structure.
[in]	`aArgs`	A pointer to a structure of arguments.

Return values

`OT_ERROR_NONE`	Successfully opened the TCP endpoint.
`OT_ERROR_FAILED`	Failed to open the TCP endpoint.

◆ otTcpGetLocalAddress()

const otSockAddr * otTcpGetLocalAddress ( const otTcpEndpoint * aEndpoint )

Obtains a pointer to a TCP endpoint's local host and port.

The contents of the host and port may be stale if this socket is not in a connected state and has not been bound after it was last disconnected.

Parameters

[in] aEndpoint The TCP endpoint whose local host and port to obtain.

Returns: The local host and port of aEndpoint .

◆ otTcpGetPeerAddress()

const otSockAddr * otTcpGetPeerAddress ( const otTcpEndpoint * aEndpoint )

Obtains a pointer to a TCP endpoint's peer's host and port.

The contents of the host and port may be stale if this socket is not in a connected state.

Parameters

[in] aEndpoint The TCP endpoint whose peer's host and port to obtain.

Returns: The host and port of the connection peer of aEndpoint .

◆ otTcpListen()

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

Causes incoming TCP connections that match the specified IP address and port to trigger this TCP listener's callbacks.

Parameters

[in]	`aListener`	A pointer to the TCP listener structure that should begin listening.
[in]	`aSockName`	The address and port on which to listen for incoming connections.

Return values

`OT_ERROR_NONE`	Successfully initiated listening on the TCP listener.
`OT_ERROR_FAILED`	Failed to initiate listening on the TCP listener.

◆ otTcpListenerDeinitialize()

otError otTcpListenerDeinitialize ( otTcpListener * aListener )

Deinitializes this TCP listener.

This means that OpenThread no longer keeps track of this TCP listener and deallocates all resources it has internally allocated for this TCP listener. The application can reuse the memory backing the TCP listener as it sees fit.

If the TCP listener is currently listening, it stops listening.

Parameters

[in] aListener A pointer to the TCP listener structure to deinitialize.

Return values

`OT_ERROR_NONE`	Successfully deinitialized the TCP listener.
`OT_ERROR_FAILED`	Failed to deinitialize the TCP listener.

◆ otTcpListenerGetContext()

void* otTcpListenerGetContext ( otTcpListener * aListener )

Obtains the context pointer that was associated with aListener upon initialization.

Parameters

[in] aListener The TCP listener whose context to obtain.

Returns: The context pointer associated with aListener .

◆ otTcpListenerGetInstance()

otInstance * otTcpListenerGetInstance ( otTcpListener * aListener )

Obtains the otInstance that was associated with aListener upon initialization.

Parameters

[in] aListener The TCP listener whose instance to obtain.

Returns: The otInstance pointer associated with aListener .

◆ otTcpListenerInitialize()

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

Initializes a TCP listener.

Calling this function causes OpenThread to keep track of the TCP listener and store and retrieve TCP data inside aListener . The application should refrain from directly accessing or modifying the fields in aListener . If the application needs to reclaim the memory backing aListener , it should call otTcpListenerDeinitialize() .

Parameters

[in]	`aInstance`	A pointer to an OpenThread instance.
[in]	`aListener`	A pointer to a TCP listener structure.
[in]	`aArgs`	A pointer to a structure of arguments.

Return values

`OT_ERROR_NONE`	Successfully opened the TCP listener.
`OT_ERROR_FAILED`	Failed to open the TCP listener.

◆ otTcpReceiveByReference()

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

Provides the application with a linked buffer chain referencing data currently in the TCP receive buffer.

The linked buffer chain is valid until the "receive ready" callback is next invoked, or until the next call to otTcpReceiveContiguify() or otTcpCommitReceive() .

Parameters

[in]	`aEndpoint`	A pointer to the TCP endpoint structure representing the TCP endpoint on which to receive data.
[out]	`aBuffer`	A pointer to the linked buffer chain referencing data currently in the receive buffer.

Return values

`OT_ERROR_NONE`	Successfully completed the operation.
`OT_ERROR_FAILED`	Failed to complete the operation.

◆ otTcpReceiveContiguify()

otError otTcpReceiveContiguify ( otTcpEndpoint * aEndpoint )

Reorganizes the receive buffer to be entirely contiguous in memory.

This is optional; an application can simply traverse the linked buffer chain obtained by calling otTcpReceiveByReference . Some applications may wish to call this function to make the receive buffer contiguous to simplify their data processing, but this comes at the expense of CPU time to reorganize the data in the receive buffer.

Parameters

[in] aEndpoint A pointer to the TCP endpoint whose receive buffer to reorganize.

Return values

`OT_ERROR_NONE`	Successfully completed the operation.
`OT_ERROR_FAILED`	Failed to complete the operation.

◆ otTcpSendByExtension()

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

Adds data to the send buffer by extending the length of the final otLinkedBuffer in the send buffer by the specified amount.

If the send buffer is empty, then the operation fails.

Parameters

[in]	`aEndpoint`	A pointer to the TCP endpoint structure representing the TCP endpoint on which to send data.
[in]	`aNumBytes`	The number of bytes by which to extend the length of the final linked buffer.
[in]	`aFlags`	Flags specifying options for this operation (see enumeration above).

Return values

`OT_ERROR_NONE`	Successfully added data to the send buffer.
`OT_ERROR_FAILED`	Failed to add data to the send buffer.

◆ otTcpSendByReference()

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

Adds data referenced by the linked buffer pointed to by aBuffer to the send buffer.

Upon a successful call to this function, the linked buffer and data it references are owned by the TCP stack; they should not be modified by the application until a "send done" callback returns ownership of those objects to the application. It is acceptable to call this function to add another linked buffer to the send queue, even if the "send done" callback for a previous invocation of this function has not yet fired.

Note that aBuffer should not be chained; its mNext field should be NULL. If additional data will be added right after this call, then the OT_TCP_SEND_MORE_TO_COME flag should be used as a hint to the TCP implementation.

Parameters

[in]	`aEndpoint`	A pointer to the TCP endpoint structure representing the TCP endpoint on which to send data.
[in]	`aBuffer`	A pointer to the linked buffer chain referencing data to add to the send buffer.
[in]	`aFlags`	Flags specifying options for this operation (see enumeration above).

Return values

`OT_ERROR_NONE`	Successfully added data to the send buffer.
`OT_ERROR_FAILED`	Failed to add data to the send buffer.

◆ otTcpSendEndOfStream()

otError otTcpSendEndOfStream ( otTcpEndpoint * aEndpoint )

Informs the connection peer that this TCP endpoint will not send more data.

This should be used when the application has no more data to send to the connection peer. For this connection, future reads on the connection peer will result in the "end of stream" condition, and future writes on this connection endpoint will fail.

The "end of stream" condition only applies after any data previously provided to the TCP stack to send out has been received by the connection peer.

Parameters

[in] aEndpoint A pointer to the TCP endpoint structure representing the TCP endpoint to shut down.

Return values

`OT_ERROR_NONE`	Successfully queued the "end of stream" condition for transmission.
`OT_ERROR_FAILED`	Failed to queue the "end of stream" condition for transmission.

◆ otTcpStopListening()

otError otTcpStopListening ( otTcpListener * aListener )

Causes this TCP listener to stop listening for incoming connections.

Parameters

[in] aListener A pointer to the TCP listener structure that should stop listening.

Return values

`OT_ERROR_NONE`	Successfully stopped listening on the TCP listener.
`OT_ERROR_FAILED`	Failed to stop listening on the TCP listener.

TCP API > IPv6 Networking

Classes

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ OT_TCP_RECEIVE_BUFFER_SIZE_FEW_HOPS

◆ OT_TCP_RECEIVE_BUFFER_SIZE_MANY_HOPS

Typedef Documentation

◆ otLinkedBuffer

◆ otTcpAcceptDone

◆ otTcpAcceptReady

◆ otTcpBytesAcked

◆ otTcpDisconnected

◆ otTcpEstablished

◆ otTcpIncomingConnectionAction

◆ otTcpReceiveAvailable

◆ otTcpSendDone

◆ otTcpSendReady

Enumeration Type Documentation

◆ otTcpIncomingConnectionAction

Function Documentation

◆ otTcpAbort()

◆ otTcpBind()

◆ otTcpCommitReceive()

◆ otTcpConnect()

◆ otTcpEndpointDeinitialize()

◆ otTcpEndpointGetContext()

◆ otTcpEndpointGetInstance()

◆ otTcpEndpointInitialize()

◆ otTcpGetLocalAddress()

◆ otTcpGetPeerAddress()

◆ otTcpListen()

◆ otTcpListenerDeinitialize()

◆ otTcpListenerGetContext()

◆ otTcpListenerGetInstance()

◆ otTcpListenerInitialize()

◆ otTcpReceiveByReference()

◆ otTcpReceiveContiguify()

◆ otTcpSendByExtension()

◆ otTcpSendByReference()

◆ otTcpSendEndOfStream()

◆ otTcpStopListening()

TCP
API > IPv6 Networking