From 5d0853c8c9615574d64533254b77cd1b770d91b8 Mon Sep 17 00:00:00 2001 From: Yang Sun Date: Wed, 23 Oct 2024 20:11:45 +0800 Subject: [PATCH] [border-agent] update docs for set and clear ephemeral key APIs (#10854) The docs are updated to mention that users can use the `otBorderAgentDisconnect()` API to forcely disconnect from commissioner sessions. --- include/openthread/border_agent.h | 4 +++- include/openthread/instance.h | 2 +- src/core/meshcop/border_agent.hpp | 6 ++++-- 3 files changed, 8 insertions(+), 4 deletions(-) diff --git a/include/openthread/border_agent.h b/include/openthread/border_agent.h index 39fdfdc943a..bfe0e746142 100644 --- a/include/openthread/border_agent.h +++ b/include/openthread/border_agent.h @@ -187,6 +187,7 @@ otError otBorderAgentSetId(otInstance *aInstance, const otBorderAgentId *aId); * * The ephemeral key can be set when the Border Agent is already running and is not currently connected to any external * commissioner (i.e., it is in `OT_BORDER_AGENT_STATE_STARTED` state). Otherwise `OT_ERROR_INVALID_STATE` is returned. + * To terminate active commissioner sessions, use the `otBorderAgentDisconnect()` API. * * The given @p aKeyString is directly used as the ephemeral PSK (excluding the trailing null `\0` character ). * The @p aKeyString length must be between `OT_BORDER_AGENT_MIN_EPHEMERAL_KEY_LENGTH` and @@ -230,7 +231,8 @@ otError otBorderAgentSetEphemeralKey(otInstance *aInstance, * * If a commissioner is connected using the ephemeral key and is currently active, calling this function does not * change its state. In this case the `otBorderAgentIsEphemeralKeyActive()` will continue to return `TRUE` until the - * commissioner disconnects, or the ephemeral key timeout expires. + * commissioner disconnects, or the ephemeral key timeout expires. To terminate active commissioner sessions, use the + * `otBorderAgentDisconnect()` API. * * @param[in] aInstance The OpenThread instance. */ diff --git a/include/openthread/instance.h b/include/openthread/instance.h index 1eeb751e866..3dfe84fdd28 100644 --- a/include/openthread/instance.h +++ b/include/openthread/instance.h @@ -52,7 +52,7 @@ extern "C" { * * @note This number versions both OpenThread platform and user APIs. */ -#define OPENTHREAD_API_VERSION (456) +#define OPENTHREAD_API_VERSION (457) /** * @addtogroup api-instance diff --git a/src/core/meshcop/border_agent.hpp b/src/core/meshcop/border_agent.hpp index 6f1eb0bc3e4..7091b0e798d 100644 --- a/src/core/meshcop/border_agent.hpp +++ b/src/core/meshcop/border_agent.hpp @@ -173,7 +173,8 @@ class BorderAgent : public InstanceLocator, private NonCopyable * Sets the ephemeral key for a given timeout duration. * * The ephemeral key can be set when the Border Agent is already running and is not currently connected to any - * external commissioner (i.e., it is in `kStateStarted` state). + * external commissioner (i.e., it is in `kStateStarted` state). To terminate active commissioner sessions, + * use the `Disconnect()` function. * * The given @p aKeyString is directly used as the ephemeral PSK (excluding the trailing null `\0` character). Its * length must be between `kMinEphemeralKeyLength` and `kMaxEphemeralKeyLength`, inclusive. @@ -209,7 +210,8 @@ class BorderAgent : public InstanceLocator, private NonCopyable * * If a commissioner is connected using the ephemeral key and is currently active, calling this method does not * change its state. In this case the `IsEphemeralKeyActive()` will continue to return `true` until the commissioner - * disconnects, or the ephemeral key timeout expires. + * disconnects, or the ephemeral key timeout expires. To terminate active commissioner sessions, use the + * `Disconnect()` function. */ void ClearEphemeralKey(void);