From be317ecb73604f065820b65fb9501954bff17a6e Mon Sep 17 00:00:00 2001 From: jrhodie <139580534+jrhodie@users.noreply.github.com> Date: Wed, 11 Oct 2023 13:27:37 -0700 Subject: [PATCH] [docs] UDP commands - added Doxygen tags (#9504) --- src/cli/README_UDP.md | 2 +- src/cli/cli_udp.cpp | 151 ++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 152 insertions(+), 1 deletion(-) diff --git a/src/cli/README_UDP.md b/src/cli/README_UDP.md index 14444cdaf14..720aa880fe9 100644 --- a/src/cli/README_UDP.md +++ b/src/cli/README_UDP.md @@ -169,7 +169,7 @@ The address can be an IPv4 address, which will be synthesized to an IPv6 address > Note: The command will return `InvalidState` when the preferred NAT64 prefix is unavailable. ```bash -> udp send 172.17.0.1 1234 +> udp send 172.17.0.1 1234 hello Sending to synthesized IPv6 address: fdde:ad00:beef:2:0:0:ac11:1 Done ``` diff --git a/src/cli/cli_udp.cpp b/src/cli/cli_udp.cpp index d5f37928855..b64facd82ee 100644 --- a/src/cli/cli_udp.cpp +++ b/src/cli/cli_udp.cpp @@ -50,6 +50,35 @@ UdpExample::UdpExample(otInstance *aInstance, OutputImplementer &aOutputImplemen memset(&mSocket, 0, sizeof(mSocket)); } +/** + * @cli udp bind + * @code + * udp bind :: 1234 + * Done + * @endcode + * @code + * udp bind -u :: 1234 + * Done + * @endcode + * @code + * udp bind -b :: 1234 + * Done + * @endcode + * @cparam udp bind [@ca{netif}] @ca{ip} @ca{port} + * - `netif`: The binding network interface, which is determined as follows: + * - No value (leaving out this parameter from the command): Thread network interface is used. + * - `-u`: Unspecified network interface, which means that the UDP/IPv6 stack determines which + * network interface to bind the socket to. + * - `-b`: Backbone network interface is used. + * - `ip`: IPv6 address to bind to. If you wish to have the UDP/IPv6 stack assign the binding + * IPv6 address, then you can use the following value to use the unspecified + * IPv6 address: `::`. Each example uses the unspecified IPv6 address. + * - `port`: UDP port number to bind to. Each of the examples is using port number 1234. + * @par + * Assigns an IPv6 address and a port to an open socket, which binds the socket for communication. + * Assigning the IPv6 address and port is referred to as naming the socket. + * @sa otUdpBind + */ template <> otError UdpExample::Process(Arg aArgs[]) { otError error; @@ -77,6 +106,27 @@ template <> otError UdpExample::Process(Arg aArgs[]) return error; } +/** + * @cli udp connect + * @code + * udp connect fdde:ad00:beef:0:bb1:ebd6:ad10:f33 1234 + * Done + * @endcode + * @code + * udp connect 172.17.0.1 1234 + * Connecting to synthesized IPv6 address: fdde:ad00:beef:2:0:0:ac11:1 + * Done + * @endcode + * @cparam udp connect @ca{ip} @ca{port} + * The following parameters are required: + * - `ip`: IP address of the peer. + * - `port`: UDP port number 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. + * @par api_copy + * #otUdpConnect + */ template <> otError UdpExample::Process(Arg aArgs[]) { otError error; @@ -100,6 +150,15 @@ template <> otError UdpExample::Process(Arg aArgs[]) return error; } +/** + * @cli udp close + * @code + * udp close + * Done + * @endcode + * @par api_copy + * #otUdpClose + */ template <> otError UdpExample::Process(Arg aArgs[]) { OT_UNUSED_VARIABLE(aArgs); @@ -107,6 +166,15 @@ template <> otError UdpExample::Process(Arg aArgs[]) return otUdpClose(GetInstancePtr(), &mSocket); } +/** + * @cli udp open + * @code + * udp open + * Done + * @endcode + * @par api_copy + * #otUdpOpen + */ template <> otError UdpExample::Process(Arg aArgs[]) { OT_UNUSED_VARIABLE(aArgs); @@ -120,6 +188,66 @@ template <> otError UdpExample::Process(Arg aArgs[]) return error; } +/** + * @cli udp send + * @code + * udp send hello + * Done + * @endcode + * @code + * udp send -t hello + * Done + * @endcode + * @code + * udp send -x 68656c6c6f + * Done + * @endcode + * @code + * udp send -s 800 + * Done + * @endcode + * @code + * udp send fdde:ad00:beef:0:bb1:ebd6:ad10:f33 1234 hello + * Done + * @endcode + * @code + * udp send 172.17.0.1 1234 hello + * Sending to synthesized IPv6 address: fdde:ad00:beef:2:0:0:ac11:1 + * Done + * @endcode + * @code + * udp send fdde:ad00:beef:0:bb1:ebd6:ad10:f33 1234 -t hello + * Done + * @endcode + * @code + * udp send fdde:ad00:beef:0:bb1:ebd6:ad10:f33 1234 -x 68656c6c6f + * Done + * @endcode + * @code + * udp send fdde:ad00:beef:0:bb1:ebd6:ad10:f33 1234 -s 800 + * Done + * @endcode + * @cparam udp send [@ca{ip} @ca{port}] [@ca{type}] @ca{value} + * The `ip` and `port` are optional as a pair, but if you specify one you must + * specify the other. If `ip` and `port` are not specified, the socket peer address + * is used from `udp connect`. + * - `ip`: Destination address. This address can be either an IPv4 or IPv6 address, + * An IPv4 address gets synthesized to an IPv6 address with the preferred + * NAT64 prefix from the network data. (If the preferred NAT64 prefix + * is unavailable, the command returns `InvalidState`). + * - `port`: UDP destination port. + * - `type`/`value` combinations: + * - `-t`: The payload in the `value` parameter is treated as text. If no `type` value + * is entered, the payload in the `value` parameter is also treated as text. + * - `-s`: Auto-generated payload with the specified length given in the `value` parameter. + * - `-x`: Binary data in hexadecimal representation given in the `value` parameter. + * @par + * Sends a UDP message using the socket. + * @csa{udp open} + * @csa{udp bind} + * @csa{udp connect} + * @sa otUdpSend + */ template <> otError UdpExample::Process(Arg aArgs[]) { otError error = OT_ERROR_NONE; @@ -201,10 +329,33 @@ template <> otError UdpExample::Process(Arg aArgs[]) { otError error = OT_ERROR_NONE; + /** + * @cli udp linksecurity + * @code + * udp linksecurity + * Enabled + * Done + * @endcode + * @par + * Indicates whether link security is enabled or disabled. + */ if (aArgs[0].IsEmpty()) { OutputEnabledDisabledStatus(mLinkSecurityEnabled); } + /** + * @cli udp linksecurity (enable,disable) + * @code + * udp linksecurity enable + * Done + * @endcode + * @code + * udp linksecurity disable + * Done + * @endcode + * @par + * Enables or disables link security. + */ else { error = Interpreter::ParseEnableOrDisable(aArgs[0], mLinkSecurityEnabled);