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 Joiner role. 33 */ 34 35 #ifndef OPENTHREAD_JOINER_H_ 36 #define OPENTHREAD_JOINER_H_ 37 38 #include <openthread/platform/radio.h> 39 #include <openthread/platform/toolchain.h> 40 41 #ifdef __cplusplus 42 extern "C" { 43 #endif 44 45 /** 46 * @addtogroup api-joiner 47 * 48 * @brief 49 * This module includes functions for the Thread Joiner role. 50 * 51 * @note 52 * The functions in this module require `OPENTHREAD_CONFIG_JOINER_ENABLE=1`. 53 * 54 * @{ 55 */ 56 57 /** 58 * Defines the Joiner State. 59 */ 60 typedef enum otJoinerState 61 { 62 OT_JOINER_STATE_IDLE = 0, 63 OT_JOINER_STATE_DISCOVER = 1, 64 OT_JOINER_STATE_CONNECT = 2, 65 OT_JOINER_STATE_CONNECTED = 3, 66 OT_JOINER_STATE_ENTRUST = 4, 67 OT_JOINER_STATE_JOINED = 5, 68 } otJoinerState; 69 70 #define OT_JOINER_MAX_DISCERNER_LENGTH 64 ///< Maximum length of a Joiner Discerner in bits. 71 72 /** 73 * Represents a Joiner Discerner. 74 */ 75 typedef struct otJoinerDiscerner 76 { 77 uint64_t mValue; ///< Discerner value (the lowest `mLength` bits specify the discerner). 78 uint8_t mLength; ///< Length (number of bits) - must be non-zero and at most `OT_JOINER_MAX_DISCERNER_LENGTH`. 79 } otJoinerDiscerner; 80 81 /** 82 * Pointer is called to notify the completion of a join operation. 83 * 84 * @param[in] aError OT_ERROR_NONE if the join process succeeded. 85 * OT_ERROR_SECURITY if the join process failed due to security credentials. 86 * OT_ERROR_NOT_FOUND if no joinable network was discovered. 87 * OT_ERROR_RESPONSE_TIMEOUT if a response timed out. 88 * @param[in] aContext A pointer to application-specific context. 89 */ 90 typedef void (*otJoinerCallback)(otError aError, void *aContext); 91 92 /** 93 * Enables the Thread Joiner role. 94 * 95 * @param[in] aInstance A pointer to an OpenThread instance. 96 * @param[in] aPskd A pointer to the PSKd. 97 * @param[in] aProvisioningUrl A pointer to the Provisioning URL (may be NULL). 98 * @param[in] aVendorName A pointer to the Vendor Name (may be NULL). 99 * @param[in] aVendorModel A pointer to the Vendor Model (may be NULL). 100 * @param[in] aVendorSwVersion A pointer to the Vendor SW Version (may be NULL). 101 * @param[in] aVendorData A pointer to the Vendor Data (may be NULL). 102 * @param[in] aCallback A pointer to a function that is called when the join operation completes. 103 * @param[in] aContext A pointer to application-specific context. 104 * 105 * @retval OT_ERROR_NONE Successfully started the Joiner role. 106 * @retval OT_ERROR_BUSY The previous attempt is still on-going. 107 * @retval OT_ERROR_INVALID_ARGS @p aPskd or @p aProvisioningUrl is invalid. 108 * @retval OT_ERROR_INVALID_STATE The IPv6 stack is not enabled or Thread stack is fully enabled. 109 */ 110 otError otJoinerStart(otInstance *aInstance, 111 const char *aPskd, 112 const char *aProvisioningUrl, 113 const char *aVendorName, 114 const char *aVendorModel, 115 const char *aVendorSwVersion, 116 const char *aVendorData, 117 otJoinerCallback aCallback, 118 void *aContext); 119 120 /** 121 * Disables the Thread Joiner role. 122 * 123 * @param[in] aInstance A pointer to an OpenThread instance. 124 */ 125 void otJoinerStop(otInstance *aInstance); 126 127 /** 128 * Gets the Joiner State. 129 * 130 * @param[in] aInstance A pointer to an OpenThread instance. 131 * 132 * @returns The joiner state. 133 */ 134 otJoinerState otJoinerGetState(otInstance *aInstance); 135 136 /** 137 * Gets the Joiner ID. 138 * 139 * If a Joiner Discerner is not set, Joiner ID is the first 64 bits of the result of computing SHA-256 over 140 * factory-assigned IEEE EUI-64. Otherwise the Joiner ID is calculated from the Joiner Discerner value. 141 * 142 * The Joiner ID is also used as the device's IEEE 802.15.4 Extended Address during the commissioning process. 143 * 144 * @param[in] aInstance A pointer to the OpenThread instance. 145 * 146 * @returns A pointer to the Joiner ID. 147 */ 148 const otExtAddress *otJoinerGetId(otInstance *aInstance); 149 150 /** 151 * Sets the Joiner Discerner. 152 * 153 * The Joiner Discerner is used to calculate the Joiner ID during the Thread Commissioning process. For more 154 * information, refer to #otJoinerGetId. 155 * @note The Joiner Discerner takes the place of the Joiner EUI-64 during the joiner session of Thread Commissioning. 156 * 157 * @param[in] aInstance A pointer to the OpenThread instance. 158 * @param[in] aDiscerner A pointer to a Joiner Discerner. If NULL clears any previously set discerner. 159 * 160 * @retval OT_ERROR_NONE The Joiner Discerner updated successfully. 161 * @retval OT_ERROR_INVALID_ARGS @p aDiscerner is not valid (specified length is not within valid range). 162 * @retval OT_ERROR_INVALID_STATE There is an ongoing Joining process so Joiner Discerner could not be changed. 163 */ 164 otError otJoinerSetDiscerner(otInstance *aInstance, otJoinerDiscerner *aDiscerner); 165 166 /** 167 * Gets the Joiner Discerner. For more information, refer to #otJoinerSetDiscerner. 168 * 169 * @param[in] aInstance A pointer to the OpenThread instance. 170 * 171 * @returns A pointer to Joiner Discerner or NULL if none is set. 172 */ 173 const otJoinerDiscerner *otJoinerGetDiscerner(otInstance *aInstance); 174 175 /** 176 * Converts a given joiner state enumeration value to a human-readable string. 177 * 178 * @param[in] aState The joiner state. 179 * 180 * @returns A human-readable string representation of @p aState. 181 */ 182 const char *otJoinerStateToString(otJoinerState aState); 183 184 /** 185 * @} 186 */ 187 188 #ifdef __cplusplus 189 } // end of extern "C" 190 #endif 191 192 #endif // OPENTHREAD_JOINER_H_ 193
