/src/openthread/include/openthread/commissioner.h

Source (jump to first uncovered line)
/*
 *  Copyright (c) 2016, The OpenThread Authors.
 *  All rights reserved.
 *
 *  Redistribution and use in source and binary forms, with or without
 *  modification, are permitted provided that the following conditions are met:
 *  1. Redistributions of source code must retain the above copyright
 *     notice, this list of conditions and the following disclaimer.
 *  2. Redistributions in binary form must reproduce the above copyright
 *     notice, this list of conditions and the following disclaimer in the
 *     documentation and/or other materials provided with the distribution.
 *  3. Neither the name of the copyright holder nor the
 *     names of its contributors may be used to endorse or promote products
 *     derived from this software without specific prior written permission.
 *
 *  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 *  AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 *  IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 *  ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
 *  LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
 *  CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
 *  SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
 *  INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
 *  CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
 *  ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 *  POSSIBILITY OF SUCH DAMAGE.
 */

/**
 * @file
 * @brief
 *   This file includes functions for the Thread Commissioner role.
 */

#ifndef OPENTHREAD_COMMISSIONER_H_
#define OPENTHREAD_COMMISSIONER_H_

#include <openthread/dataset.h>
#include <openthread/ip6.h>
#include <openthread/joiner.h>
#include <openthread/platform/radio.h>
#include <openthread/platform/toolchain.h>

#ifdef __cplusplus
extern "C" {
#endif

/**
 * @addtogroup api-commissioner
 *
 * @brief
 *   This module includes functions for the Thread Commissioner role.
 *
 * @{
 *
 */

/**
 * This enumeration defines the Commissioner State.
 *
 */
typedef enum otCommissionerState
{
    OT_COMMISSIONER_STATE_DISABLED = 0, ///< Commissioner role is disabled.
    OT_COMMISSIONER_STATE_PETITION = 1, ///< Currently petitioning to become a Commissioner.
    OT_COMMISSIONER_STATE_ACTIVE   = 2, ///< Commissioner role is active.
} otCommissionerState;

/**
 * This enumeration defines a Joiner Event on the Commissioner.
 *
 */
typedef enum otCommissionerJoinerEvent
{
    OT_COMMISSIONER_JOINER_START     = 0,
    OT_COMMISSIONER_JOINER_CONNECTED = 1,
    OT_COMMISSIONER_JOINER_FINALIZE  = 2,
    OT_COMMISSIONER_JOINER_END       = 3,
    OT_COMMISSIONER_JOINER_REMOVED   = 4,
} otCommissionerJoinerEvent;

#define OT_COMMISSIONING_PASSPHRASE_MIN_SIZE 6   ///< Minimum size of the Commissioning Passphrase
#define OT_COMMISSIONING_PASSPHRASE_MAX_SIZE 255 ///< Maximum size of the Commissioning Passphrase

#define OT_PROVISIONING_URL_MAX_SIZE 64 ///< Max size (number of chars) in Provisioning URL string (excludes null char).

#define OT_STEERING_DATA_MAX_LENGTH 16 ///< Max steering data length (bytes)

/**
 * This structure represents the steering data.
 *
 */
typedef struct otSteeringData
{
    uint8_t mLength;                         ///< Length of steering data (bytes)
    uint8_t m8[OT_STEERING_DATA_MAX_LENGTH]; ///< Byte values
} otSteeringData;

/**
 * This structure represents a Commissioning Dataset.
 *
 */
typedef struct otCommissioningDataset
{
    uint16_t       mLocator;       ///< Border Router RLOC16
    uint16_t       mSessionId;     ///< Commissioner Session Id
    otSteeringData mSteeringData;  ///< Steering Data
    uint16_t       mJoinerUdpPort; ///< Joiner UDP Port

    bool mIsLocatorSet : 1;       ///< TRUE if Border Router RLOC16 is set, FALSE otherwise.
    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.
} otCommissioningDataset;

#define OT_JOINER_MAX_PSKD_LENGTH 32 ///< Maximum string length of a Joiner PSKd (does not include null char).

/**
 * This structure represents a Joiner PSKd.
 *
 */
typedef struct otJoinerPskd
{
    char m8[OT_JOINER_MAX_PSKD_LENGTH + 1]; ///< Char string array (must be null terminated - +1 is for null char).
} otJoinerPskd;

/**
 * This enumeration defines a Joiner Info Type.
 *
 */
typedef enum otJoinerInfoType
{
    OT_JOINER_INFO_TYPE_ANY       = 0, ///< Accept any Joiner (no EUI64 or Discerner is specified).
    OT_JOINER_INFO_TYPE_EUI64     = 1, ///< Joiner EUI-64 is specified (`mSharedId.mEui64` in `otJoinerInfo`).
    OT_JOINER_INFO_TYPE_DISCERNER = 2, ///< Joiner Discerner is specified (`mSharedId.mDiscerner` in `otJoinerInfo`).
} otJoinerInfoType;

/**
 * This structure represents a Joiner Info.
 *
 */
typedef struct otJoinerInfo
{
    otJoinerInfoType mType; ///< Joiner type.
    union
    {
        otExtAddress      mEui64;     ///< Joiner EUI64 (when `mType` is `OT_JOINER_INFO_TYPE_EUI64`)
        otJoinerDiscerner mDiscerner; ///< Joiner Discerner (when `mType` is `OT_JOINER_INFO_TYPE_DISCERNER`)
    } mSharedId;                      ///< Shared fields
    otJoinerPskd mPskd;               ///< Joiner PSKd
    uint32_t     mExpirationTime;     ///< Joiner expiration time in msec
} otJoinerInfo;

/**
 * This function pointer is called whenever the commissioner state changes.
 *
 * @param[in]  aState    The Commissioner state.
 * @param[in]  aContext  A pointer to application-specific context.
 *
 */
typedef void (*otCommissionerStateCallback)(otCommissionerState aState, void *aContext);

/**
 * This function pointer is called whenever the joiner state changes.
 *
 * @param[in]  aEvent       The joiner event type.
 * @param[in]  aJoinerInfo  A pointer to the Joiner Info.
 * @param[in]  aJoinerId    A pointer to the Joiner ID (if not known, it will be NULL).
 * @param[in]  aContext     A pointer to application-specific context.
 *
 */
typedef void (*otCommissionerJoinerCallback)(otCommissionerJoinerEvent aEvent,
                                             const otJoinerInfo       *aJoinerInfo,
                                             const otExtAddress       *aJoinerId,
                                             void                     *aContext);

/**
 * This function enables the Thread Commissioner role.
 *
 * @param[in]  aInstance         A pointer to an OpenThread instance.
 * @param[in]  aStateCallback    A pointer to a function that is called when the commissioner state changes.
 * @param[in]  aJoinerCallback   A pointer to a function that is called with a joiner event occurs.
 * @param[in]  aCallbackContext  A pointer to application-specific context.
 *
 * @retval OT_ERROR_NONE           Successfully started the Commissioner service.
 * @retval OT_ERROR_ALREADY        Commissioner is already started.
 * @retval OT_ERROR_INVALID_STATE  Device is not currently attached to a network.
 *
 */
otError otCommissionerStart(otInstance                  *aInstance,
                            otCommissionerStateCallback  aStateCallback,
                            otCommissionerJoinerCallback aJoinerCallback,
                            void                        *aCallbackContext);

/**
 * This function disables the Thread Commissioner role.
 *
 * @param[in]  aInstance         A pointer to an OpenThread instance.
 *
 * @retval OT_ERROR_NONE     Successfully stopped the Commissioner service.
 * @retval OT_ERROR_ALREADY  Commissioner is already stopped.
 *
 */
otError otCommissionerStop(otInstance *aInstance);

/**
 * This function returns the Commissioner Id.
 *
 * @param[in]  aInstance         A pointer to an OpenThread instance.
 *
 * @returns The Commissioner Id.
 *
 */
const char *otCommissionerGetId(otInstance *aInstance);

/**
 * This function sets the Commissioner Id.
 *
 * @param[in]  aInstance     A pointer to an OpenThread instance.
 * @param[in]  aId           A pointer to a string character array. Must be null terminated.
 *
 * @retval OT_ERROR_NONE            Successfully set the Commissioner Id.
 * @retval OT_ERROR_INVALID_ARGS    Given name is too long.
 * @retval OT_ERROR_INVALID_STATE   The commissioner is active and id cannot be changed.
 *
 */
otError otCommissionerSetId(otInstance *aInstance, const char *aId);

/**
 * This function adds a Joiner entry.
 *
 * @param[in]  aInstance          A pointer to an OpenThread instance.
 * @param[in]  aEui64             A pointer to the Joiner's IEEE EUI-64 or NULL for any Joiner.
 * @param[in]  aPskd              A pointer to the PSKd.
 * @param[in]  aTimeout           A time after which a Joiner is automatically removed, in seconds.
 *
 * @retval OT_ERROR_NONE          Successfully added the Joiner.
 * @retval OT_ERROR_NO_BUFS       No buffers available to add the Joiner.
 * @retval OT_ERROR_INVALID_ARGS  @p aEui64 or @p aPskd is invalid.
 * @retval OT_ERROR_INVALID_STATE The commissioner is not active.
 *
 * @note Only use this after successfully starting the Commissioner role with otCommissionerStart().
 *
 */
otError otCommissionerAddJoiner(otInstance         *aInstance,
                                const otExtAddress *aEui64,
                                const char         *aPskd,
                                uint32_t            aTimeout);

/**
 * This function adds a Joiner entry with a given Joiner Discerner value.
 *
 * @param[in]  aInstance          A pointer to an OpenThread instance.
 * @param[in]  aDiscerner         A pointer to the Joiner Discerner.
 * @param[in]  aPskd              A pointer to the PSKd.
 * @param[in]  aTimeout           A time after which a Joiner is automatically removed, in seconds.
 *
 * @retval OT_ERROR_NONE          Successfully added the Joiner.
 * @retval OT_ERROR_NO_BUFS       No buffers available to add the Joiner.
 * @retval OT_ERROR_INVALID_ARGS  @p aDiscerner or @p aPskd is invalid.
 * @retval OT_ERROR_INVALID_STATE The commissioner is not active.
 *
 * @note Only use this after successfully starting the Commissioner role with otCommissionerStart().
 *
 */
otError otCommissionerAddJoinerWithDiscerner(otInstance              *aInstance,
                                             const otJoinerDiscerner *aDiscerner,
                                             const char              *aPskd,
                                             uint32_t                 aTimeout);

/**
 * This method get joiner info at aIterator position.
 *
 * @param[in]      aInstance   A pointer to instance.
 * @param[in,out]  aIterator   A pointer to the Joiner Info iterator context.
 * @param[out]     aJoiner     A reference to Joiner info.
 *
 * @retval OT_ERROR_NONE       Successfully get the Joiner info.
 * @retval OT_ERROR_NOT_FOUND  Not found next Joiner.
 *
 */
otError otCommissionerGetNextJoinerInfo(otInstance *aInstance, uint16_t *aIterator, otJoinerInfo *aJoiner);

/**
 * This function removes a Joiner entry.
 *
 * @param[in]  aInstance          A pointer to an OpenThread instance.
 * @param[in]  aEui64             A pointer to the Joiner's IEEE EUI-64 or NULL for any Joiner.
 *
 * @retval OT_ERROR_NONE          Successfully removed the Joiner.
 * @retval OT_ERROR_NOT_FOUND     The Joiner specified by @p aEui64 was not found.
 * @retval OT_ERROR_INVALID_ARGS  @p aEui64 is invalid.
 * @retval OT_ERROR_INVALID_STATE The commissioner is not active.
 *
 * @note Only use this after successfully starting the Commissioner role with otCommissionerStart().
 *
 */
otError otCommissionerRemoveJoiner(otInstance *aInstance, const otExtAddress *aEui64);

/**
 * This function removes a Joiner entry.
 *
 * @param[in]  aInstance          A pointer to an OpenThread instance.
 * @param[in]  aDiscerner         A pointer to the Joiner Discerner.
 *
 * @retval OT_ERROR_NONE          Successfully removed the Joiner.
 * @retval OT_ERROR_NOT_FOUND     The Joiner specified by @p aEui64 was not found.
 * @retval OT_ERROR_INVALID_ARGS  @p aDiscerner is invalid.
 * @retval OT_ERROR_INVALID_STATE The commissioner is not active.
 *
 * @note Only use this after successfully starting the Commissioner role with otCommissionerStart().
 *
 */
otError otCommissionerRemoveJoinerWithDiscerner(otInstance *aInstance, const otJoinerDiscerner *aDiscerner);

/**
 * This function gets the Provisioning URL.
 *
 * @param[in]    aInstance       A pointer to an OpenThread instance.
 *
 * @returns A pointer to the URL string.
 *
 */
const char *otCommissionerGetProvisioningUrl(otInstance *aInstance);

/**
 * This function sets the Provisioning URL.
 *
 * @param[in]  aInstance             A pointer to an OpenThread instance.
 * @param[in]  aProvisioningUrl      A pointer to the Provisioning URL (may be NULL to set as empty string).
 *
 * @retval OT_ERROR_NONE          Successfully set the Provisioning URL.
 * @retval OT_ERROR_INVALID_ARGS  @p aProvisioningUrl is invalid (too long).
 *
 */
otError otCommissionerSetProvisioningUrl(otInstance *aInstance, const char *aProvisioningUrl);

/**
 * This function sends an Announce Begin message.
 *
 * @param[in]  aInstance             A pointer to an OpenThread instance.
 * @param[in]  aChannelMask          The channel mask value.
 * @param[in]  aCount                The number of Announcement messages per channel.
 * @param[in]  aPeriod               The time between two successive MLE Announce transmissions (in milliseconds).
 * @param[in]  aAddress              A pointer to the IPv6 destination.
 *
 * @retval OT_ERROR_NONE          Successfully enqueued the Announce Begin message.
 * @retval OT_ERROR_NO_BUFS       Insufficient buffers to generate an Announce Begin message.
 * @retval OT_ERROR_INVALID_STATE The commissioner is not active.
 *
 * @note Only use this after successfully starting the Commissioner role with otCommissionerStart().
 *
 */
otError otCommissionerAnnounceBegin(otInstance         *aInstance,
                                    uint32_t            aChannelMask,
                                    uint8_t             aCount,
                                    uint16_t            aPeriod,
                                    const otIp6Address *aAddress);

/**
 * This function pointer is called when the Commissioner receives an Energy Report.
 *
 * @param[in]  aChannelMask       The channel mask value.
 * @param[in]  aEnergyList        A pointer to the energy measurement list.
 * @param[in]  aEnergyListLength  Number of entries in @p aEnergyListLength.
 * @param[in]  aContext           A pointer to application-specific context.
 *
 */
typedef void (*otCommissionerEnergyReportCallback)(uint32_t       aChannelMask,
                                                   const uint8_t *aEnergyList,
                                                   uint8_t        aEnergyListLength,
                                                   void          *aContext);

/**
 * This function sends an Energy Scan Query message.
 *
 * @param[in]  aInstance             A pointer to an OpenThread instance.
 * @param[in]  aChannelMask          The channel mask value.
 * @param[in]  aCount                The number of energy measurements per channel.
 * @param[in]  aPeriod               The time between energy measurements (milliseconds).
 * @param[in]  aScanDuration         The scan duration for each energy measurement (milliseconds).
 * @param[in]  aAddress              A pointer to the IPv6 destination.
 * @param[in]  aCallback             A pointer to a function called on receiving an Energy Report message.
 * @param[in]  aContext              A pointer to application-specific context.
 *
 * @retval OT_ERROR_NONE          Successfully enqueued the Energy Scan Query message.
 * @retval OT_ERROR_NO_BUFS       Insufficient buffers to generate an Energy Scan Query message.
 * @retval OT_ERROR_INVALID_STATE The commissioner is not active.
 *
 * @note Only use this after successfully starting the Commissioner role with otCommissionerStart().
 *
 */
otError otCommissionerEnergyScan(otInstance                        *aInstance,
                                 uint32_t                           aChannelMask,
                                 uint8_t                            aCount,
                                 uint16_t                           aPeriod,
                                 uint16_t                           aScanDuration,
                                 const otIp6Address                *aAddress,
                                 otCommissionerEnergyReportCallback aCallback,
                                 void                              *aContext);

/**
 * This function pointer is called when the Commissioner receives a PAN ID Conflict message.
 *
 * @param[in]  aPanId             The PAN ID value.
 * @param[in]  aChannelMask       The channel mask value.
 * @param[in]  aContext           A pointer to application-specific context.
 *
 */
typedef void (*otCommissionerPanIdConflictCallback)(uint16_t aPanId, uint32_t aChannelMask, void *aContext);

/**
 * This function sends a PAN ID Query message.
 *
 * @param[in]  aInstance             A pointer to an OpenThread instance.
 * @param[in]  aPanId                The PAN ID to query.
 * @param[in]  aChannelMask          The channel mask value.
 * @param[in]  aAddress              A pointer to the IPv6 destination.
 * @param[in]  aCallback             A pointer to a function called on receiving a PAN ID Conflict message.
 * @param[in]  aContext              A pointer to application-specific context.
 *
 * @retval OT_ERROR_NONE          Successfully enqueued the PAN ID Query message.
 * @retval OT_ERROR_NO_BUFS       Insufficient buffers to generate a PAN ID Query message.
 * @retval OT_ERROR_INVALID_STATE The commissioner is not active.
 *
 * @note Only use this after successfully starting the Commissioner role with otCommissionerStart().
 *
 */
otError otCommissionerPanIdQuery(otInstance                         *aInstance,
                                 uint16_t                            aPanId,
                                 uint32_t                            aChannelMask,
                                 const otIp6Address                 *aAddress,
                                 otCommissionerPanIdConflictCallback aCallback,
                                 void                               *aContext);

/**
 * This function sends MGMT_COMMISSIONER_GET.
 *
 * @param[in]  aInstance  A pointer to an OpenThread instance.
 * @param[in]  aTlvs      A pointer to TLVs.
 * @param[in]  aLength    The length of TLVs.
 *
 * @retval OT_ERROR_NONE          Successfully send the meshcop dataset command.
 * @retval OT_ERROR_NO_BUFS       Insufficient buffer space to send.
 * @retval OT_ERROR_INVALID_STATE The commissioner is not active.
 *
 */
otError otCommissionerSendMgmtGet(otInstance *aInstance, const uint8_t *aTlvs, uint8_t aLength);

/**
 * This function sends MGMT_COMMISSIONER_SET.
 *
 * @param[in]  aInstance  A pointer to an OpenThread instance.
 * @param[in]  aDataset   A pointer to commissioning dataset.
 * @param[in]  aTlvs      A pointer to TLVs.
 * @param[in]  aLength    The length of TLVs.
 *
 * @retval OT_ERROR_NONE          Successfully send the meshcop dataset command.
 * @retval OT_ERROR_NO_BUFS       Insufficient buffer space to send.
 * @retval OT_ERROR_INVALID_STATE The commissioner is not active.
 *
 */
otError otCommissionerSendMgmtSet(otInstance                   *aInstance,
                                  const otCommissioningDataset *aDataset,
                                  const uint8_t                *aTlvs,
                                  uint8_t                       aLength);

/**
 * This function returns the Commissioner Session ID.
 *
 * @param[in]  aInstance  A pointer to an OpenThread instance.
 *
 * @returns The current commissioner session id.
 *
 */
uint16_t otCommissionerGetSessionId(otInstance *aInstance);

/**
 * This function returns the Commissioner State.
 *
 * @param[in]  aInstance  A pointer to an OpenThread instance.
 *
 * @retval OT_COMMISSIONER_STATE_DISABLED  Commissioner disabled.
 * @retval OT_COMMISSIONER_STATE_PETITION  Becoming the commissioner.
 * @retval OT_COMMISSIONER_STATE_ACTIVE    Commissioner enabled.
 *
 */
otCommissionerState otCommissionerGetState(otInstance *aInstance);

/**
 * @}
 *
 */

#ifdef __cplusplus
} // end of extern "C"
#endif

#endif // OPENTHREAD_COMMISSIONER_H_

Coverage Report

Created: 2023-12-14 14:18

Line	Count	Source (jump to first uncovered line)
1		/*
2		* Copyright (c) 2016, The OpenThread Authors.
3		* All rights reserved.
4		*
5		* Redistribution and use in source and binary forms, with or without
6		* modification, are permitted provided that the following conditions are met:
7		* 1. Redistributions of source code must retain the above copyright
8		* notice, this list of conditions and the following disclaimer.
9		* 2. Redistributions in binary form must reproduce the above copyright
10		* notice, this list of conditions and the following disclaimer in the
11		* documentation and/or other materials provided with the distribution.
12		* 3. Neither the name of the copyright holder nor the
13		* names of its contributors may be used to endorse or promote products
14		* derived from this software without specific prior written permission.
15		*
16		* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
17		* AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18		* IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19		* ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
20		* LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
21		* CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
22		* SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
23		* INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
24		* CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
25		* ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
26		* POSSIBILITY OF SUCH DAMAGE.
27		*/
28
29		/**
30		* @file
31		* @brief
32		* This file includes functions for the Thread Commissioner role.
33		*/
34
35		#ifndef OPENTHREAD_COMMISSIONER_H_
36		#define OPENTHREAD_COMMISSIONER_H_
37
38		#include <openthread/dataset.h>
39		#include <openthread/ip6.h>
40		#include <openthread/joiner.h>
41		#include <openthread/platform/radio.h>
42		#include <openthread/platform/toolchain.h>
43
44		#ifdef __cplusplus
45		extern "C" {
46		#endif
47
48		/**
49		* @addtogroup api-commissioner
50		*
51		* @brief
52		* This module includes functions for the Thread Commissioner role.
53		*
54		* @{
55		*
56		*/
57
58		/**
59		* This enumeration defines the Commissioner State.
60		*
61		*/
62		typedef enum otCommissionerState
63		{
64		OT_COMMISSIONER_STATE_DISABLED = 0, ///< Commissioner role is disabled.
65		OT_COMMISSIONER_STATE_PETITION = 1, ///< Currently petitioning to become a Commissioner.
66		OT_COMMISSIONER_STATE_ACTIVE = 2, ///< Commissioner role is active.
67		} otCommissionerState;
68
69		/**
70		* This enumeration defines a Joiner Event on the Commissioner.
71		*
72		*/
73		typedef enum otCommissionerJoinerEvent
74		{
75		OT_COMMISSIONER_JOINER_START = 0,
76		OT_COMMISSIONER_JOINER_CONNECTED = 1,
77		OT_COMMISSIONER_JOINER_FINALIZE = 2,
78		OT_COMMISSIONER_JOINER_END = 3,
79		OT_COMMISSIONER_JOINER_REMOVED = 4,
80		} otCommissionerJoinerEvent;
81
82		#define OT_COMMISSIONING_PASSPHRASE_MIN_SIZE 6 ///< Minimum size of the Commissioning Passphrase
83	0	#define OT_COMMISSIONING_PASSPHRASE_MAX_SIZE 255 ///< Maximum size of the Commissioning Passphrase
84
85		#define OT_PROVISIONING_URL_MAX_SIZE 64 ///< Max size (number of chars) in Provisioning URL string (excludes null char).
86
87		#define OT_STEERING_DATA_MAX_LENGTH 16 ///< Max steering data length (bytes)
88
89		/**
90		* This structure represents the steering data.
91		*
92		*/
93		typedef struct otSteeringData
94		{
95		uint8_t mLength; ///< Length of steering data (bytes)
96		uint8_t m8[OT_STEERING_DATA_MAX_LENGTH]; ///< Byte values
97		} otSteeringData;
98
99		/**
100		* This structure represents a Commissioning Dataset.
101		*
102		*/
103		typedef struct otCommissioningDataset
104		{
105		uint16_t mLocator; ///< Border Router RLOC16
106		uint16_t mSessionId; ///< Commissioner Session Id
107		otSteeringData mSteeringData; ///< Steering Data
108		uint16_t mJoinerUdpPort; ///< Joiner UDP Port
109
110		bool mIsLocatorSet : 1; ///< TRUE if Border Router RLOC16 is set, FALSE otherwise.
111		bool mIsSessionIdSet : 1; ///< TRUE if Commissioner Session Id is set, FALSE otherwise.
112		bool mIsSteeringDataSet : 1; ///< TRUE if Steering Data is set, FALSE otherwise.
113		bool mIsJoinerUdpPortSet : 1; ///< TRUE if Joiner UDP Port is set, FALSE otherwise.
114		} otCommissioningDataset;
115
116		#define OT_JOINER_MAX_PSKD_LENGTH 32 ///< Maximum string length of a Joiner PSKd (does not include null char).
117
118		/**
119		* This structure represents a Joiner PSKd.
120		*
121		*/
122		typedef struct otJoinerPskd
123		{
124		char m8[OT_JOINER_MAX_PSKD_LENGTH + 1]; ///< Char string array (must be null terminated - +1 is for null char).
125		} otJoinerPskd;
126
127		/**
128		* This enumeration defines a Joiner Info Type.
129		*
130		*/
131		typedef enum otJoinerInfoType
132		{
133		OT_JOINER_INFO_TYPE_ANY = 0, ///< Accept any Joiner (no EUI64 or Discerner is specified).
134		OT_JOINER_INFO_TYPE_EUI64 = 1, ///< Joiner EUI-64 is specified (`mSharedId.mEui64` in `otJoinerInfo`).
135		OT_JOINER_INFO_TYPE_DISCERNER = 2, ///< Joiner Discerner is specified (`mSharedId.mDiscerner` in `otJoinerInfo`).
136		} otJoinerInfoType;
137
138		/**
139		* This structure represents a Joiner Info.
140		*
141		*/
142		typedef struct otJoinerInfo
143		{
144		otJoinerInfoType mType; ///< Joiner type.
145		union
146		{
147		otExtAddress mEui64; ///< Joiner EUI64 (when `mType` is `OT_JOINER_INFO_TYPE_EUI64`)
148		otJoinerDiscerner mDiscerner; ///< Joiner Discerner (when `mType` is `OT_JOINER_INFO_TYPE_DISCERNER`)
149		} mSharedId; ///< Shared fields
150		otJoinerPskd mPskd; ///< Joiner PSKd
151		uint32_t mExpirationTime; ///< Joiner expiration time in msec
152		} otJoinerInfo;
153
154		/**
155		* This function pointer is called whenever the commissioner state changes.
156		*
157		* @param[in] aState The Commissioner state.
158		* @param[in] aContext A pointer to application-specific context.
159		*
160		*/
161		typedef void (otCommissionerStateCallback)(otCommissionerState aState, void aContext);
162
163		/**
164		* This function pointer is called whenever the joiner state changes.
165		*
166		* @param[in] aEvent The joiner event type.
167		* @param[in] aJoinerInfo A pointer to the Joiner Info.
168		* @param[in] aJoinerId A pointer to the Joiner ID (if not known, it will be NULL).
169		* @param[in] aContext A pointer to application-specific context.
170		*
171		*/
172		typedef void (*otCommissionerJoinerCallback)(otCommissionerJoinerEvent aEvent,
173		const otJoinerInfo *aJoinerInfo,
174		const otExtAddress *aJoinerId,
175		void *aContext);
176
177		/**
178		* This function enables the Thread Commissioner role.
179		*
180		* @param[in] aInstance A pointer to an OpenThread instance.
181		* @param[in] aStateCallback A pointer to a function that is called when the commissioner state changes.
182		* @param[in] aJoinerCallback A pointer to a function that is called with a joiner event occurs.
183		* @param[in] aCallbackContext A pointer to application-specific context.
184		*
185		* @retval OT_ERROR_NONE Successfully started the Commissioner service.
186		* @retval OT_ERROR_ALREADY Commissioner is already started.
187		* @retval OT_ERROR_INVALID_STATE Device is not currently attached to a network.
188		*
189		*/
190		otError otCommissionerStart(otInstance *aInstance,
191		otCommissionerStateCallback aStateCallback,
192		otCommissionerJoinerCallback aJoinerCallback,
193		void *aCallbackContext);
194
195		/**
196		* This function disables the Thread Commissioner role.
197		*
198		* @param[in] aInstance A pointer to an OpenThread instance.
199		*
200		* @retval OT_ERROR_NONE Successfully stopped the Commissioner service.
201		* @retval OT_ERROR_ALREADY Commissioner is already stopped.
202		*
203		*/
204		otError otCommissionerStop(otInstance *aInstance);
205
206		/**
207		* This function returns the Commissioner Id.
208		*
209		* @param[in] aInstance A pointer to an OpenThread instance.
210		*
211		* @returns The Commissioner Id.
212		*
213		*/
214		const char otCommissionerGetId(otInstance aInstance);
215
216		/**
217		* This function sets the Commissioner Id.
218		*
219		* @param[in] aInstance A pointer to an OpenThread instance.
220		* @param[in] aId A pointer to a string character array. Must be null terminated.
221		*
222		* @retval OT_ERROR_NONE Successfully set the Commissioner Id.
223		* @retval OT_ERROR_INVALID_ARGS Given name is too long.
224		* @retval OT_ERROR_INVALID_STATE The commissioner is active and id cannot be changed.
225		*
226		*/
227		otError otCommissionerSetId(otInstance aInstance, const char aId);
228
229		/**
230		* This function adds a Joiner entry.
231		*
232		* @param[in] aInstance A pointer to an OpenThread instance.
233		* @param[in] aEui64 A pointer to the Joiner's IEEE EUI-64 or NULL for any Joiner.
234		* @param[in] aPskd A pointer to the PSKd.
235		* @param[in] aTimeout A time after which a Joiner is automatically removed, in seconds.
236		*
237		* @retval OT_ERROR_NONE Successfully added the Joiner.
238		* @retval OT_ERROR_NO_BUFS No buffers available to add the Joiner.
239		* @retval OT_ERROR_INVALID_ARGS @p aEui64 or @p aPskd is invalid.
240		* @retval OT_ERROR_INVALID_STATE The commissioner is not active.
241		*
242		* @note Only use this after successfully starting the Commissioner role with otCommissionerStart().
243		*
244		*/
245		otError otCommissionerAddJoiner(otInstance *aInstance,
246		const otExtAddress *aEui64,
247		const char *aPskd,
248		uint32_t aTimeout);
249
250		/**
251		* This function adds a Joiner entry with a given Joiner Discerner value.
252		*
253		* @param[in] aInstance A pointer to an OpenThread instance.
254		* @param[in] aDiscerner A pointer to the Joiner Discerner.
255		* @param[in] aPskd A pointer to the PSKd.
256		* @param[in] aTimeout A time after which a Joiner is automatically removed, in seconds.
257		*
258		* @retval OT_ERROR_NONE Successfully added the Joiner.
259		* @retval OT_ERROR_NO_BUFS No buffers available to add the Joiner.
260		* @retval OT_ERROR_INVALID_ARGS @p aDiscerner or @p aPskd is invalid.
261		* @retval OT_ERROR_INVALID_STATE The commissioner is not active.
262		*
263		* @note Only use this after successfully starting the Commissioner role with otCommissionerStart().
264		*
265		*/
266		otError otCommissionerAddJoinerWithDiscerner(otInstance *aInstance,
267		const otJoinerDiscerner *aDiscerner,
268		const char *aPskd,
269		uint32_t aTimeout);
270
271		/**
272		* This method get joiner info at aIterator position.
273		*
274		* @param[in] aInstance A pointer to instance.
275		* @param[in,out] aIterator A pointer to the Joiner Info iterator context.
276		* @param[out] aJoiner A reference to Joiner info.
277		*
278		* @retval OT_ERROR_NONE Successfully get the Joiner info.
279		* @retval OT_ERROR_NOT_FOUND Not found next Joiner.
280		*
281		*/
282		otError otCommissionerGetNextJoinerInfo(otInstance aInstance, uint16_t aIterator, otJoinerInfo *aJoiner);
283
284		/**
285		* This function removes a Joiner entry.
286		*
287		* @param[in] aInstance A pointer to an OpenThread instance.
288		* @param[in] aEui64 A pointer to the Joiner's IEEE EUI-64 or NULL for any Joiner.
289		*
290		* @retval OT_ERROR_NONE Successfully removed the Joiner.
291		* @retval OT_ERROR_NOT_FOUND The Joiner specified by @p aEui64 was not found.
292		* @retval OT_ERROR_INVALID_ARGS @p aEui64 is invalid.
293		* @retval OT_ERROR_INVALID_STATE The commissioner is not active.
294		*
295		* @note Only use this after successfully starting the Commissioner role with otCommissionerStart().
296		*
297		*/
298		otError otCommissionerRemoveJoiner(otInstance aInstance, const otExtAddress aEui64);
299
300		/**
301		* This function removes a Joiner entry.
302		*
303		* @param[in] aInstance A pointer to an OpenThread instance.
304		* @param[in] aDiscerner A pointer to the Joiner Discerner.
305		*
306		* @retval OT_ERROR_NONE Successfully removed the Joiner.
307		* @retval OT_ERROR_NOT_FOUND The Joiner specified by @p aEui64 was not found.
308		* @retval OT_ERROR_INVALID_ARGS @p aDiscerner is invalid.
309		* @retval OT_ERROR_INVALID_STATE The commissioner is not active.
310		*
311		* @note Only use this after successfully starting the Commissioner role with otCommissionerStart().
312		*
313		*/
314		otError otCommissionerRemoveJoinerWithDiscerner(otInstance aInstance, const otJoinerDiscerner aDiscerner);
315
316		/**
317		* This function gets the Provisioning URL.
318		*
319		* @param[in] aInstance A pointer to an OpenThread instance.
320		*
321		* @returns A pointer to the URL string.
322		*
323		*/
324		const char otCommissionerGetProvisioningUrl(otInstance aInstance);
325
326		/**
327		* This function sets the Provisioning URL.
328		*
329		* @param[in] aInstance A pointer to an OpenThread instance.
330		* @param[in] aProvisioningUrl A pointer to the Provisioning URL (may be NULL to set as empty string).
331		*
332		* @retval OT_ERROR_NONE Successfully set the Provisioning URL.
333		* @retval OT_ERROR_INVALID_ARGS @p aProvisioningUrl is invalid (too long).
334		*
335		*/
336		otError otCommissionerSetProvisioningUrl(otInstance aInstance, const char aProvisioningUrl);
337
338		/**
339		* This function sends an Announce Begin message.
340		*
341		* @param[in] aInstance A pointer to an OpenThread instance.
342		* @param[in] aChannelMask The channel mask value.
343		* @param[in] aCount The number of Announcement messages per channel.
344		* @param[in] aPeriod The time between two successive MLE Announce transmissions (in milliseconds).
345		* @param[in] aAddress A pointer to the IPv6 destination.
346		*
347		* @retval OT_ERROR_NONE Successfully enqueued the Announce Begin message.
348		* @retval OT_ERROR_NO_BUFS Insufficient buffers to generate an Announce Begin message.
349		* @retval OT_ERROR_INVALID_STATE The commissioner is not active.
350		*
351		* @note Only use this after successfully starting the Commissioner role with otCommissionerStart().
352		*
353		*/
354		otError otCommissionerAnnounceBegin(otInstance *aInstance,
355		uint32_t aChannelMask,
356		uint8_t aCount,
357		uint16_t aPeriod,
358		const otIp6Address *aAddress);
359
360		/**
361		* This function pointer is called when the Commissioner receives an Energy Report.
362		*
363		* @param[in] aChannelMask The channel mask value.
364		* @param[in] aEnergyList A pointer to the energy measurement list.
365		* @param[in] aEnergyListLength Number of entries in @p aEnergyListLength.
366		* @param[in] aContext A pointer to application-specific context.
367		*
368		*/
369		typedef void (*otCommissionerEnergyReportCallback)(uint32_t aChannelMask,
370		const uint8_t *aEnergyList,
371		uint8_t aEnergyListLength,
372		void *aContext);
373
374		/**
375		* This function sends an Energy Scan Query message.
376		*
377		* @param[in] aInstance A pointer to an OpenThread instance.
378		* @param[in] aChannelMask The channel mask value.
379		* @param[in] aCount The number of energy measurements per channel.
380		* @param[in] aPeriod The time between energy measurements (milliseconds).
381		* @param[in] aScanDuration The scan duration for each energy measurement (milliseconds).
382		* @param[in] aAddress A pointer to the IPv6 destination.
383		* @param[in] aCallback A pointer to a function called on receiving an Energy Report message.
384		* @param[in] aContext A pointer to application-specific context.
385		*
386		* @retval OT_ERROR_NONE Successfully enqueued the Energy Scan Query message.
387		* @retval OT_ERROR_NO_BUFS Insufficient buffers to generate an Energy Scan Query message.
388		* @retval OT_ERROR_INVALID_STATE The commissioner is not active.
389		*
390		* @note Only use this after successfully starting the Commissioner role with otCommissionerStart().
391		*
392		*/
393		otError otCommissionerEnergyScan(otInstance *aInstance,
394		uint32_t aChannelMask,
395		uint8_t aCount,
396		uint16_t aPeriod,
397		uint16_t aScanDuration,
398		const otIp6Address *aAddress,
399		otCommissionerEnergyReportCallback aCallback,
400		void *aContext);
401
402		/**
403		* This function pointer is called when the Commissioner receives a PAN ID Conflict message.
404		*
405		* @param[in] aPanId The PAN ID value.
406		* @param[in] aChannelMask The channel mask value.
407		* @param[in] aContext A pointer to application-specific context.
408		*
409		*/
410		typedef void (otCommissionerPanIdConflictCallback)(uint16_t aPanId, uint32_t aChannelMask, void aContext);
411
412		/**
413		* This function sends a PAN ID Query message.
414		*
415		* @param[in] aInstance A pointer to an OpenThread instance.
416		* @param[in] aPanId The PAN ID to query.
417		* @param[in] aChannelMask The channel mask value.
418		* @param[in] aAddress A pointer to the IPv6 destination.
419		* @param[in] aCallback A pointer to a function called on receiving a PAN ID Conflict message.
420		* @param[in] aContext A pointer to application-specific context.
421		*
422		* @retval OT_ERROR_NONE Successfully enqueued the PAN ID Query message.
423		* @retval OT_ERROR_NO_BUFS Insufficient buffers to generate a PAN ID Query message.
424		* @retval OT_ERROR_INVALID_STATE The commissioner is not active.
425		*
426		* @note Only use this after successfully starting the Commissioner role with otCommissionerStart().
427		*
428		*/
429		otError otCommissionerPanIdQuery(otInstance *aInstance,
430		uint16_t aPanId,
431		uint32_t aChannelMask,
432		const otIp6Address *aAddress,
433		otCommissionerPanIdConflictCallback aCallback,
434		void *aContext);
435
436		/**
437		* This function sends MGMT_COMMISSIONER_GET.
438		*
439		* @param[in] aInstance A pointer to an OpenThread instance.
440		* @param[in] aTlvs A pointer to TLVs.
441		* @param[in] aLength The length of TLVs.
442		*
443		* @retval OT_ERROR_NONE Successfully send the meshcop dataset command.
444		* @retval OT_ERROR_NO_BUFS Insufficient buffer space to send.
445		* @retval OT_ERROR_INVALID_STATE The commissioner is not active.
446		*
447		*/
448		otError otCommissionerSendMgmtGet(otInstance aInstance, const uint8_t aTlvs, uint8_t aLength);
449
450		/**
451		* This function sends MGMT_COMMISSIONER_SET.
452		*
453		* @param[in] aInstance A pointer to an OpenThread instance.
454		* @param[in] aDataset A pointer to commissioning dataset.
455		* @param[in] aTlvs A pointer to TLVs.
456		* @param[in] aLength The length of TLVs.
457		*
458		* @retval OT_ERROR_NONE Successfully send the meshcop dataset command.
459		* @retval OT_ERROR_NO_BUFS Insufficient buffer space to send.
460		* @retval OT_ERROR_INVALID_STATE The commissioner is not active.
461		*
462		*/
463		otError otCommissionerSendMgmtSet(otInstance *aInstance,
464		const otCommissioningDataset *aDataset,
465		const uint8_t *aTlvs,
466		uint8_t aLength);
467
468		/**
469		* This function returns the Commissioner Session ID.
470		*
471		* @param[in] aInstance A pointer to an OpenThread instance.
472		*
473		* @returns The current commissioner session id.
474		*
475		*/
476		uint16_t otCommissionerGetSessionId(otInstance *aInstance);
477
478		/**
479		* This function returns the Commissioner State.
480		*
481		* @param[in] aInstance A pointer to an OpenThread instance.
482		*
483		* @retval OT_COMMISSIONER_STATE_DISABLED Commissioner disabled.
484		* @retval OT_COMMISSIONER_STATE_PETITION Becoming the commissioner.
485		* @retval OT_COMMISSIONER_STATE_ACTIVE Commissioner enabled.
486		*
487		*/
488		otCommissionerState otCommissionerGetState(otInstance *aInstance);
489
490		/**
491		* @}
492		*
493		*/
494
495		#ifdef __cplusplus
496		} // end of extern "C"
497		#endif
498
499		#endif // OPENTHREAD_COMMISSIONER_H_