From c39c4cb2df1b237a4c048cc434e541dbf178f5ee Mon Sep 17 00:00:00 2001 From: Abtin Keshavarzian Date: Fri, 6 Aug 2021 12:22:55 -0700 Subject: [PATCH] [tcp] style changes, typo fixes, and smaller changes (#6871) This commit contains smaller style/code changes in `tcp6` modules. --- include/openthread/instance.h | 2 +- include/openthread/tcp.h | 60 +++++++++++++++++++++++++++++------ src/core/net/tcp6.cpp | 14 ++------ src/core/net/tcp6.hpp | 47 ++++++++++++++++++--------- 4 files changed, 86 insertions(+), 37 deletions(-) diff --git a/include/openthread/instance.h b/include/openthread/instance.h index 0ae0f4228..9bb79e623 100644 --- a/include/openthread/instance.h +++ b/include/openthread/instance.h @@ -53,7 +53,7 @@ extern "C" { * @note This number versions both OpenThread platform and user APIs. * */ -#define OPENTHREAD_API_VERSION (142) +#define OPENTHREAD_API_VERSION (143) /** * @addtogroup api-instance diff --git a/include/openthread/tcp.h b/include/openthread/tcp.h index 9d215b9b1..138e7af23 100644 --- a/include/openthread/tcp.h +++ b/include/openthread/tcp.h @@ -62,10 +62,9 @@ extern "C" { */ typedef struct otLinkedBuffer { - struct otLinkedBuffer - * mNext; ///< Pointer to the next linked buffer in this chain, or NULL if this is the end of the chain - const uint8_t *mData; ///< Pointer to data referenced by this linked buffer - uint16_t mLength; ///< Length of this linked buffer + 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. + uint16_t mLength; ///< Length of this linked buffer (number of bytes). } otLinkedBuffer; struct otTcpEndpoint; @@ -76,6 +75,7 @@ typedef struct otTcpEndpoint otTcpEndpoint; * complete and that the connection is now established. * * @param[in] aEndpoint The TCP endpoint whose connection is now established. + * */ typedef void (*otTcpEstablished)(otTcpEndpoint *aEndpoint); @@ -90,6 +90,7 @@ typedef void (*otTcpEstablished)(otTcpEndpoint *aEndpoint); * * @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); @@ -107,6 +108,7 @@ typedef void (*otTcpSendDone)(otTcpEndpoint *aEndpoint, otLinkedBuffer *aData); * * @param[in] aEndpoint The TCP endpoint for the connection. * @param[in] aNumBytes The number of bytes newly acknowledged by the connection peer. + * */ typedef void (*otTcpBytesAcked)(otTcpEndpoint *aEndpoint, size_t aNumBytes); @@ -131,6 +133,7 @@ typedef void (*otTcpBytesAcked)(otTcpEndpoint *aEndpoint, size_t aNumBytes); * isn't a concern, it's expected that one would not use this callback at all. * * @param[in] aEndpoint The TCP endpoint for the connection. + * */ typedef void (*otTcpSendReady)(otTcpEndpoint *aEndpoint); @@ -151,6 +154,7 @@ typedef void (*otTcpSendReady)(otTcpEndpoint *aEndpoint); * 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, @@ -183,6 +187,7 @@ typedef enum otTcpDisconnectedReason * * @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); @@ -196,6 +201,7 @@ typedef void (*otTcpDisconnected)(otTcpEndpoint *aEndpoint, otTcpDisconnectedRea * 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 { @@ -214,6 +220,7 @@ struct otTcpEndpoint /** * This structure contains arguments to the otTcpEndpointInitialize() function. + * */ typedef struct otTcpEndpointInitializeArgs { @@ -239,6 +246,7 @@ typedef struct otTcpEndpointInitializeArgs * 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 2599 @@ -250,6 +258,7 @@ typedef struct otTcpEndpointInitializeArgs * * 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 4158 @@ -268,6 +277,7 @@ typedef struct otTcpEndpointInitializeArgs * * @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, otTcpEndpointInitializeArgs *aArgs); @@ -278,6 +288,7 @@ otError otTcpEndpointInitialize(otInstance *aInstance, otTcpEndpoint *aEndpoint, * @param[in] aEndpoint The TCP endpoint whose instance to obtain. * * @returns The otInstance pointer associated with @p aEndpoint. + * */ otInstance *otTcpEndpointGetInstance(otTcpEndpoint *aEndpoint); @@ -288,6 +299,7 @@ otInstance *otTcpEndpointGetInstance(otTcpEndpoint *aEndpoint); * @param[in] aEndpoint The TCP endpoint whose context to obtain. * * @returns The context pointer associated with @p aEndpoint. + * */ void *otTcpEndpointGetContext(otTcpEndpoint *aEndpoint); @@ -300,6 +312,7 @@ void *otTcpEndpointGetContext(otTcpEndpoint *aEndpoint); * @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); @@ -312,6 +325,7 @@ const otSockAddr *otTcpGetLocalAddress(const otTcpEndpoint *aEndpoint); * @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); @@ -323,11 +337,13 @@ const otSockAddr *otTcpGetPeerAddress(const otTcpEndpoint *aEndpoint); * * @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); /** * This enumeration defines flags passed to otTcpConnect(). + * */ enum { @@ -349,11 +365,13 @@ enum * * @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); /** * This enumeration defines flags passed to @p otTcpSendByReference. + * */ enum { @@ -364,7 +382,7 @@ enum * Adds data referenced by the linked buffer pointed to by @p aBuffer to the * send buffer. * - * Upon a sucessful call to this function, the linked buffer and data it + * 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 @@ -382,6 +400,7 @@ enum * * @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); @@ -397,6 +416,7 @@ otError otTcpSendByReference(otTcpEndpoint *aEndpoint, otLinkedBuffer *aBuffer, * * @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); @@ -414,6 +434,7 @@ otError otTcpSendByExtension(otTcpEndpoint *aEndpoint, size_t aNumBytes, uint32_ * * @retval OT_ERROR_NONE Successfully completed the operation. * @retval OT_ERROR_FAILED Failed to complete the operation. + * */ otError otTcpReceiveByReference(const otTcpEndpoint *aEndpoint, const otLinkedBuffer **aBuffer); @@ -430,6 +451,7 @@ otError otTcpReceiveByReference(const otTcpEndpoint *aEndpoint, const otLinkedBu * * @retval OT_ERROR_NONE Successfully completed the operation. * @retval OT_ERROR_FAILED Failed to complete the operation. + * */ otError otTcpReceiveContiguify(otTcpEndpoint *aEndpoint); @@ -445,6 +467,7 @@ otError otTcpReceiveContiguify(otTcpEndpoint *aEndpoint); * * @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); @@ -464,6 +487,7 @@ otError otTcpCommitReceive(otTcpEndpoint *aEndpoint, size_t aNumBytes, uint32_t * * @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); @@ -480,6 +504,7 @@ otError otTcpSendEndOfStream(otTcpEndpoint *aEndpoint); * * @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); @@ -500,17 +525,24 @@ otError otTcpAbort(otTcpEndpoint *aEndpoint); * * @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; +/** + * This enumeration defines incoming connection actions. + * + * This is used in otTcpAcceptReady() callback. + * + */ typedef enum otTcpIncomingConnectionAction { - OT_TCP_INCOMING_CONNECTION_ACTION_ACCEPT, - OT_TCP_INCOMING_CONNECTION_ACTION_DEFER, - OT_TCP_INCOMING_CONNECTION_ACTION_REFUSE, + 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; /** @@ -541,6 +573,7 @@ typedef enum otTcpIncomingConnectionAction * @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, @@ -559,17 +592,19 @@ typedef otTcpIncomingConnectionAction (*otTcpAcceptReady)(otTcpListener * aLis * @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); /** * This structure represents a TCP listener. * - * A TCP listener is used to listen for and accept incoming TCP conections. + * 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 { @@ -585,6 +620,7 @@ struct otTcpListener /** * This structure contains arguments to the otTcpListenerInitialize() function. + * */ typedef struct otTcpListenerInitializeArgs { @@ -609,6 +645,7 @@ typedef struct otTcpListenerInitializeArgs * * @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, otTcpListenerInitializeArgs *aArgs); @@ -619,6 +656,7 @@ otError otTcpListenerInitialize(otInstance *aInstance, otTcpListener *aListener, * @param[in] aListener The TCP listener whose instance to obtain. * * @returns The otInstance pointer associated with @p aListener. + * */ otInstance *otTcpListenerGetInstance(otTcpListener *aListener); @@ -629,6 +667,7 @@ otInstance *otTcpListenerGetInstance(otTcpListener *aListener); * @param[in] aListener The TCP listener whose context to obtain. * * @returns The context pointer associated with @p aListener. + * */ void *otTcpListenerGetContext(otTcpListener *aListener); @@ -641,6 +680,7 @@ void *otTcpListenerGetContext(otTcpListener *aListener); * * @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); @@ -651,6 +691,7 @@ otError otTcpListen(otTcpListener *aListener, const otSockAddr *aSockName); * * @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); @@ -668,6 +709,7 @@ otError otTcpStopListening(otTcpListener *aListener); * * @retval OT_ERROR_NONE Successfully deinitialized the TCP listener. * @retval OT_ERROR_FAILED Failed to deinitialize the TCP listener. + * */ otError otTcpListenerDeinitialize(otTcpListener *aListener); diff --git a/src/core/net/tcp6.cpp b/src/core/net/tcp6.cpp index 0b89f223b..9b9dffd3a 100644 --- a/src/core/net/tcp6.cpp +++ b/src/core/net/tcp6.cpp @@ -58,12 +58,7 @@ Error Tcp::Endpoint::Initialize(Instance &aInstance, otTcpEndpointInitializeArgs Instance &Tcp::Endpoint::GetInstance(void) { - return *reinterpret_cast(this->mInstance); -} - -void *Tcp::Endpoint::GetContext(void) -{ - return this->mContext; + return *reinterpret_cast(mInstance); } const SockAddr &Tcp::Endpoint::GetLocalAddress(void) const @@ -154,12 +149,7 @@ Error Tcp::Listener::Initialize(Instance &aInstance, otTcpListenerInitializeArgs Instance &Tcp::Listener::GetInstance(void) { - return *reinterpret_cast(this->mInstance); -} - -void *Tcp::Listener::GetContext(void) -{ - return this->mContext; + return *reinterpret_cast(mInstance); } Error Tcp::Listener::Listen(const SockAddr &aSockName) diff --git a/src/core/net/tcp6.hpp b/src/core/net/tcp6.hpp index d66213ee3..2b555ef0d 100644 --- a/src/core/net/tcp6.hpp +++ b/src/core/net/tcp6.hpp @@ -48,8 +48,6 @@ namespace ot { namespace Ip6 { -class Udp; - /** * @addtogroup core-tcp * @@ -59,6 +57,11 @@ class Udp; * @{ * */ + +/** + * This class implements TCP message handling. + * + */ class Tcp : public InstanceLocator, private NonCopyable { public: @@ -68,9 +71,6 @@ public: */ class Endpoint : public otTcpEndpoint, public LinkedListEntry { - friend class Tcp; - friend class LinkedList; - public: /** * Initializes a TCP endpoint. @@ -78,7 +78,7 @@ public: * Calling this function causes OpenThread to keep track of this Endpoint * and store and retrieve TCP data inside of it. The application * should refrain from directly accessing or modifying the fields in - * this Endpoint. If the application needs to reclaimthe memory backing + * this Endpoint. If the application needs to reclaim the memory backing * this Endpoint, it should call otTcpEndpointDeinitialize(). * * @sa otTcpEndpointInitialize in include/openthread/tcp.h. @@ -88,6 +88,7 @@ public: * * @retval kErrorNone Successfully opened the TCP endpoint. * @retval kErrorFailed Failed to open the TCP endpoint. + * */ Error Initialize(Instance &aInstance, otTcpEndpointInitializeArgs &aArgs); @@ -98,6 +99,7 @@ public: * @sa otTcpEndpointGetInstance * * @returns The Instance pointer associated with this Endpoint. + * */ Instance &GetInstance(void); @@ -108,8 +110,9 @@ public: * @sa otTcpEndpointGetContext * * @returns The context pointer associated with this Endpoint. + * */ - void *GetContext(void); + void *GetContext(void) { return mContext; } /** * Obtains a pointer to a TCP endpoint's local host and port. @@ -120,6 +123,7 @@ public: * @sa otTcpGetLocalAddress * * @returns The local host and port of this Endpoint. + * */ const SockAddr &GetLocalAddress(void) const; @@ -132,6 +136,7 @@ public: * @sa otTcpGetPeerAddress * * @returns The host and port of the connection peer of this Endpoint. + * */ const SockAddr &GetPeerAddress(void) const; @@ -144,6 +149,7 @@ public: * * @retval kErrorNone Successfully bound the TCP endpoint. * @retval kErrorFailed Failed to bind the TCP endpoint. + * */ Error Bind(const SockAddr &aSockName); @@ -163,6 +169,7 @@ public: * * @retval kErrorNone Successfully completed the operation. * @retval kErrorFailed Failed to complete the operation. + * */ Error Connect(const SockAddr &aSockName, uint32_t aFlags); @@ -170,7 +177,7 @@ public: * Adds data referenced by the linked buffer pointed to by @p aBuffer to the * send buffer. * - * Upon a sucessful call to this function, the linked buffer and data it + * 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 @@ -189,6 +196,7 @@ public: * * @retval kErrorNone Successfully added data to the send buffer. * @retval kErrorFailed Failed to add data to the send buffer. + * */ Error SendByReference(otLinkedBuffer &aBuffer, uint32_t aFlags); @@ -205,6 +213,7 @@ public: * * @retval kErrorNone Successfully added data to the send buffer. * @retval kErrorFailed Failed to add data to the send buffer. + * */ Error SendByExtension(size_t aNumBytes, uint32_t aFlags); @@ -239,6 +248,7 @@ public: * * @retval kErrorNone Successfully completed the operation. * @retval kErrorFailed Failed to complete the operation. + * */ Error ReceiveContiguify(void); @@ -254,6 +264,7 @@ public: * * @retval kErrorNone Successfully completed the receive operation. * @retval kErrorFailed Failed to complete the receive operation. + * */ Error CommitReceive(size_t aNumBytes, uint32_t aFlags); @@ -273,6 +284,7 @@ public: * * @retval kErrorNone Successfully queued the "end of stream" condition for transmission. * @retval kErrorFailed Failed to queue the "end of stream" condition for transmission. + * */ Error SendEndOfStream(void); @@ -289,6 +301,7 @@ public: * * @retval kErrorNone Successfully aborted the TCP endpoint's connection. * @retval kErrorFailed Failed to abort the TCP endpoint's connection. + * */ Error Abort(void); @@ -309,18 +322,17 @@ public: * * @retval kErrorNone Successfully deinitialized the TCP endpoint. * @retval kErrorFailed Failed to deinitialize the TCP endpoint. + * */ Error Deinitialize(void); }; /** * This class represents a TCP/IPv6 listener. + * */ class Listener : public otTcpListener, public LinkedListEntry { - friend class Tcp; - friend class LinkedList; - public: /** * Initializes a TCP listener. @@ -338,6 +350,7 @@ public: * * @retval kErrorNone Successfully opened the TCP listener. * @retval kErrorFailed Failed to open the TCP listener. + * */ Error Initialize(Instance &aInstance, otTcpListenerInitializeArgs &aArgs); @@ -348,6 +361,7 @@ public: * @sa otTcpListenerGetInstance * * @returns The otInstance pointer associated with this Listener. + * */ Instance &GetInstance(void); @@ -358,8 +372,9 @@ public: * @sa otTcpListenerGetContext * * @returns The context pointer associated with this Listener. + * */ - void *GetContext(void); + void *GetContext(void) { return mContext; } /** * Causes incoming TCP connections that match the specified IP address and port @@ -371,6 +386,7 @@ public: * * @retval kErrorNone Successfully initiated listening on the TCP listener. * @retval kErrorFailed Failed to initiate listening on the TCP listener. + * */ Error Listen(const SockAddr &aSockName); @@ -381,6 +397,7 @@ public: * * @retval kErrorNone Successfully stopped listening on the TCP listener. * @retval kErrorFailed Failed to stop listening on the TCP listener. + * */ Error StopListening(void); @@ -388,7 +405,7 @@ public: * 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. + * deallocates all resources it has internally allocated for this TCP endpoint. * The application can reuse the memory backing the TCP listener as it sees * fit. * @@ -398,6 +415,7 @@ public: * * @retval kErrorNone Successfully deinitialized the TCP listener. * @retval kErrorFailed Failed to deinitialize the TCP listener. + * */ Error Deinitialize(void); }; @@ -485,7 +503,6 @@ public: uint16_t mWindow; uint16_t mChecksum; uint16_t mUrgentPointer; - } OT_TOOL_PACKED_END; /** @@ -500,7 +517,7 @@ public: * Processes a received TCP segment. * * @param[in] aMessage A reference to the message containing the TCP segment. - * @param[in] aMessageInfo A refernce to the message info associated with @p aMessage. + * @param[in] aMessageInfo A reference to the message info associated with @p aMessage. * * @retval kErrorNone Successfully processed the TCP segment. * @retval kErrorDrop Dropped the TCP segment due to an invalid checksum.