From 364e315768982b4b4310d67d718b9ec614f7f0ea Mon Sep 17 00:00:00 2001 From: jrhodie <139580534+jrhodie@users.noreply.github.com> Date: Mon, 20 Nov 2023 16:18:25 -0800 Subject: [PATCH] [cli] add Doxygen tags to SRP commands (#9615) --- src/cli/cli_srp_client.cpp | 375 +++++++++++++++++++++++++++++++++++++ 1 file changed, 375 insertions(+) diff --git a/src/cli/cli_srp_client.cpp b/src/cli/cli_srp_client.cpp index 290dec528..a153059ca 100644 --- a/src/cli/cli_srp_client.cpp +++ b/src/cli/cli_srp_client.cpp @@ -71,6 +71,17 @@ template <> otError SrpClient::Process(Arg aArgs[]) otError error = OT_ERROR_NONE; bool enable; + /** + * @cli srp client autostart (get) + * @code + * srp client autostart + * Disabled + * Done + * @endcode + * @par + * Indicates the current state of auto-start mode (enabled or disabled). + * @sa otSrpClientIsAutoStartModeEnabled + */ if (aArgs[0].IsEmpty()) { OutputEnabledDisabledStatus(otSrpClientIsAutoStartModeEnabled(GetInstancePtr())); @@ -79,10 +90,50 @@ template <> otError SrpClient::Process(Arg aArgs[]) SuccessOrExit(error = Interpreter::ParseEnableOrDisable(aArgs[0], enable)); + /** + * @cli srp client autostart enable + * @code + * srp client autostart enable + * Done + * @endcode + * @par + * Enables auto-start mode. + * @par + * When auto-start is enabled, the SRP client monitors Thread + * network data to discover SRP servers, to select the preferred + * server, and to automatically start and stop the client when + * an SRP server is detected. + * @par + * Three categories of network data entries indicate the presence of an SRP sever, + * and are preferred in the following order: + * -# Unicast entries in which the server address is included in the service + * data. If there are multiple options, the option with the lowest numerical + * IPv6 address is preferred. + * -# Anycast entries that each have a sequence number. The largest sequence + * number as specified by Serial Number Arithmetic Logic + * in RFC-1982 is preferred. + * -# Unicast entries in which the server address information is included + * with the server data. If there are multiple options, the option with the + * lowest numerical IPv6 address is preferred. + * @sa otSrpClientEnableAutoStartMode + */ if (enable) { otSrpClientEnableAutoStartMode(GetInstancePtr(), /* aCallback */ nullptr, /* aContext */ nullptr); } + /** + * @cli srp client autostart disable + * @code + * srp client autostart disable + * Done + * @endcode + * @par + * Disables the auto-start mode. + * @par + * Disabling auto-start mode does not stop a running client. + * However, the SRP client stops monitoring Thread network data. + * @sa otSrpClientDisableAutoStartMode + */ else { otSrpClientDisableAutoStartMode(GetInstancePtr()); @@ -94,6 +145,22 @@ exit: #endif // OPENTHREAD_CONFIG_SRP_CLIENT_AUTO_START_API_ENABLE +/** + * @cli srp client callback (enable/disable, get) + * @code + * srp client callback enable + * Done + * @endcode + * @code + * srp client callback + * Enabled + * Done + * @endcode + * @cparam srp client callback [@ca{enable}|@ca{disable}] + * @par + * Gets or enables/disables printing callback events from the SRP client. + * @sa otSrpClientSetCallback + */ template <> otError SrpClient::Process(Arg aArgs[]) { otError error = OT_ERROR_NONE; @@ -114,10 +181,38 @@ template <> otError SrpClient::Process(Arg aArgs[]) { otError error = OT_ERROR_NONE; + /** + * @cli srp client host + * @code + * srp client host + * name:"dev4312", state:Registered, addrs:[fd00:0:0:0:0:0:0:1234, fd00:0:0:0:0:0:0:beef] + * Done + * @endcode + * @par api_copy + * #otSrpClientGetHostInfo + */ if (aArgs[0].IsEmpty()) { OutputHostInfo(0, *otSrpClientGetHostInfo(GetInstancePtr())); } + /** + * @cli srp client host name (set, get) + * @code + * srp client host name dev4312 + * Done + * @endcode + * @code + * srp client host name + * dev4312 + * Done + * @endcode + * @cparam srp client host name [@ca{name}] + * To set the client host name when the host has either been removed or not yet + * registered with the server, use the `name` parameter. + * @par + * Sets or returns the host name of the SRP client. + * @sa otSrpClientSetHostName + */ else if (aArgs[0] == "name") { if (aArgs[1].IsEmpty()) @@ -149,6 +244,24 @@ template <> otError SrpClient::Process(Arg aArgs[]) IgnoreError(otSrpClientSetHostName(GetInstancePtr(), hostName)); } } + /** + * @cli srp client host state + * @code + * srp client host state + * Registered + * Done + * @endcode + * @par + * Returns the state of the SRP client host. Possible states: + * * `ToAdd`: Item to be added/registered. + * * `Adding`: Item is being added/registered. + * * `ToRefresh`: Item to be refreshed for lease renewal. + * * `Refreshing`: Item is beig refreshed. + * * `ToRemove`: Item to be removed. + * * `Removing`: Item is being removed. + * * `Registered`: Item is registered with server. + * * `Removed`: Item has been removed. + */ else if (aArgs[0] == "state") { VerifyOrExit(aArgs[1].IsEmpty(), error = OT_ERROR_INVALID_ARGS); @@ -156,6 +269,24 @@ template <> otError SrpClient::Process(Arg aArgs[]) } else if (aArgs[0] == "address") { + /** + * @cli srp client host address (get) + * @code + * srp client host address + * auto + * Done + * @endcode + * @code + * srp client host address + * fd00:0:0:0:0:0:0:1234 + * fd00:0:0:0:0:0:0:beef + * Done + * @endcode + * @par + * Indicates whether auto address mode is enabled. If auto address mode is not + * enabled, then the list of SRP client host addresses is returned. + * @sa otSrpClientGetHostInfo + */ if (aArgs[1].IsEmpty()) { const otSrpClientHostInfo *hostInfo = otSrpClientGetHostInfo(GetInstancePtr()); @@ -172,6 +303,33 @@ template <> otError SrpClient::Process(Arg aArgs[]) } } } + /** + * @cli srp client host address (set) + * @code + * srp client host address auto + * Done + * @endcode + * @code + * srp client host address fd00::cafe + * Done + * @endcode + * @cparam srp client host address [auto|@ca{address...}] + * * Use the `auto` parameter to enable auto host address mode. + * When enabled, the client automatically uses all Thread `netif` + * unicast addresses except for link-local and mesh-local + * addresses. If there is no valid address, the mesh local + * EID address gets added. The SRP client automatically + * re-registers if addresses on the Thread `netif` are + * added or removed. + * * Explicitly specify the list of host addresses, separating + * each address by a space. You can set this list while the client is + * running. This will also disable auto host address mode. + * @par + * Enable auto host address mode or explicitly set the list of host + * addresses. + * @sa otSrpClientEnableAutoHostAddress + * @sa otSrpClientSetHostAddresses + */ else if (aArgs[1] == "auto") { error = otSrpClientEnableAutoHostAddress(GetInstancePtr()); @@ -209,6 +367,25 @@ template <> otError SrpClient::Process(Arg aArgs[]) IgnoreError(otSrpClientSetHostAddresses(GetInstancePtr(), hostAddressArray, numAddresses)); } } + /** + * @cli srp client host remove + * @code + * srp client host remove 1 + * Done + * @endcode + * @cparam srp client host remove [@ca{removekeylease}] [@ca{sendunregtoserver}] + * * The parameter `removekeylease` is an optional boolean value that indicates + * whether the host key lease should also be removed (default is `false`). + * * The parameter `sendunregtoserver` is an optional boolean value that indicates + * whether the client host should send an "update" message to the server + * even when the client host information has not yet been registered with the + * server (default is `false`). This parameter can be specified only if the + * `removekeylease` parameter is specified first in the command. + * @par + * Removes SRP client host information and all services from the SRP server. + * @sa otSrpClientRemoveHostAndServices + * @sa otSrpClientSetHostName + */ else if (aArgs[0] == "remove") { bool removeKeyLease = false; @@ -227,6 +404,17 @@ template <> otError SrpClient::Process(Arg aArgs[]) error = otSrpClientRemoveHostAndServices(GetInstancePtr(), removeKeyLease, sendUnregToServer); } + /** + * @cli srp client host clear + * @code + * srp client host clear + * Done + * @endcode + * @par + * Clears all host information and all services. + * @sa otSrpClientClearHostAndServices + * @sa otSrpClientBuffersFreeAllServices + */ else if (aArgs[0] == "clear") { VerifyOrExit(aArgs[1].IsEmpty(), error = OT_ERROR_INVALID_ARGS); @@ -242,11 +430,45 @@ exit: return error; } +/** + * @cli srp client leaseinterval (set, get) + * @code + * srp client leaseinterval 3600 + * Done + * @endcode + * @code + * srp client leaseinterval + * 3600 + * Done + * @endcode + * @cparam srp client leaseinterval [@ca{interval}] + * @par + * Sets or gets the lease interval in seconds. + * @sa otSrpClientSetLeaseInterval + * @sa otSrpClientGetLeaseInterval + */ template <> otError SrpClient::Process(Arg aArgs[]) { return Interpreter::GetInterpreter().ProcessGetSet(aArgs, otSrpClientGetLeaseInterval, otSrpClientSetLeaseInterval); } +/** + * @cli srp client keyleaseinterval (set, get) + * @code + * srp client keyleaseinterval 864000 + * Done + * @endcode + * @code + * srp client keyleaseinterval + * 864000 + * Done + * @endcode + * @cparam srp client keyleaseinterval [@ca{interval}] + * @par + * Sets or gets the key lease interval in seconds. + * @sa otSrpClientSetKeyLeaseInterval + * @sa otSrpClientGetKeyLeaseInterval + */ template <> otError SrpClient::Process(Arg aArgs[]) { return Interpreter::GetInterpreter().ProcessGetSet(aArgs, otSrpClientGetKeyLeaseInterval, @@ -258,6 +480,19 @@ template <> otError SrpClient::Process(Arg aArgs[]) otError error = OT_ERROR_NONE; const otSockAddr *serverSockAddr = otSrpClientGetServerAddress(GetInstancePtr()); + /** + * @cli srp client server + * @code + * srp client server + * [fd00:0:0:0:d88a:618b:384d:e760]:4724 + * Done + * @endcode + * @par + * Gets the socket address (IPv6 address and port number) of the SRP server + * that is being used by the SRP client. If the client is not running, the address + * is unspecified (all zeros) with a port number of 0. + * @sa otSrpClientGetServerAddress + */ if (aArgs[0].IsEmpty()) { OutputSockAddrLine(*serverSockAddr); @@ -266,10 +501,30 @@ template <> otError SrpClient::Process(Arg aArgs[]) VerifyOrExit(aArgs[1].IsEmpty(), error = OT_ERROR_INVALID_ARGS); + /** + * @cli srp client server address + * @code + * srp client server address + * fd00:0:0:0:d88a:618b:384d:e760 + * Done + * @endcode + * @par + * Returns the server's IPv6 address. + */ if (aArgs[0] == "address") { OutputIp6AddressLine(serverSockAddr->mAddress); } + /** + * @cli srp client server port + * @code + * srp client server port + * 4724 + * Done + * @endcode + * @par + * Returns the server's port number. + */ else if (aArgs[0] == "port") { OutputLine("%u", serverSockAddr->mPort); @@ -288,14 +543,70 @@ template <> otError SrpClient::Process(Arg aArgs[]) otError error = OT_ERROR_NONE; bool isRemove; + /** + * @cli srp client service + * @code + * srp client service + * instance:"ins2", name:"_test2._udp,_sub1,_sub2", state:Registered, port:111, priority:1, weight:1 + * instance:"ins1", name:"_test1._udp", state:Registered, port:777, priority:0, weight:0 + * Done + * @endcode + * @par api_copy + * #otSrpClientGetServices + */ if (aArgs[0].IsEmpty()) { OutputServiceList(0, otSrpClientGetServices(GetInstancePtr())); } + /** + * @cli srp client service add + * @code + * srp client service add ins1 _test1._udp 777 + * Done + * @endcode + * @code + * srp client service add ins2 _test2._udp,_sub1,_sub2 111 1 1 + * Done + * @endcode + * @cparam srp client service add @ca{instancename} @ca{servicename} @ca{port} [@ca{priority}] [@ca{weight}] [@ca{txt}] + * The `servicename` parameter can optionally include a list of service subtype labels that are + * separated by commas. The examples here use generic naming. The `priority` and `weight` (both are `uint16_t` + * values) parameters are optional, and if not provided zero is used. The optional `txt` parameter sets the TXT data + * associated with the service. The `txt` value must be in hex-string format and is treated as an already encoded + * TXT data byte sequence. + * @par + * Adds a service with a given instance name, service name, and port number. + * @sa otSrpClientAddService + */ else if (aArgs[0] == "add") { error = ProcessServiceAdd(aArgs); } + /** + * @cli srp client service remove + * @code + * srp client service remove ins2 _test2._udp + * Done + * @endcode + * @cparam srp client service remove @ca{instancename} @ca{servicename} + * @par + * Requests a service to be unregistered with the SRP server. + * @sa otSrpClientRemoveService + */ + /** + * @cli srp client service name clear + * @code + * srp client service clear ins2 _test2._udp + * Done + * @endcode + * @cparam srp client service clear @ca{instancename} @ca{servicename} + * @par + * Clears a service, immediately removing it from the client service list, + * with no interaction with the SRP server. + * @sa otSrpClientClearService + */ else if ((isRemove = (aArgs[0] == "remove")) || (aArgs[0] == "clear")) { // `remove`|`clear` @@ -327,6 +638,23 @@ template <> otError SrpClient::Process(Arg aArgs[]) } } #if OPENTHREAD_CONFIG_REFERENCE_DEVICE_ENABLE + /** + * @cli srp client service key (set, get) + * @code + * srp client service key enable + * Done + * @endcode + * @code + * srp client service key + * Enabled + * Done + * @endcode + * @par + * Gets or sets the service key record inclusion mode in the SRP client. + * This command is intended for testing only, and requires that + * `OPENTHREAD_CONFIG_REFERENCE_DEVICE_ENABLE` be enabled. + * @sa otSrpClientIsServiceKeyRecordEnabled + */ else if (aArgs[0] == "key") { // `key [enable/disable]` @@ -508,6 +836,17 @@ void SrpClient::OutputService(uint8_t aIndentSize, const otSrpClientService &aSe aService.mPort, aService.mPriority, aService.mWeight); } +/** + * @cli srp client start + * @code + * srp client start fd00::d88a:618b:384d:e760 4724 + * Done + * @endcode + * @cparam srp client start @ca{serveraddr} @ca{serverport} + * @par + * Starts the SRP client operation. + * @sa otSrpClientStart + */ template <> otError SrpClient::Process(Arg aArgs[]) { otError error = OT_ERROR_NONE; @@ -523,6 +862,16 @@ exit: return error; } +/** + * @cli srp client state + * @code + * srp client state + * Enabled + * Done + * @endcode + * @par api_copy + * #otSrpClientIsRunning + */ template <> otError SrpClient::Process(Arg aArgs[]) { otError error = OT_ERROR_NONE; @@ -535,6 +884,15 @@ exit: return error; } +/** + * @cli srp client stop + * @code + * srp client stop + * Done + * @endcode + * @par api_copy + * #otSrpClientStop + */ template <> otError SrpClient::Process(Arg aArgs[]) { otError error = OT_ERROR_NONE; @@ -546,6 +904,23 @@ exit: return error; } +/** + * @cli srp client ttl (set, get) + * @code + * srp client ttl 3600 + * Done + * @endcode + * @code + * srp client ttl + * 3600 + * Done + * @endcode + * @cparam srp client ttl [@ca{value}] + * @par + * Sets or gets the `ttl`(time to live) value in seconds. + * @sa otSrpClientSetTtl + * @sa otSrpClientGetTtl + */ template <> otError SrpClient::Process(Arg aArgs[]) { return Interpreter::GetInterpreter().ProcessGetSet(aArgs, otSrpClientGetTtl, otSrpClientSetTtl);