[nedata] add API to retrieve Commissioning Dataset (openthread#9551)

This commit adds `otNetDataGetCommissioningDataset()` as a public
API to retrieve the Commissioning Dataset from the Network Data.

It also updates CLI `netdata show` command to output the Commissioning
Dataset information. The documentation in `README_NETDATA.md` and
in `cli_network_data` are also updated. The test scripts that parse
`netdata show` output are also updated.

include/openthread/commissioner.h

@@ -111,6 +111,7 @@ typedef struct otCommissioningDataset
     bool mIsSessionIdSet : 1;     ///< TRUE if Commissioner Session Id is set, FALSE otherwise.
     bool mIsSteeringDataSet : 1;  ///< TRUE if Steering Data is set, FALSE otherwise.
     bool mIsJoinerUdpPortSet : 1; ///< TRUE if Joiner UDP Port is set, FALSE otherwise.
+    bool mHasExtraTlv : 1;        ///< TRUE if the Dataset contains any extra unknown sub-TLV, FALSE otherwise.
 } otCommissioningDataset;
 
 #define OT_JOINER_MAX_PSKD_LENGTH 32 ///< Maximum string length of a Joiner PSKd (does not include null char).

include/openthread/instance.h

@@ -53,7 +53,7 @@ extern "C" {
  * @note This number versions both OpenThread platform and user APIs.
  *
  */
-#define OPENTHREAD_API_VERSION (367)
+#define OPENTHREAD_API_VERSION (368)
 
 /**
  * @addtogroup api-instance

include/openthread/netdata.h

@@ -35,6 +35,7 @@
 #ifndef OPENTHREAD_NETDATA_H_
 #define OPENTHREAD_NETDATA_H_
 
+#include <openthread/commissioner.h>
 #include <openthread/ip6.h>
 
 #ifdef __cplusplus
@@ -242,6 +243,15 @@ otError otNetDataGetNextLowpanContextInfo(otInstance            *aInstance,
                                           otNetworkDataIterator *aIterator,
                                           otLowpanContextInfo   *aContextInfo);
 
+/**
+ * Gets the Commissioning Dataset from the partition's Network Data.
+ *
+ * @param[in]  aInstance   A pointer to the OpenThread instance.
+ * @param[out] aDataset    A pointer to a `otCommissioningDataset` to populate.
+ *
+ */
+void otNetDataGetCommissioningDataset(otInstance *aInstance, otCommissioningDataset *aDataset);
+
 /**
  * Get the Network Data Version.
  *

src/cli/README_NETDATA.md

@@ -379,6 +379,15 @@ Service entries are listed under `Services` header:
 - Context ID
 - Compress flag (`c` if marked or `-` otherwise).
 
+Commissioning Dataset information is printed under `Commissioning` header:
+
+- Session ID if present in Dataset or `-` otherwise
+- Border Agent RLOC16 (in hex) if present in Dataset or `-` otherwise
+- Joiner UDP port number if present in Dataset or `-` otherwise
+- Steering Data (as hex bytes) if present in Dataset or `-` otherwise
+- Flags:
+  - e: if Dataset contains any extra unknown TLV
+
 Print Network Data received from the Leader.
 
 ```bash
@@ -392,6 +401,8 @@ Services:
 44970 5d fddead00beef00007bad0069ce45948504d2 s a000
 Contexts:
 fd00:dead:beef:cafe::/64 1 c
+Commissioning:
+1248 dc00 9988 00000000000120000000000000000000 e
 Done
 ```
 

src/cli/cli_network_data.cpp

@@ -662,6 +662,33 @@ void NetworkData::OutputLowpanContexts(bool aLocal)
     return;
 }
 
+void NetworkData::OutputCommissioningDataset(bool aLocal)
+{
+    otCommissioningDataset dataset;
+
+    VerifyOrExit(!aLocal);
+
+    otNetDataGetCommissioningDataset(GetInstancePtr(), &dataset);
+
+    OutputLine("Commissioning:");
+
+    dataset.mIsSessionIdSet ? OutputFormat("%u ", dataset.mSessionId) : OutputFormat("- ");
+    dataset.mIsLocatorSet ? OutputFormat("%04x ", dataset.mLocator) : OutputFormat("- ");
+    dataset.mIsJoinerUdpPortSet ? OutputFormat("%u ", dataset.mJoinerUdpPort) : OutputFormat("- ");
+    dataset.mIsSteeringDataSet ? OutputBytes(dataset.mSteeringData.m8, dataset.mSteeringData.mLength)
+                               : OutputFormat("-");
+
+    if (dataset.mHasExtraTlv)
+    {
+        OutputFormat(" e");
+    }
+
+    OutputNewLine();
+
+exit:
+    return;
+}
+
 otError NetworkData::OutputBinary(bool aLocal)
 {
     otError error;
@@ -701,6 +728,8 @@ otError NetworkData::OutputBinary(bool aLocal)
  * 44970 01 9a04b000000e10 s 4000
  * Contexts:
  * fd00:dead:beef:cafe::/64 1 c
+ * Commissioning:
+ * 1248 dc00 9988 00000000000120000000000000000000 e
  * Done
  * @endcode
  * @code
@@ -751,6 +780,14 @@ otError NetworkData::OutputBinary(bool aLocal)
  * * Context ID
  * * Compress flag (`c` if marked or `-` otherwise).
  * @par
+ * Commissioning Dataset information is printed under `Commissioning` header:
+ * * Session ID if present in Dataset or `-` otherwise
+ * * Border Agent RLOC16 (in hex) if present in Dataset or `-` otherwise
+ * * Joiner UDP port number if present in Dataset or `-` otherwise
+ * * Steering Data (as hex bytes) if present in Dataset or `-` otherwise
+ * * Flags:
+ *   * e: If Dataset contains any extra unknown TLV
+ * @par
  * @moreinfo{@netdata}.
  * @csa{br omrprefix}
  * @csa{br onlinkprefix}
@@ -809,6 +846,7 @@ template <> otError NetworkData::Process<Cmd("show")>(Arg aArgs[])
         OutputRoutes(local);
         OutputServices(local);
         OutputLowpanContexts(local);
+        OutputCommissioningDataset(local);
         error = OT_ERROR_NONE;
     }
 

src/cli/cli_network_data.hpp

@@ -143,6 +143,7 @@ class NetworkData : private Output
     void    OutputRoutes(bool aLocal);
     void    OutputServices(bool aLocal);
     void    OutputLowpanContexts(bool aLocal);
+    void    OutputCommissioningDataset(bool aLocal);
 
 #if OPENTHREAD_CONFIG_BORDER_ROUTER_SIGNAL_NETWORK_DATA_FULL
     static void HandleNetdataFull(void *aContext) { static_cast<NetworkData *>(aContext)->HandleNetdataFull(); }

src/core/api/netdata_api.cpp

@@ -104,6 +104,11 @@ otError otNetDataGetNextLowpanContextInfo(otInstance            *aInstance,
                                                                                      AsCoreType(aContextInfo));
 }
 
+void otNetDataGetCommissioningDataset(otInstance *aInstance, otCommissioningDataset *aDataset)
+{
+    return AsCoreType(aInstance).Get<NetworkData::Leader>().GetCommissioningDataset(AsCoreType(aDataset));
+}
+
 uint8_t otNetDataGetVersion(otInstance *aInstance)
 {
     return AsCoreType(aInstance).Get<Mle::MleRouter>().GetLeaderData().GetDataVersion(NetworkData::kFullSet);

src/core/meshcop/commissioner.cpp

@@ -392,8 +392,8 @@ void Commissioner::ComputeBloomFilter(SteeringData &aSteeringData) const
 
 void Commissioner::SendCommissionerSet(void)
 {
-    Error   error = kErrorNone;
-    Dataset dataset;
+    Error                error = kErrorNone;
+    CommissioningDataset dataset;
 
     VerifyOrExit(mState == kStateActive, error = kErrorInvalidState);
 
@@ -671,7 +671,9 @@ void Commissioner::HandleMgmtCommissionerGetResponse(Coap::Message          *aMe
     return;
 }
 
-Error Commissioner::SendMgmtCommissionerSetRequest(const Dataset &aDataset, const uint8_t *aTlvs, uint8_t aLength)
+Error Commissioner::SendMgmtCommissionerSetRequest(const CommissioningDataset &aDataset,
+                                                   const uint8_t              *aTlvs,
+                                                   uint8_t                     aLength)
 {
     Error            error = kErrorNone;
     Coap::Message   *message;

src/core/meshcop/commissioner.hpp

@@ -96,134 +96,6 @@ class Commissioner : public InstanceLocator, private NonCopyable
     typedef otCommissionerStateCallback  StateCallback;  ///< State change callback function pointer type.
     typedef otCommissionerJoinerCallback JoinerCallback; ///< Joiner state change callback function pointer type.
 
-    /**
-     * Represents a Commissioning Dataset.
-     *
-     */
-    class Dataset : public otCommissioningDataset, public Clearable<Dataset>
-    {
-    public:
-        /**
-         * Indicates whether or not the Border Router RLOC16 Locator is set in the Dataset.
-         *
-         * @returns TRUE if Border Router RLOC16 Locator is set, FALSE otherwise.
-         *
-         */
-        bool IsLocatorSet(void) const { return mIsLocatorSet; }
-
-        /**
-         * Gets the Border Router RLOC16 Locator in the Dataset.
-         *
-         * MUST be used when Locator is set in the Dataset, otherwise its behavior is undefined.
-         *
-         * @returns The Border Router RLOC16 Locator in the Dataset.
-         *
-         */
-        uint16_t GetLocator(void) const { return mLocator; }
-
-        /**
-         * Sets the Border Router RLOCG16 Locator in the Dataset.
-         *
-         * @param[in] aLocator  A Locator.
-         *
-         */
-        void SetLocator(uint16_t aLocator)
-        {
-            mIsLocatorSet = true;
-            mLocator      = aLocator;
-        }
-
-        /**
-         * Indicates whether or not the Session ID is set in the Dataset.
-         *
-         * @returns TRUE if Session ID is set, FALSE otherwise.
-         *
-         */
-        bool IsSessionIdSet(void) const { return mIsSessionIdSet; }
-
-        /**
-         * Gets the Session ID in the Dataset.
-         *
-         * MUST be used when Session ID is set in the Dataset, otherwise its behavior is undefined.
-         *
-         * @returns The Session ID in the Dataset.
-         *
-         */
-        uint16_t GetSessionId(void) const { return mSessionId; }
-
-        /**
-         * Sets the Session ID in the Dataset.
-         *
-         * @param[in] aSessionId  The Session ID.
-         *
-         */
-        void SetSessionId(uint16_t aSessionId)
-        {
-            mIsSessionIdSet = true;
-            mSessionId      = aSessionId;
-        }
-
-        /**
-         * Indicates whether or not the Steering Data is set in the Dataset.
-         *
-         * @returns TRUE if Steering Data is set, FALSE otherwise.
-         *
-         */
-        bool IsSteeringDataSet(void) const { return mIsSteeringDataSet; }
-
-        /**
-         * Gets the Steering Data in the Dataset.
-         *
-         * MUST be used when Steering Data is set in the Dataset, otherwise its behavior is undefined.
-         *
-         * @returns The Steering Data in the Dataset.
-         *
-         */
-        const SteeringData &GetSteeringData(void) const { return AsCoreType(&mSteeringData); }
-
-        /**
-         * Returns a reference to the Steering Data in the Dataset to be updated by caller.
-         *
-         * @returns A reference to the Steering Data in the Dataset.
-         *
-         */
-        SteeringData &UpdateSteeringData(void)
-        {
-            mIsSteeringDataSet = true;
-            return AsCoreType(&mSteeringData);
-        }
-
-        /**
-         * Indicates whether or not the Joiner UDP port is set in the Dataset.
-         *
-         * @returns TRUE if Joiner UDP port is set, FALSE otherwise.
-         *
-         */
-        bool IsJoinerUdpPortSet(void) const { return mIsJoinerUdpPortSet; }
-
-        /**
-         * Gets the Joiner UDP port in the Dataset.
-         *
-         * MUST be used when Joiner UDP port is set in the Dataset, otherwise its behavior is undefined.
-         *
-         * @returns The Joiner UDP port in the Dataset.
-         *
-         */
-        uint16_t GetJoinerUdpPort(void) const { return mJoinerUdpPort; }
-
-        /**
-         * Sets the Joiner UDP Port in the Dataset.
-         *
-         * @param[in] aJoinerUdpPort  The Joiner UDP Port.
-         *
-         */
-        void SetJoinerUdpPort(uint16_t aJoinerUdpPort)
-        {
-            mIsJoinerUdpPortSet = true;
-            mJoinerUdpPort      = aJoinerUdpPort;
-        }
-    };
-
     /**
      * Initializes the Commissioner object.
      *
@@ -460,7 +332,7 @@ class Commissioner : public InstanceLocator, private NonCopyable
      * @retval kErrorInvalidState  Commissioner service is not started.
      *
      */
-    Error SendMgmtCommissionerSetRequest(const Dataset &aDataset, const uint8_t *aTlvs, uint8_t aLength);
+    Error SendMgmtCommissionerSetRequest(const CommissioningDataset &aDataset, const uint8_t *aTlvs, uint8_t aLength);
 
     /**
      * Returns a reference to the AnnounceBeginClient instance.
@@ -633,7 +505,6 @@ DeclareTmfHandler(Commissioner, kUriJoinerFinalize);
 
 DefineMapEnum(otCommissionerState, MeshCoP::Commissioner::State);
 DefineMapEnum(otCommissionerJoinerEvent, MeshCoP::Commissioner::JoinerEvent);
-DefineCoreType(otCommissioningDataset, MeshCoP::Commissioner::Dataset);
 
 } // namespace ot