From 0d74e43fa6e40108b906a3c319c751163cc55fd6 Mon Sep 17 00:00:00 2001 From: jrhodie <139580534+jrhodie@users.noreply.github.com> Date: Mon, 6 Nov 2023 15:41:32 -0800 Subject: [PATCH] [docs] TCP Commands - add Doxygen tags (#9578) --- src/cli/cli_tcp.cpp | 185 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 185 insertions(+) diff --git a/src/cli/cli_tcp.cpp b/src/cli/cli_tcp.cpp index 67534f0b9..ddfc098db 100644 --- a/src/cli/cli_tcp.cpp +++ b/src/cli/cli_tcp.cpp @@ -85,6 +85,32 @@ void TcpExample::MbedTlsDebugOutput(void *ctx, int level, const char *file, int } #endif // OPENTHREAD_CONFIG_TLS_ENABLE +/** + * @cli tcp init + * @code + * tcp init tls + * Done + * @endcode + * @cparam tcp init [@ca{mode}] [@ca{size}] + * * The `mode` has three possible values: + * * `tls`: Specifies that the TCP connection between two nodes should also + * use the TLS protocol on top of TCP. When two nodes communicate over TCP, + * both nodes must either use TLS or neither node should use TLS because + * a non-TLS endpoint cannot communicate with a TLS endpoint. + * * `linked` or `circular`: Either one of these options means that TLS + * is not to be used, and the specified buffering type should be used for TCP + * buffering. The behavior of `linked` and `circular` is identical. Examine the code + * for the differences between these two buffering types. + * Two endpoints of a TCP connection are not required to use the same buffering type. + * * The `size` parameter sets the size of the receive buffer to associate with the + * example TCP endpoint. If left unspecified, the maximum size is used. The + * maximum size is set in `OPENTHREAD_CONFIG_CLI_TCP_RECEIVE_BUFFER_SIZE`. + * @par + * Initializes the example TCP listener and the example TCP endpoint provided + * by the `tcp` CLI. + * @sa otTcpListenerInitialize + * @sa otTcpEndpointInitialize + */ template <> otError TcpExample::Process(Arg aArgs[]) { otError error = OT_ERROR_NONE; @@ -234,6 +260,15 @@ exit: return error; } +/** + * @cli tcp deinit + * @code + * tcp deinit + * Done + * @endcode + * @par api_copy + * #otTcpEndpointDeinitialize + */ template <> otError TcpExample::Process(Arg aArgs[]) { otError error = OT_ERROR_NONE; @@ -273,6 +308,23 @@ exit: return error; } +/** + * @cli tcp bind + * @code + * tcp bind :: 30000 + * Done + * @endcode + * @cparam tcp bind @ca{ip} @ca{port} + * * `ip`: IPv6 address to bind to. If you wish to have the TCP/IPv6 stack assign + * the binding IPv6 address, use the unspecified IPv6 address: `::`. + * * `port`: TCP port number to bind to. + * @par + * Associates an IPv6 address and a port to the example TCP endpoint provided by + * the `tcp` CLI. Associating the TCP endpoint to an IPv6 + * address and port is referred to as "naming the TCP endpoint." This binds the + * endpoint for communication. + * @sa otTcpBind + */ template <> otError TcpExample::Process(Arg aArgs[]) { otError error; @@ -290,6 +342,34 @@ exit: return error; } +/** + * @cli tcp connect + * @code + * tcp connect fe80:0:0:0:a8df:580a:860:ffa4 30000 + * Done + * TCP: Connection established + * @endcode + * @code + * tcp connect 172.17.0.1 1234 + * Connecting to synthesized IPv6 address: fdde:ad00:beef:2:0:0:ac11:1 + * Done + * @endcode + * @cparam tcp connect @ca{ip} @ca{port} [@ca{fastopen}] + * * `ip`: IP address of the peer The address can be an IPv4 address, + * which gets synthesized to an IPv6 address using the preferred + * NAT64 prefix from the network data. The command returns `InvalidState` + * when the preferred NAT64 prefix is unavailable. + * * `port`: TCP port number of the peer. + * * `fastopen`: This parameter is optional. If set to `fast`, TCP Fast Open is enabled + * for this connection. Otherwise, if this parameter is set to `slow` or not used, + * TCP Fast Open is disabled. + * @par + * Establishes a connection with the specified peer. + * @par + * If the connection establishment is successful, the resulting TCP connection + * is associated with the example TCP endpoint. + * @sa otTcpConnect + */ template <> otError TcpExample::Process(Arg aArgs[]) { otError error; @@ -357,6 +437,19 @@ exit: return error; } +/** + * @cli tcp send + * @code + * tcp send hello + * Done + * @endcode + * @cparam tcp send @ca{message} + * The `message` parameter contains the message you want to send to the + * remote TCP endpoint. + * @par + * Sends data over the TCP connection associated with the example TCP endpoint + * that is provided with the `tcp` CLI. + */ template <> otError TcpExample::Process(Arg aArgs[]) { otError error; @@ -408,6 +501,28 @@ template <> otError TcpExample::Process(Arg aArgs[]) { otError error = OT_ERROR_NONE; + /** + * @cli tcp benchmark result + * @code + * tcp benchmark result + * TCP Benchmark Status: Ongoing + * Done + * @endcode + * @code + * tcp benchmark result + * TCP Benchmark Status: Completed + * TCP Benchmark Complete: Transferred 73728 bytes in 7056 milliseconds + * TCP Goodput: 83.592 kb/s + * @endcode + * @par + * Shows the latest result of the TCP benchmark test. Possible status values: + * * Ongoing + * * Completed + * * Untested + * @par + * This command is primarily intended for creating scripts that automate + * the TCP benchmark test. + */ if (aArgs[0] == "result") { OutputFormat("TCP Benchmark Status: "); @@ -425,6 +540,23 @@ template <> otError TcpExample::Process(Arg aArgs[]) OutputLine("Untested"); } } + /** + * @cli tcp benchmark run + * @code + * tcp benchmark run + * Done + * TCP Benchmark Complete: Transferred 73728 bytes in 7233 milliseconds + * TCP Goodput: 81.546 kb/s + * @endcode + * @cparam tcp benchmark run [@ca{size}] + * Use the `size` parameter to specify the number of bytes to send + * for the benchmark. If you do not use the `size` parameter, the default + * value (`OPENTHREAD_CONFIG_CLI_TCP_DEFAULT_BENCHMARK_SIZE`) is used. + * @par + * Transfers the specified number of bytes using the TCP connection + * currently associated with the example TCP endpoint provided by the `tcp` CLI. + * @note You must establish a TCP connection before you run this command. + */ else if (aArgs[0] == "run") { VerifyOrExit(!mSendBusy, error = OT_ERROR_BUSY); @@ -481,6 +613,18 @@ exit: return error; } +/** + * @cli tcp sendend + * @code + * tcp sendend + * Done + * @endcode + * @par + * Sends the "end of stream" signal over the TCP connection + * associated with the example TCP endpoint provided by the `tcp` CLI. This + * alerts the peer that it will not receive any more data over this TCP connection. + * @sa otTcpSendEndOfStream + */ template <> otError TcpExample::Process(Arg aArgs[]) { otError error; @@ -494,6 +638,18 @@ exit: return error; } +/** + * @cli tcp abort + * @code + * tcp abort + * TCP: Connection reset + * Done + * @endcode + * @par + * Unceremoniously ends the TCP connection associated with the + * example TCP endpoint, transitioning the TCP endpoint to the closed state. + * @sa otTcpAbort + */ template <> otError TcpExample::Process(Arg aArgs[]) { otError error; @@ -509,6 +665,25 @@ exit: return error; } +/** + * @cli tcp listen + * @code + * tcp listen :: 30000 + * Done + * @endcode + * @cparam tcp listen @ca{ip} @ca{port} + * The following parameters are required: + * * `ip`: IPv6 address or the unspecified IPv6 address (`::`) of the example + * TCP listener provided by the `tcp` CLI. + * * `port`: TCP port of the example TCP listener. + * If no TCP connection is associated with the example TCP endpoint, then any + * incoming connections matching the specified IPv6 address and port are accepted + * and are associated with the example TCP endpoint. + * @par + * Uses the example TCP listener to listen for incoming connections on the + * specified IPv6 address and port. + * @sa otTcpListen + */ template <> otError TcpExample::Process(Arg aArgs[]) { otError error; @@ -527,6 +702,16 @@ exit: return error; } +/** + * @cli tcp stoplistening + * @code + * tcp stoplistening + * Done + * @endcode + * @par + * Instructs the example TCP listener to stop listening for incoming TCP connections. + * @sa otTcpStopListening + */ template <> otError TcpExample::Process(Arg aArgs[]) { otError error;