TCP - Platform

Defines the reason for a TCP connection disconnection.

Represents a TCP connection.

The OpenThread core owns and manages the otPlatTcpConnection instances. The platform should track the pointers to these instances and pass them when invoking the otPlatTcpHandle* callbacks. The otPlatTcpConnection * can be viewed as a "descriptor" or "handle" to the connection.

The otPlatTcpConnection instance remains valid as long as the connection is active.

Defines the reason for a TCP connection disconnection.

Represents a TCP listener.

The OpenThread core owns and manages the otPlatTcpListener instances. The platform should track the pointers to these instances and use them when invoking the callbacks. The otPlatTcpListener * can be viewed as a "descriptor" or "handle" to the listener.

Represents a TCP socket address.

Aborts the TCP connection.

This function forcefully terminates the connection. Any unsent data is discarded.

After this call, the platform must forget the aConn. Importantly, it must not invoke any callbacks using the aConn any longer, including otPlatTcpHandleDisconnected. This effectively indicates to the platform that the OpenThread core is de-allocating the aConn instance and it is no longer valid.

Callback to accept an incoming TCP connection request on an active listener.

This function is implemented and provided by the OpenThread stack for the platform to use.

The callback returns a pointer to an otPlatTcpConnection for the new connection. If the callback returns NULL, the incoming connection is rejected.

Gracefully closes the TCP connection.

This function initiates a graceful closure of the connection. The platform should transmit any remaining data before performing the standard TCP connection termination.

Once the connection is fully disconnected, or if it is already closed, or if an error occurs during the close operation, the platform must indicate this by invoking the otPlatTcpHandleDisconnected callback.

The platform must always call otPlatTcpHandleDisconnected() to report the final outcome of the connection. It is permissible for the platform implementation to invoke this callback directly from within otPlatTcpClose() before returning. The OpenThread stack will handle this correctly.

Initiates a TCP connection to a peer.

The platform should initiate a TCP connection to the aPeerSockAddr.

The aLocalSockAddr specifies the local address and port to bind to before connecting. It can be NULL if the OpenThread stack does not specify a preference. If provided, fields within aLocalSockAddr may still be left unspecified (e.g., the IP address can be all zeros, or the port can be zero). In all such cases, the platform and the underlying TCP stack should automatically select an appropriate local IP address and/or an ephemeral port.

If OT_ERROR_NONE is returned (indicating successful initialization of the connection process), the platform must subsequently report the status. Upon successful connection establishment, the platform must invoke the otPlatTcpHandleConnected callback. If it fails to establish the connection, the otPlatTcpHandleDisconnected callback must be called to indicate the failure.

Disables a TCP listener.

The platform should stop listening for incoming connections on the socket associated with the listener. Any incoming connection requests that have not yet been accepted should be discarded.

Enables a TCP listener.

The platform should start listening for incoming TCP connections on the provided aLocalSockAddr. When an incoming connection request is received, the platform must invoke the otPlatTcpAccept() callback to accept the request.

The aLocalSockAddr specifies the local interface, address, and port to bind to. Importantly, the port number within aLocalSockAddr must not be zero. The IP address may be unspecified (all zeros) to indicate that the listener should accept connections on any local address.

Gets the OpenThread instance associated with a given TCP connection.

This function is provided by OpenThread core. Platform implementations can use it to get the OpenThread instance associated with an active otPlatTcpConnection.

Gets the OpenThread instance associated with a given TCP listener.

This function is provided by OpenThread core. Platform implementations can use it to get the OpenThread instance associated with an active otPlatTcpListener.

Callback to notify the connection establishment.

This callback is implemented and provided by the OpenThread stack. It must be invoked by the platform to indicate that the TCP handshake is complete and that the connection is now established.

The platform must call this after a successful call to otPlatTcpConnect() when the connection is established. For incoming connection requests (on an otPlatTcpListener), the platform must call this after the otPlatTcpAccept() callback returns successfully and when the connection is established.

Callback to notify the connection disconnection.

This function is implemented and provided by the OpenThread stack for the platform to use.

This callback should be invoked by the platform when it fails to establish a connection, when an established connection is successfully closed (by both endpoints), when it times out, or is reset or aborted.

After this callback is invoked, the otPlatTcpConnection instance is no longer valid. The platform must not use it in any future callbacks.

Callback to notify the reception of data on a connection.

This function is implemented and provided by the OpenThread stack for the platform to use.

The platform invokes this callback to provide received data to the OpenThread stack. The provided aBuffer only needs to remain valid for the duration of this call. The OpenThread stack will process and copy the bytes as needed, and will not retain the aBuffer pointer after the function returns.

Since TCP is a stream protocol, data can arrive in arbitrarily sized chunks. The platform does not need to buffer or reassemble these; it can invoke this callback immediately as data is received, even if it is expecting more data. The OpenThread stack handles all stream-level behavior, processing, and retention of the received data. This helps simplify the platform implementation.

On certain platforms (such as standard POSIX), a return value of 0 from read() or recv() indicates an End-of-File (EOF) or graceful closure by the peer. The platform implementation must check for this condition and report it by invoking otPlatTcpHandleDisconnected() with the reason set to OT_PLAT_TCP_DISCONNECT_REASON_CLOSED. Importantly, calling otPlatTcpHandleReceive() with aLength set to zero does not signify a graceful closure in the otPlatTcp APIs; such a call is treated as a no-op receive event by the OpenThread stack and is ignored.

Callback to notify that the platform is ready to accept more transmit data.

This function is implemented and provided by the OpenThread stack for the platform to use.

The platform should invoke this callback when it is ready to accept more data for transmission over the TCP connection, in response to a prior otPlatTcpNotifyTxPending() call. Upon being called, the OpenThread stack will use otPlatTcpSend() to provide the pending TX data to the platform. The stack may call otPlatTcpSend() multiple times during the execution of this callback.

Indicates whether the TCP connection is currently in the connecting state.

This function is provided by the OpenThread stack. The platform can use it to determine if a TCP connection is still waiting for the TCP handshake to complete.

Indicates whether the TCP connection has pending data for transmission.

This function is provided by the OpenThread stack. The platform can use it to check if there is any pending data for transmission over the TCP connection.

Iterates through the active TCP connections.

This function can be used to iterate over all currently active TCP connections associated with the OpenThread instance. It allows platform implementations to process or manage connections without needing to maintain their own list of active connections.

The iteration is guaranteed to remain consistent and safe even if callbacks are invoked during the process. For example, if a connection is reported as disconnected via otPlatTcpHandleDisconnected during iteration, the OpenThread stack ensures that the connection entry remains valid until the iteration is completed.

Iterates through the active TCP listeners.

This function can be used to iterate over all currently active TCP listeners associated with the OpenThread instance. It allows platform implementations to process or manage listeners without needing to maintain their own list of active listeners.

The iteration is guaranteed to remain consistent even if callbacks (e.g., otPlatTcpAccept) are invoked during the process.

Notifies the platform that there is pending data for transmission.

This function is called by the OpenThread stack when it has new data for transmission. After this call, the platform should indicate when it is ready to accept the data by invoking the otPlatTcpHandleTxReady() callback.

The platform can also use otPlatTcpIsTxPending() to check if there is pending data for transmission.

It is permissible for the platform implementation to invoke the otPlatTcpHandleTxReady() callback directly from within otPlatTcpNotifyTxPending() before returning, if the underlying TCP transmit buffer is already available. The OpenThread stack will handle this correctly.

Sends data over an active TCP connection.

This function is called by the OpenThread stack to provide data for the platform to transmit. The data is provided in a buffer. The platform should copy as much data as it can from the given buffer into its underlying platform transmit buffer.

The provided aBuffer is temporary. The platform must not store the pointer or assume the content remains valid after this function returns. All required data must be copied during this call.

The OpenThread stack typically invokes this function from the otPlatTcpHandleTxReady() callback. However, the platform implementation must not assume this and should support being called at any time. If there is no space available to accept any data, the platform can return zero.

The OpenThread stack may call this function multiple times back-to-back to provide all queued transmit content in chunks. The platform should be prepared to handle consecutive calls efficiently.