openthread/include/openthread/tcp.h

/*
 *  Copyright (c) 2021, The OpenThread Authors.
 *  All rights reserved.
 *
 *  Redistribution and use in source and binary forms, with or without
 *  modification, are permitted provided that the following conditions are met:
 *  1. Redistributions of source code must retain the above copyright
 *     notice, this list of conditions and the following disclaimer.
 *  2. Redistributions in binary form must reproduce the above copyright
 *     notice, this list of conditions and the following disclaimer in the
 *     documentation and/or other materials provided with the distribution.
 *  3. Neither the name of the copyright holder nor the
 *     names of its contributors may be used to endorse or promote products
 *     derived from this software without specific prior written permission.
 *
 *  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 *  AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 *  IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 *  ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
 *  LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
 *  CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
 *  SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
 *  INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
 *  CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
 *  ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 *  POSSIBILITY OF SUCH DAMAGE.
 */

/**
 * @file
 * @brief
 *   This file defines the OpenThread TCP API.
 */

#ifndef OPENTHREAD_TCP_H_
#define OPENTHREAD_TCP_H_

#include <openthread/ip6.h>

#ifdef __cplusplus
extern "C" {
#endif

/**
 * @addtogroup api-tcp
 *
 * @brief
 *   This module includes functions that control TCP communication.
 *
 * @{
 */

/**
 * 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.
 */
typedef struct otLinkedBuffer
{
    struct otLinkedBuffer *mNext;   ///< Pointer to the next linked buffer in the chain, or NULL if it is the end.
    const uint8_t         *mData;   ///< Pointer to data referenced by this linked buffer.
    size_t                 mLength; ///< Length of this linked buffer (number of bytes).
} otLinkedBuffer;

struct otTcpEndpoint;
typedef struct otTcpEndpoint otTcpEndpoint;

/**
 * This callback informs the application that the TCP 3-way handshake is
 * complete and that the connection is now established.
 *
 * @param[in]  aEndpoint  The TCP endpoint whose connection is now established.
 */
typedef void (*otTcpEstablished)(otTcpEndpoint *aEndpoint);

/**
 * This callback informs the application that data in the provided
 * @p aData have been acknowledged by the connection peer and that @p aData and
 * the data it contains can be reclaimed by the application.
 *
 * The @p aData are guaranteed to be identical to those passed in to TCP via
 * otTcpSendByReference(), including any extensions effected via
 * otTcpSendByExtension().
 *
 * @param[in]  aEndpoint  The TCP endpoint for the connection.
 * @param[in]  aData      A pointer to the otLinkedBuffer that can be reclaimed.
 */
typedef void (*otTcpSendDone)(otTcpEndpoint *aEndpoint, otLinkedBuffer *aData);

/**
 * This callback informs the application if forward progress has been made in
 * transferring data from the send buffer to the recipient. This callback is
 * not necessary for correct TCP operation. Most applications can just rely on
 * the otTcpSendDone() callback to reclaim linked buffers once the TCP stack is
 * done using them. The purpose of this callback is to support advanced
 * applications that benefit from finer-grained information about how the
 * the connection is making forward progress in transferring data to the
 * connection peer.
 *
 * This callback's operation is closely tied to TCP's send buffer. The send
 * buffer can be understood as having two regions. First, there is the
 * "in-flight" region at the head (front) of the send buffer. It corresponds
 * to data which has been sent to the recipient, but is not yet acknowledged.
 * Second, there is the "backlog" region, which consists of all data in the
 * send buffer that is not in the "in-flight" region. The "backlog" region
 * corresponds to data that is queued for sending, but has not yet been sent.
 *
 * The callback is invoked in response to two types of events. First, the
 * "in-flight" region of the send buffer may shrink (e.g., when the recipient
 * acknowledges data that we sent earlier). Second, the "backlog" region of the
 * send buffer may shrink (e.g., new data was sent out). These two conditions
 * often occur at the same time, in response to an ACK segment from the
 * connection peer, which is why they are combined in a single callback.
 *
 * The TCP stack only uses the @p aInSendBuffer bytes at the tail of the send
 * buffer; when @p aInSendBuffer decreases by an amount x, it means that x
 * additional bytes that were formerly at the head of the send buffer are no
 * longer part of the send buffer and can now be reclaimed (i.e., overwritten)
 * by the application. Note that the otLinkedBuffer structure itself can only
 * be reclaimed once all bytes that it references are no longer part of the
 * send buffer.
 *
 * This callback subsumes otTcpSendDone(), in the following sense: applications
 * can determine when linked buffers can be reclaimed by comparing
 * @p aInSendBuffer with how many bytes are in each linked buffer. However, we
 * expect otTcpSendDone(), which directly conveys which otLinkedBuffers can be
 * reclaimed, to be much simpler to use. If both callbacks are registered and
 * are triggered by the same event (e.g., the same ACK segment received), then
 * the otTcpSendDone() callback will be triggered first, followed by this
 * callback.
 *
 * Additionally, this callback provides @p aBacklog, which indicates how many
 * bytes of data in the send buffer are not yet in flight. For applications
 * that only want to add data to the send buffer when there is an assurance
 * that it will be sent out soon, it may be desirable to only send out data
 * when @p aBacklog is suitably small (0 or close to 0). For example, an
 * application may use @p aBacklog so that it can react to queue buildup by
 * dropping or aggregating data to avoid creating a backlog of data.
 *
 * After a call to otTcpSendByReference() or otTcpSendByExtension() with a
 * positive number of bytes, the otTcpForwardProgress() callback is guaranteed
 * to be called, to indicate when the bytes that were added to the send buffer
 * are sent out. The call to otTcpForwardProgress() may be made immediately
 * after the bytes are added to the send buffer (if some of those bytes are
 * immediately sent out, reducing the backlog), or sometime in the future (once
 * the connection sends out some or all of the data, reducing the backlog). By
 * "immediately," we mean that the callback is immediately scheduled for
 * execution in a tasklet; to avoid reentrancy-related complexity, the
 * otTcpForwardProgress() callback is never directly called from the
 * otTcpSendByReference() or otTcpSendByExtension() functions.
 *
 * @param[in]  aEndpoint      The TCP endpoint for the connection.
 * @param[in]  aInSendBuffer  The number of bytes in the send buffer (sum of "in-flight" and "backlog" regions).
 * @param[in]  aBacklog       The number of bytes that are queued for sending but have not yet been sent (the "backlog"
 *                            region).
 */
typedef void (*otTcpForwardProgress)(otTcpEndpoint *aEndpoint, size_t aInSendBuffer, size_t aBacklog);

/**
 * 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 @p aEndOfStream is
 * true. Finally, @p aBytesRemaining indicates how much capacity is left in the
 * receive buffer to hold additional data that arrives.
 *
 * @param[in]  aEndpoint        The TCP endpoint for the connection.
 * @param[in]  aBytesAvailable  The number of bytes in the connection's receive buffer.
 * @param[in]  aEndOfStream     Indicates if additional data, beyond what is already in the connection's receive buffer,
 *                              can be received.
 * @param[in]  aBytesRemaining  The number of additional bytes that can be received before the receive buffer becomes
 *                              full.
 */
typedef void (*otTcpReceiveAvailable)(otTcpEndpoint *aEndpoint,
                                      size_t         aBytesAvailable,
                                      bool           aEndOfStream,
                                      size_t         aBytesRemaining);

typedef 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,
} otTcpDisconnectedReason;

/**
 * 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).
 *
 * @param[in]  aEndpoint  The TCP endpoint whose connection has been lost.
 * @param[in]  aReason    The reason why the connection was lost.
 */
typedef void (*otTcpDisconnected)(otTcpEndpoint *aEndpoint, otTcpDisconnectedReason aReason);

/**
 * OT_TCP_ENDPOINT_TCB_SIZE_BASE and OT_TCP_ENDPOINT_TCB_NUM_POINTERS are
 * chosen such that the mTcb field of otTcpEndpoint has the same size as
 * struct tcpcb in TCPlp. This is necessary because the mTcb field, although
 * opaque in its declaration, is treated as struct tcpcb in the TCP
 * implementation.
 */
#define OT_TCP_ENDPOINT_TCB_SIZE_BASE 392
#define OT_TCP_ENDPOINT_TCB_NUM_PTR 36

/**
 * Represents a TCP endpoint.
 *
 * A TCP endpoint acts an endpoint of TCP connection. It can be used to
 * initiate TCP connections, and, once a TCP connection is established, send
 * data to and receive data from the connection peer.
 *
 * The application should not inspect the fields of this structure directly; it
 * should only interact with it via the TCP API functions whose signatures are
 * provided in this file.
 */
struct otTcpEndpoint
{
    union
    {
        uint8_t  mSize[OT_TCP_ENDPOINT_TCB_SIZE_BASE + OT_TCP_ENDPOINT_TCB_NUM_PTR * sizeof(void *)];
        uint64_t mAlign;
    } mTcb;

    struct otTcpEndpoint *mNext;    ///< A pointer to the next TCP endpoint (internal use only)
    void                 *mContext; ///< A pointer to application-specific context

    otTcpEstablished      mEstablishedCallback;      ///< "Established" callback function
    otTcpSendDone         mSendDoneCallback;         ///< "Send done" callback function
    otTcpForwardProgress  mForwardProgressCallback;  ///< "Forward progress" callback function
    otTcpReceiveAvailable mReceiveAvailableCallback; ///< "Receive available" callback function
    otTcpDisconnected     mDisconnectedCallback;     ///< "Disconnected" callback function

    uint32_t mTimers[4];

    otLinkedBuffer mReceiveLinks[2];
    otSockAddr     mSockAddr;

    uint8_t mPendingCallbacks;
};

/**
 * Contains arguments to the otTcpEndpointInitialize() function.
 */
typedef struct otTcpEndpointInitializeArgs
{
    void *mContext; ///< Pointer to application-specific context

    otTcpEstablished      mEstablishedCallback;      ///< "Established" callback function
    otTcpSendDone         mSendDoneCallback;         ///< "Send done" callback function
    otTcpForwardProgress  mForwardProgressCallback;  ///< "Forward progress" callback function
    otTcpReceiveAvailable mReceiveAvailableCallback; ///< "Receive available" callback function
    otTcpDisconnected     mDisconnectedCallback;     ///< "Disconnected" callback function

    void  *mReceiveBuffer;     ///< Pointer to memory provided to the system for the TCP receive buffer
    size_t mReceiveBufferSize; ///< Size of memory provided to the system for the TCP receive buffer
} otTcpEndpointInitializeArgs;

/**
 * @def OT_TCP_RECEIVE_BUFFER_SIZE_FEW_HOPS
 *
 * 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.
 */
#define OT_TCP_RECEIVE_BUFFER_SIZE_FEW_HOPS 2598

/**
 * @def OT_TCP_RECEIVE_BUFFER_SIZE_MANY_HOPS
 *
 * 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.
 */
#define OT_TCP_RECEIVE_BUFFER_SIZE_MANY_HOPS 4157

/**
 * Initializes a TCP endpoint.
 *
 * Calling this function causes OpenThread to keep track of the TCP endpoint
 * and store and retrieve TCP data inside the @p aEndpoint. The application
 * should refrain from directly accessing or modifying the fields in
 * @p aEndpoint. If the application needs to reclaim the memory backing
 * @p aEndpoint, it should call otTcpEndpointDeinitialize().
 *
 * @param[in]  aInstance  A pointer to an OpenThread instance.
 * @param[in]  aEndpoint  A pointer to a TCP endpoint structure.
 * @param[in]  aArgs      A pointer to a structure of arguments.
 *
 * @retval OT_ERROR_NONE    Successfully opened the TCP endpoint.
 * @retval OT_ERROR_FAILED  Failed to open the TCP endpoint.
 */
otError otTcpEndpointInitialize(otInstance                        *aInstance,
                                otTcpEndpoint                     *aEndpoint,
                                const otTcpEndpointInitializeArgs *aArgs);

/**
 * Obtains the otInstance that was associated with @p aEndpoint upon
 * initialization.
 *
 * @param[in]  aEndpoint  The TCP endpoint whose instance to obtain.
 *
 * @returns  The otInstance pointer associated with @p aEndpoint.
 */
otInstance *otTcpEndpointGetInstance(otTcpEndpoint *aEndpoint);

/**
 * Obtains the context pointer that was associated with @p aEndpoint upon
 * initialization.
 *
 * @param[in]  aEndpoint  The TCP endpoint whose context to obtain.
 *
 * @returns  The context pointer associated with @p aEndpoint.
 */
void *otTcpEndpointGetContext(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.
 *
 * @param[in]  aEndpoint  The TCP endpoint whose local host and port to obtain.
 *
 * @returns  The local host and port of @p aEndpoint.
 */
const otSockAddr *otTcpGetLocalAddress(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.
 *
 * @param[in]  aEndpoint  The TCP endpoint whose peer's host and port to obtain.
 *
 * @returns  The host and port of the connection peer of @p aEndpoint.
 */
const otSockAddr *otTcpGetPeerAddress(const otTcpEndpoint *aEndpoint);

/**
 * Binds the TCP endpoint to an IP address and port.
 *
 * @param[in]  aEndpoint   A pointer to the TCP endpoint structure to bind.
 * @param[in]  aSockName   The address and port to which to bind this TCP endpoint.
 *
 * @retval OT_ERROR_NONE    Successfully bound the TCP endpoint.
 * @retval OT_ERROR_FAILED  Failed to bind the TCP endpoint.
 */
otError otTcpBind(otTcpEndpoint *aEndpoint, const otSockAddr *aSockName);

/**
 * Defines flags passed to otTcpConnect().
 */
enum
{
    OT_TCP_CONNECT_NO_FAST_OPEN = 1 << 0,
};

/**
 * Records the remote host and port for this connection.
 *
 * TCP Fast Open must be enabled or disabled using @p aFlags. If it is
 * disabled, then the TCP connection establishment handshake is initiated
 * immediately. If it is enabled, then this function merely records the
 * the remote host and port, and the TCP connection establishment handshake
 * only happens on the first call to `otTcpSendByReference()`.
 *
 * If TCP Fast Open is disabled, then the caller must wait for the
 * `otTcpEstablished` callback indicating that TCP connection establishment
 * handshake is done before it can start sending data e.g., by calling
 * `otTcpSendByReference()`.
 *
 * @param[in]  aEndpoint  A pointer to the TCP endpoint structure to connect.
 * @param[in]  aSockName  The IP address and port of the host to which to connect.
 * @param[in]  aFlags     Flags specifying options for this operation (see enumeration above).
 *
 * @retval OT_ERROR_NONE    Successfully completed the operation.
 * @retval OT_ERROR_FAILED  Failed to complete the operation.
 */
otError otTcpConnect(otTcpEndpoint *aEndpoint, const otSockAddr *aSockName, uint32_t aFlags);

/**
 * Defines flags passed to @p otTcpSendByReference.
 */
enum
{
    OT_TCP_SEND_MORE_TO_COME = 1 << 0,
};

/**
 * Adds data referenced by the linked buffer pointed to by @p 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 @p 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.
 *
 * @param[in]  aEndpoint  A pointer to the TCP endpoint structure representing the TCP endpoint on which to send data.
 * @param[in]  aBuffer    A pointer to the linked buffer chain referencing data to add to the send buffer.
 * @param[in]  aFlags     Flags specifying options for this operation (see enumeration above).
 *
 * @retval OT_ERROR_NONE    Successfully added data to the send buffer.
 * @retval OT_ERROR_FAILED  Failed to add data to the send buffer.
 */
otError otTcpSendByReference(otTcpEndpoint *aEndpoint, otLinkedBuffer *aBuffer, 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.
 *
 * @param[in]  aEndpoint  A pointer to the TCP endpoint structure representing the TCP endpoint on which to send data.
 * @param[in]  aNumBytes  The number of bytes by which to extend the length of the final linked buffer.
 * @param[in]  aFlags     Flags specifying options for this operation (see enumeration above).
 *
 * @retval OT_ERROR_NONE    Successfully added data to the send buffer.
 * @retval OT_ERROR_FAILED  Failed to add data to the send buffer.
 */
otError otTcpSendByExtension(otTcpEndpoint *aEndpoint, size_t aNumBytes, uint32_t aFlags);

/**
 * 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().
 *
 * @param[in]   aEndpoint  A pointer to the TCP endpoint structure representing the TCP endpoint on which to receive
 *                         data.
 * @param[out]  aBuffer    A pointer to the linked buffer chain referencing data currently in the receive buffer.
 *
 * @retval OT_ERROR_NONE    Successfully completed the operation.
 * @retval OT_ERROR_FAILED  Failed to complete the operation.
 */
otError otTcpReceiveByReference(otTcpEndpoint *aEndpoint, const otLinkedBuffer **aBuffer);

/**
 * 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 @p 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.
 *
 * @param[in]   aEndpoint  A pointer to the TCP endpoint whose receive buffer to reorganize.
 *
 * @retval OT_ERROR_NONE    Successfully completed the operation.
 * @retval OT_ERROR_FAILED  Failed to complete the operation.
 */
otError otTcpReceiveContiguify(otTcpEndpoint *aEndpoint);

/**
 * Informs the TCP stack that the application has finished processing
 * @p 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.
 *
 * @param[in]  aEndpoint  A pointer to the TCP endpoint structure representing the TCP endpoint on which to receive
 *                        data.
 * @param[in]  aNumBytes  The number of bytes consumed.
 * @param[in]  aFlags     Flags specifying options for this operation (none yet).
 *
 * @retval OT_ERROR_NONE    Successfully completed the receive operation.
 * @retval OT_ERROR_FAILED  Failed to complete the receive operation.
 */
otError otTcpCommitReceive(otTcpEndpoint *aEndpoint, size_t aNumBytes, uint32_t aFlags);

/**
 * 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.
 *
 * @param[in]  aEndpoint  A pointer to the TCP endpoint structure representing the TCP endpoint to shut down.
 *
 * @retval OT_ERROR_NONE    Successfully queued the "end of stream" condition for transmission.
 * @retval OT_ERROR_FAILED  Failed to queue the "end of stream" condition for transmission.
 */
otError otTcpSendEndOfStream(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() and
 * otTcpSendByExtension() calls back to the application. The TCP endpoint's
 * callbacks and memory for the receive buffer remain associated with the
 * TCP endpoint.
 *
 * @param[in]  aEndpoint  A pointer to the TCP endpoint structure representing the TCP endpoint to abort.
 *
 * @retval OT_ERROR_NONE    Successfully aborted the TCP endpoint's connection.
 * @retval OT_ERROR_FAILED  Failed to abort the TCP endpoint's connection.
 */
otError otTcpAbort(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 @p aEndpoint structure itself, etc.) are
 * immediately returned to the application.
 *
 * @param[in]  aEndpoint  A pointer to the TCP endpoint structure to deinitialize.
 *
 * @retval OT_ERROR_NONE    Successfully deinitialized the TCP endpoint.
 * @retval OT_ERROR_FAILED  Failed to deinitialize the TCP endpoint.
 */
otError otTcpEndpointDeinitialize(otTcpEndpoint *aEndpoint);

struct otTcpListener;
typedef struct otTcpListener otTcpListener;

/**
 * Defines incoming connection actions.
 *
 * This is used in otTcpAcceptReady() callback.
 */
typedef enum otTcpIncomingConnectionAction
{
    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.
} otTcpIncomingConnectionAction;

/**
 * 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 @p 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 @p aAcceptInto.
 *
 * @param[in]   aListener    The TCP listener that matches the incoming connection.
 * @param[in]   aPeer        The host and port from which the incoming connection originates.
 * @param[out]  aAcceptInto  The TCP endpoint into which to accept the incoming connection.
 *
 * @returns  Description of how to handle the incoming connection.
 */
typedef otTcpIncomingConnectionAction (*otTcpAcceptReady)(otTcpListener    *aListener,
                                                          const otSockAddr *aPeer,
                                                          otTcpEndpoint   **aAcceptInto);

/**
 * 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.
 *
 * @param[in]  aListener  The TCP listener that matches the incoming connection.
 * @param[in]  aEndpoint  The TCP endpoint into which the incoming connection was accepted.
 * @param[in]  aPeer      the host and port from which the incoming connection originated.
 */
typedef void (*otTcpAcceptDone)(otTcpListener *aListener, otTcpEndpoint *aEndpoint, const otSockAddr *aPeer);

/**
 * OT_TCP_LISTENER_TCB_SIZE_BASE and OT_TCP_LISTENER_TCB_NUM_POINTERS are
 * chosen such that the mTcbListener field of otTcpListener has the same size
 * as struct tcpcb_listen in TCPlp. This is necessary because the mTcbListen
 * field, though opaque in its declaration, is treated as struct tcpcb in the
 * TCP implementation.
 */
#define OT_TCP_LISTENER_TCB_SIZE_BASE 16
#define OT_TCP_LISTENER_TCB_NUM_PTR 3

/**
 * Represents a TCP listener.
 *
 * A TCP listener is used to listen for and accept incoming TCP connections.
 *
 * The application should not inspect the fields of this structure directly; it
 * should only interact with it via the TCP API functions whose signatures are
 * provided in this file.
 */
struct otTcpListener
{
    union
    {
        uint8_t mSize[OT_TCP_LISTENER_TCB_SIZE_BASE + OT_TCP_LISTENER_TCB_NUM_PTR * sizeof(void *)];
        void   *mAlign;
    } mTcbListen;

    struct otTcpListener *mNext;    ///< A pointer to the next TCP listener (internal use only)
    void                 *mContext; ///< A pointer to application-specific context

    otTcpAcceptReady mAcceptReadyCallback; ///< "Accept ready" callback function
    otTcpAcceptDone  mAcceptDoneCallback;  ///< "Accept done" callback function
};

/**
 * Contains arguments to the otTcpListenerInitialize() function.
 */
typedef struct otTcpListenerInitializeArgs
{
    void *mContext; ///< Pointer to application-specific context

    otTcpAcceptReady mAcceptReadyCallback; ///< "Accept ready" callback function
    otTcpAcceptDone  mAcceptDoneCallback;  ///< "Accept done" callback function
} otTcpListenerInitializeArgs;

/**
 * Initializes a TCP listener.
 *
 * Calling this function causes OpenThread to keep track of the TCP listener
 * and store and retrieve TCP data inside @p aListener. The application should
 * refrain from directly accessing or modifying the fields in @p aListener. If
 * the application needs to reclaim the memory backing @p aListener, it should
 * call otTcpListenerDeinitialize().
 *
 * @param[in]  aInstance  A pointer to an OpenThread instance.
 * @param[in]  aListener  A pointer to a TCP listener structure.
 * @param[in]  aArgs      A pointer to a structure of arguments.
 *
 * @retval OT_ERROR_NONE    Successfully opened the TCP listener.
 * @retval OT_ERROR_FAILED  Failed to open the TCP listener.
 */
otError otTcpListenerInitialize(otInstance                        *aInstance,
                                otTcpListener                     *aListener,
                                const otTcpListenerInitializeArgs *aArgs);

/**
 * Obtains the otInstance that was associated with @p aListener upon
 * initialization.
 *
 * @param[in]  aListener  The TCP listener whose instance to obtain.
 *
 * @returns  The otInstance pointer associated with @p aListener.
 */
otInstance *otTcpListenerGetInstance(otTcpListener *aListener);

/**
 * Obtains the context pointer that was associated with @p aListener upon
 * initialization.
 *
 * @param[in]  aListener  The TCP listener whose context to obtain.
 *
 * @returns  The context pointer associated with @p aListener.
 */
void *otTcpListenerGetContext(otTcpListener *aListener);

/**
 * Causes incoming TCP connections that match the specified IP address and port
 * to trigger this TCP listener's callbacks.
 *
 * @param[in]  aListener  A pointer to the TCP listener structure that should begin listening.
 * @param[in]  aSockName  The address and port on which to listen for incoming connections.
 *
 * @retval OT_ERROR_NONE    Successfully initiated listening on the TCP listener.
 * @retval OT_ERROR_FAILED  Failed to initiate listening on the TCP listener.
 */
otError otTcpListen(otTcpListener *aListener, const otSockAddr *aSockName);

/**
 * Causes this TCP listener to stop listening for incoming connections.
 *
 * @param[in]  aListener  A pointer to the TCP listener structure that should stop listening.
 *
 * @retval OT_ERROR_NONE    Successfully stopped listening on the TCP listener.
 * @retval OT_ERROR_FAILED  Failed to stop listening on the TCP listener.
 */
otError otTcpStopListening(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.
 *
 * @param[in]  aListener  A pointer to the TCP listener structure to deinitialize.
 *
 * @retval OT_ERROR_NONE    Successfully deinitialized the TCP listener.
 * @retval OT_ERROR_FAILED  Failed to deinitialize the TCP listener.
 */
otError otTcpListenerDeinitialize(otTcpListener *aListener);

/**
 * @}
 */

#ifdef __cplusplus
} // extern "C"
#endif

#endif // OPENTHREAD_TCP_H_