[commissioner] add Dataset and ResignMode (#7352)

This commit adds `Commissioner::Dataset` class which mirrors the
public `otCommissioningDataset`. It also adds `ResignMode` enum
which is used as input to `Stop()` method to indicate whether or
not to resign from being the commissioner.

src/core/api/commissioner_api.cpp

@@ -52,7 +52,7 @@ otError otCommissionerStart(otInstance *                 aInstance,
 
 otError otCommissionerStop(otInstance *aInstance)
 {
-    return AsCoreType(aInstance).Get<MeshCoP::Commissioner>().Stop(/* aResign */ true);
+    return AsCoreType(aInstance).Get<MeshCoP::Commissioner>().Stop();
 }
 
 otError otCommissionerAddJoiner(otInstance *aInstance, const otExtAddress *aEui64, const char *aPskd, uint32_t aTimeout)
@@ -161,7 +161,8 @@ otError otCommissionerSendMgmtSet(otInstance *                  aInstance,
                                   const uint8_t *               aTlvs,
                                   uint8_t                       aLength)
 {
-    return AsCoreType(aInstance).Get<MeshCoP::Commissioner>().SendMgmtCommissionerSetRequest(*aDataset, aTlvs, aLength);
+    return AsCoreType(aInstance).Get<MeshCoP::Commissioner>().SendMgmtCommissionerSetRequest(AsCoreType(aDataset),
+                                                                                             aTlvs, aLength);
 }
 
 uint16_t otCommissionerGetSessionId(otInstance *aInstance)

src/core/meshcop/commissioner.cpp

@@ -129,8 +129,7 @@ void Commissioner::SignalJoinerEvent(JoinerEvent aEvent, const Joiner *aJoiner)
         noJoinerId = true;
     }
 
-    mJoinerCallback(static_cast<otCommissionerJoinerEvent>(aEvent), &joinerInfo, noJoinerId ? nullptr : &joinerId,
+    mJoinerCallback(MapEnum(aEvent), &joinerInfo, noJoinerId ? nullptr : &joinerId, mCallbackContext);
-                    mCallbackContext);
 
 exit:
     return;
@@ -295,9 +294,7 @@ void Commissioner::RemoveJoinerEntry(Commissioner::Joiner &aJoiner)
     SignalJoinerEvent(kJoinerEventRemoved, &joinerCopy);
 }
 
-Error Commissioner::Start(otCommissionerStateCallback  aStateCallback,
+Error Commissioner::Start(StateCallback aStateCallback, JoinerCallback aJoinerCallback, void *aCallbackContext)
-                          otCommissionerJoinerCallback aJoinerCallback,
-                          void *                       aCallbackContext)
 {
     Error error = kErrorNone;
 
@@ -329,7 +326,7 @@ exit:
     return error;
 }
 
-Error Commissioner::Stop(bool aResign)
+Error Commissioner::Stop(ResignMode aResignMode)
 {
     Error error      = kErrorNone;
     bool  needResign = false;
@@ -354,7 +351,7 @@ Error Commissioner::Stop(bool aResign)
 
     SetState(kStateDisabled);
 
-    if (needResign && aResign)
+    if (needResign && (aResignMode == kSendKeepAliveToResign))
     {
         SendKeepAlive();
     }
@@ -402,18 +399,15 @@ exit:
 
 void Commissioner::SendCommissionerSet(void)
 {
-    Error                  error = kErrorNone;
+    Error   error = kErrorNone;
-    otCommissioningDataset dataset;
+    Dataset dataset;
 
     VerifyOrExit(mState == kStateActive, error = kErrorInvalidState);
 
-    memset(&dataset, 0, sizeof(dataset));
+    dataset.Clear();
 
-    dataset.mSessionId      = mSessionId;
+    dataset.SetSessionId(mSessionId);
-    dataset.mIsSessionIdSet = true;
+    ComputeBloomFilter(dataset.UpdateSteeringData());
-
-    ComputeBloomFilter(AsCoreType(&dataset.mSteeringData));
-    dataset.mIsSteeringDataSet = true;
 
     error = SendMgmtCommissionerSetRequest(dataset, nullptr, 0);
 
@@ -745,9 +739,7 @@ exit:
     return;
 }
 
-Error Commissioner::SendMgmtCommissionerSetRequest(const otCommissioningDataset &aDataset,
+Error Commissioner::SendMgmtCommissionerSetRequest(const Dataset &aDataset, const uint8_t *aTlvs, uint8_t aLength)
-                                                   const uint8_t *               aTlvs,
-                                                   uint8_t                       aLength)
 {
     Error            error = kErrorNone;
     Coap::Message *  message;
@@ -758,25 +750,26 @@ Error Commissioner::SendMgmtCommissionerSetRequest(const otCommissioningDataset
     SuccessOrExit(error = message->InitAsConfirmablePost(UriPath::kCommissionerSet));
     SuccessOrExit(error = message->SetPayloadMarker());
 
-    if (aDataset.mIsLocatorSet)
+    if (aDataset.IsLocatorSet())
     {
-        SuccessOrExit(error = Tlv::Append<MeshCoP::BorderAgentLocatorTlv>(*message, aDataset.mLocator));
+        SuccessOrExit(error = Tlv::Append<MeshCoP::BorderAgentLocatorTlv>(*message, aDataset.GetLocator()));
     }
 
-    if (aDataset.mIsSessionIdSet)
+    if (aDataset.IsSessionIdSet())
     {
-        SuccessOrExit(error = Tlv::Append<MeshCoP::CommissionerSessionIdTlv>(*message, aDataset.mSessionId));
+        SuccessOrExit(error = Tlv::Append<MeshCoP::CommissionerSessionIdTlv>(*message, aDataset.GetSessionId()));
     }
 
-    if (aDataset.mIsSteeringDataSet)
+    if (aDataset.IsSteeringDataSet())
     {
-        SuccessOrExit(
+        const SteeringData &steeringData = aDataset.GetSteeringData();
-            error = Tlv::Append<SteeringDataTlv>(*message, aDataset.mSteeringData.m8, aDataset.mSteeringData.mLength));
+
+        SuccessOrExit(error = Tlv::Append<SteeringDataTlv>(*message, steeringData.GetData(), steeringData.GetLength()));
     }
 
-    if (aDataset.mIsJoinerUdpPortSet)
+    if (aDataset.IsJoinerUdpPortSet())
     {
-        SuccessOrExit(error = Tlv::Append<JoinerUdpPortTlv>(*message, aDataset.mJoinerUdpPort));
+        SuccessOrExit(error = Tlv::Append<JoinerUdpPortTlv>(*message, aDataset.GetJoinerUdpPort()));
     }
 
     if (aLength > 0)
@@ -876,7 +869,7 @@ void Commissioner::HandleLeaderPetitionResponse(Coap::Message *         aMessage
     otLogInfoMeshCoP("received Leader Petition response");
 
     SuccessOrExit(Tlv::Find<StateTlv>(*aMessage, state));
-    VerifyOrExit(state == StateTlv::kAccept, IgnoreError(Stop(/* aResign */ false)));
+    VerifyOrExit(state == StateTlv::kAccept, IgnoreError(Stop(kDoNotSendKeepAlive)));
 
     SuccessOrExit(Tlv::Find<CommissionerSessionIdTlv>(*aMessage, mSessionId));
 
@@ -903,7 +896,7 @@ exit:
     {
         if (mTransmitAttempts >= kPetitionRetryCount)
         {
-            IgnoreError(Stop(/* aResign */ false));
+            IgnoreError(Stop(kDoNotSendKeepAlive));
         }
         else
         {
@@ -965,12 +958,12 @@ void Commissioner::HandleLeaderKeepAliveResponse(Coap::Message *         aMessag
 
     VerifyOrExit(mState == kStateActive);
     VerifyOrExit(aResult == kErrorNone && aMessage->GetCode() == Coap::kCodeChanged,
-                 IgnoreError(Stop(/* aResign */ false)));
+                 IgnoreError(Stop(kDoNotSendKeepAlive)));
 
     otLogInfoMeshCoP("received Leader keep-alive response");
 
     SuccessOrExit(Tlv::Find<StateTlv>(*aMessage, state));
-    VerifyOrExit(state == StateTlv::kAccept, IgnoreError(Stop(/* aResign */ false)));
+    VerifyOrExit(state == StateTlv::kAccept, IgnoreError(Stop(kDoNotSendKeepAlive)));
 
     mTimer.Start(Time::SecToMsec(kKeepAliveTimeout) / 2);
 

src/core/meshcop/commissioner.hpp

@@ -43,6 +43,7 @@
 #include "coap/coap.hpp"
 #include "coap/coap_secure.hpp"
 #include "common/as_core_type.hpp"
+#include "common/clearable.hpp"
 #include "common/locator.hpp"
 #include "common/non_copyable.hpp"
 #include "common/timer.hpp"
@@ -74,6 +75,150 @@ public:
         kStateActive   = OT_COMMISSIONER_STATE_ACTIVE,   ///< Active Commissioner.
     };
 
+    /**
+     * This enumeration type represents Joiner Event.
+     *
+     */
+    enum JoinerEvent : uint8_t
+    {
+        kJoinerEventStart     = OT_COMMISSIONER_JOINER_START,
+        kJoinerEventConnected = OT_COMMISSIONER_JOINER_CONNECTED,
+        kJoinerEventFinalize  = OT_COMMISSIONER_JOINER_FINALIZE,
+        kJoinerEventEnd       = OT_COMMISSIONER_JOINER_END,
+        kJoinerEventRemoved   = OT_COMMISSIONER_JOINER_REMOVED,
+    };
+
+    typedef otCommissionerStateCallback  StateCallback;  ///< State change callback function pointer type.
+    typedef otCommissionerJoinerCallback JoinerCallback; ///< Joiner state change callback function pointer type.
+
+    /**
+     * This type represents a Commissioning Dataset.
+     *
+     */
+    class Dataset : public otCommissioningDataset, public Clearable<Dataset>
+    {
+    public:
+        /**
+         * This method 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; }
+
+        /**
+         * This method gets the Border Router RLOC16 Locator in the Dataset.
+         *
+         * This method 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; }
+
+        /**
+         * This method sets the Border Router RLOCG16 Locator in the Dataset.
+         *
+         * @param[in] aLocator  A Locator.
+         *
+         */
+        void SetLocator(uint16_t aLocator)
+        {
+            mIsLocatorSet = true;
+            mLocator      = aLocator;
+        }
+
+        /**
+         * This method 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; }
+
+        /**
+         * This method gets the Session ID in the Dataset.
+         *
+         * This method 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; }
+
+        /**
+         * This method sets the Session ID in the Dataset.
+         *
+         * @param[in] aSessionId  The Session ID.
+         *
+         */
+        void SetSessionId(uint16_t aSessionId)
+        {
+            mIsSessionIdSet = true;
+            mSessionId      = aSessionId;
+        }
+
+        /**
+         * This method 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; }
+
+        /**
+         * This method gets the Steering Data in the Dataset.
+         *
+         * This method 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); }
+
+        /**
+         * This method 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);
+        }
+
+        /**
+         * This method 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; }
+
+        /**
+         * This method gets the Joiner UDP port in the Dataset.
+         *
+         * This method 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; }
+
+        /**
+         * This method sets the Joiner UDP Port in the Dataset.
+         *
+         * @param[in] aJoinerUdpPort  The Joiner UDP Port.
+         *
+         */
+        void SetJoinerUdpPort(uint16_t aJoinerUdpPort)
+        {
+            mIsJoinerUdpPortSet = true;
+            mJoinerUdpPort      = aJoinerUdpPort;
+        }
+    };
+
     /**
      * This constructor initializes the Commissioner object.
      *
@@ -94,20 +239,16 @@ public:
      * @retval kErrorInvalidState   Device is not currently attached to a network.
      *
      */
-    Error Start(otCommissionerStateCallback  aStateCallback,
+    Error Start(StateCallback aStateCallback, JoinerCallback aJoinerCallback, void *aCallbackContext);
-                otCommissionerJoinerCallback aJoinerCallback,
-                void *                       aCallbackContext);
 
     /**
      * This method stops the Commissioner service.
      *
-     * @param[in]  aResign      Whether send LEAD_KA.req to resign as Commissioner
-     *
      * @retval kErrorNone     Successfully stopped the Commissioner service.
      * @retval kErrorAlready  Commissioner is already stopped.
      *
      */
-    Error Stop(bool aResign);
+    Error Stop(void) { return Stop(kSendKeepAliveToResign); }
 
     /**
      * This method clears all Joiner entries.
@@ -294,7 +435,7 @@ public:
      * @retval kErrorInvalidState  Commissioner service is not started.
      *
      */
-    Error SendMgmtCommissionerSetRequest(const otCommissioningDataset &aDataset, const uint8_t *aTlvs, uint8_t aLength);
+    Error SendMgmtCommissionerSetRequest(const Dataset &aDataset, const uint8_t *aTlvs, uint8_t aLength);
 
     /**
      * This method returns a reference to the AnnounceBeginClient instance.
@@ -333,13 +474,10 @@ private:
     static constexpr uint32_t kKeepAliveTimeout     = 50; // TIMEOUT_COMM_PET (seconds)
     static constexpr uint32_t kRemoveJoinerDelay    = 20; // Delay to remove successfully joined joiner
 
-    enum JoinerEvent : uint8_t
+    enum ResignMode : uint8_t
     {
-        kJoinerEventStart     = OT_COMMISSIONER_JOINER_START,
+        kSendKeepAliveToResign,
-        kJoinerEventConnected = OT_COMMISSIONER_JOINER_CONNECTED,
+        kDoNotSendKeepAlive,
-        kJoinerEventFinalize  = OT_COMMISSIONER_JOINER_FINALIZE,
-        kJoinerEventEnd       = OT_COMMISSIONER_JOINER_END,
-        kJoinerEventRemoved   = OT_COMMISSIONER_JOINER_REMOVED,
     };
 
     struct Joiner
@@ -366,6 +504,7 @@ private:
         void CopyToJoinerInfo(otJoinerInfo &aJoiner) const;
     };
 
+    Error   Stop(ResignMode aResignMode);
     Joiner *GetUnusedJoinerEntry(void);
     Joiner *FindJoinerEntry(const Mac::ExtAddress *aEui64);
     Joiner *FindJoinerEntry(const JoinerDiscerner &aDiscerner);
@@ -469,14 +608,16 @@ private:
 
     State mState;
 
-    otCommissionerStateCallback  mStateCallback;
+    StateCallback  mStateCallback;
-    otCommissionerJoinerCallback mJoinerCallback;
+    JoinerCallback mJoinerCallback;
-    void *                       mCallbackContext;
+    void *         mCallbackContext;
 };
 
 } // namespace MeshCoP
 
 DefineMapEnum(otCommissionerState, MeshCoP::Commissioner::State);
+DefineMapEnum(otCommissionerJoinerEvent, MeshCoP::Commissioner::JoinerEvent);
+DefineCoreType(otCommissioningDataset, MeshCoP::Commissioner::Dataset);
 
 } // namespace ot