From 045ea0636b832416a5e1691754e7d5de10639619 Mon Sep 17 00:00:00 2001 From: Abtin Keshavarzian Date: Fri, 26 Dec 2025 20:02:19 -0800 Subject: [PATCH] [meshcop] enhance `Joiner` class details and style (#12244) This commit contain style fixes for the `Joiner` for improved clarity and consistency. Changes include: - Rename `mCallback` to `mCompletionCallback` and introduce a new `CompletionCallback` typedef for `otJoinerCallback` to more clearly indicate its purpose. - Improve Doxygen comments for the `State` enum to make them more descriptive. - Replace the use of `OPENTHREAD_CONFIG_JOINER_MAX_CANDIDATES` macro with a new private constant `kMaxJoinerRouterCandidates`. - Reorder private method and member variable declarations in `joiner.hpp` to follow a more consistent style. --- src/core/meshcop/joiner.cpp | 10 ++-- src/core/meshcop/joiner.hpp | 97 +++++++++++++++++-------------------- 2 files changed, 48 insertions(+), 59 deletions(-) diff --git a/src/core/meshcop/joiner.cpp b/src/core/meshcop/joiner.cpp index 802bd8187..ae60510ef 100644 --- a/src/core/meshcop/joiner.cpp +++ b/src/core/meshcop/joiner.cpp @@ -44,8 +44,6 @@ RegisterLogModule("Joiner"); Joiner::Joiner(Instance &aInstance) : InstanceLocator(aInstance) - , mId() - , mDiscerner() , mState(kStateIdle) , mJoinerRouterIndex(0) , mFinalizeMessage(nullptr) @@ -132,7 +130,6 @@ Error Joiner::Start(const char *aPskd, SuccessOrExit(error = joinerPskd.SetFrom(aPskd)); - // Use random-generated extended address. randomAddress.GenerateRandom(); Get().SetExtAddress(randomAddress); Get().UpdateLinkLocalAddress(); @@ -164,7 +161,7 @@ Error Joiner::Start(const char *aPskd, /* aJoiner */ true, /* aEnableFiltering */ true, &filterIndexes, HandleDiscoverResult, this)); - mCallback.Set(aCallback, aContext); + mCompletionCallback.Set(aCallback, aContext); SetState(kStateDiscover); exit: @@ -182,7 +179,7 @@ void Joiner::Stop(void) LogInfo("Joiner stopped"); // Callback is set to `nullptr` to skip calling it from `Finish()` - mCallback.Clear(); + mCompletionCallback.Clear(); Finish(kErrorAbort); } @@ -211,7 +208,7 @@ void Joiner::Finish(Error aError) SetState(kStateIdle); FreeJoinerFinalizeMessage(); - mCallback.InvokeIfSet(aError); + mCompletionCallback.InvokeIfSet(aError); exit: return; @@ -226,7 +223,6 @@ uint8_t Joiner::CalculatePriority(int8_t aRssi, bool aSteeringDataAllowsAny) aRssi = -127; } - // Clamp the RSSI to range [-127, -1] priority = Clamp(aRssi, -127, -1); // Assign higher priority to networks with an exact match of Joiner diff --git a/src/core/meshcop/joiner.hpp b/src/core/meshcop/joiner.hpp index d07a8f779..97c015856 100644 --- a/src/core/meshcop/joiner.hpp +++ b/src/core/meshcop/joiner.hpp @@ -68,17 +68,19 @@ class Joiner : public InstanceLocator, private NonCopyable friend class Tmf::Agent; public: + typedef otJoinerCallback CompletionCallback; ///< Callback to notify the completion of join operation. + /** - * Type defines the Joiner State. + * Represents the Joiner State. */ enum State : uint8_t { - kStateIdle = OT_JOINER_STATE_IDLE, - kStateDiscover = OT_JOINER_STATE_DISCOVER, - kStateConnect = OT_JOINER_STATE_CONNECT, - kStateConnected = OT_JOINER_STATE_CONNECTED, - kStateEntrust = OT_JOINER_STATE_ENTRUST, - kStateJoined = OT_JOINER_STATE_JOINED, + kStateIdle = OT_JOINER_STATE_IDLE, ///< Idle state. + kStateDiscover = OT_JOINER_STATE_DISCOVER, ///< Discovering Joiner Routers (performing scan). + kStateConnect = OT_JOINER_STATE_CONNECT, ///< Establishing a connection to commissioner. + kStateConnected = OT_JOINER_STATE_CONNECTED, ///< Successfully connected to commissioner. + kStateEntrust = OT_JOINER_STATE_ENTRUST, ///< Waiting to receive Joiner Entrust message. + kStateJoined = OT_JOINER_STATE_JOINED, ///< Join completed successfully. }; /** @@ -104,14 +106,14 @@ public: * @retval kErrorBusy The previous attempt is still on-going. * @retval kErrorInvalidState The IPv6 stack is not enabled or Thread stack is fully enabled. */ - Error Start(const char *aPskd, - const char *aProvisioningUrl, - const char *aVendorName, - const char *aVendorModel, - const char *aVendorSwVersion, - const char *aVendorData, - otJoinerCallback aCallback, - void *aContext); + Error Start(const char *aPskd, + const char *aProvisioningUrl, + const char *aVendorName, + const char *aVendorModel, + const char *aVendorSwVersion, + const char *aVendorData, + CompletionCallback aCallback, + void *aContext); /** * Stops the Joiner service. @@ -176,10 +178,10 @@ public: static const char *StateToString(State aState); private: - static constexpr uint16_t kJoinerUdpPort = OPENTHREAD_CONFIG_JOINER_UDP_PORT; - - static constexpr uint32_t kConfigExtAddressDelay = 100; // in msec. - static constexpr uint32_t kResponseTimeout = 4000; ///< Max wait time to receive response (in msec). + static constexpr uint16_t kMaxJoinerRouterCandidates = OPENTHREAD_CONFIG_JOINER_MAX_CANDIDATES; + static constexpr uint16_t kJoinerUdpPort = OPENTHREAD_CONFIG_JOINER_UDP_PORT; + static constexpr uint32_t kConfigExtAddressDelay = 100; // in msec. + static constexpr uint32_t kResponseTimeout = 4000; // in msec struct JoinerRouter { @@ -190,9 +192,24 @@ private: uint8_t mPriority; }; + void SetState(State aState); + void SetIdFromIeeeEui64(void); + void SaveDiscoveredJoinerRouter(const Mle::DiscoverScanner::ScanResult &aResult); + void TryNextJoinerRouter(Error aPrevError); + Error Connect(JoinerRouter &aRouter); + void Finish(Error aError); + void HandleTimer(void); + uint8_t CalculatePriority(int8_t aRssi, bool aSteeringDataAllowsAny); + Error PrepareJoinerFinalizeMessage(const char *aProvisioningUrl, + const char *aVendorName, + const char *aVendorModel, + const char *aVendorSwVersion, + const char *aVendorData); + void FreeJoinerFinalizeMessage(void); + void SendJoinerFinalize(void); + void SendJoinerEntrustResponse(const Coap::Message &aRequest, const Ip6::MessageInfo &aRequestInfo); static void HandleDiscoverResult(Mle::DiscoverScanner::ScanResult *aResult, void *aContext); void HandleDiscoverResult(Mle::DiscoverScanner::ScanResult *aResult); - static void HandleSecureCoapClientConnect(Dtls::Session::ConnectEvent aEvent, void *aContext); void HandleSecureCoapClientConnect(Dtls::Session::ConnectEvent aEvent); @@ -200,40 +217,16 @@ private: template void HandleTmf(Coap::Message &aMessage, const Ip6::MessageInfo &aMessageInfo); - void HandleTimer(void); - - void SetState(State aState); - void SetIdFromIeeeEui64(void); - void SaveDiscoveredJoinerRouter(const Mle::DiscoverScanner::ScanResult &aResult); - void TryNextJoinerRouter(Error aPrevError); - Error Connect(JoinerRouter &aRouter); - void Finish(Error aError); - uint8_t CalculatePriority(int8_t aRssi, bool aSteeringDataAllowsAny); - - Error PrepareJoinerFinalizeMessage(const char *aProvisioningUrl, - const char *aVendorName, - const char *aVendorModel, - const char *aVendorSwVersion, - const char *aVendorData); - void FreeJoinerFinalizeMessage(void); - void SendJoinerFinalize(void); - void SendJoinerEntrustResponse(const Coap::Message &aRequest, const Ip6::MessageInfo &aRequestInfo); - using JoinerTimer = TimerMilliIn; - Mac::ExtAddress mId; - JoinerDiscerner mDiscerner; - - State mState; - - Callback mCallback; - - JoinerRouter mJoinerRouters[OPENTHREAD_CONFIG_JOINER_MAX_CANDIDATES]; - uint16_t mJoinerRouterIndex; - - Coap::Message *mFinalizeMessage; - - JoinerTimer mTimer; + Mac::ExtAddress mId; + JoinerDiscerner mDiscerner; + State mState; + Callback mCompletionCallback; + JoinerRouter mJoinerRouters[kMaxJoinerRouterCandidates]; + uint16_t mJoinerRouterIndex; + Coap::Message *mFinalizeMessage; + JoinerTimer mTimer; }; DeclareTmfHandler(Joiner, kUriJoinerEntrust);