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 defines the OpenThread Operational Dataset API (for both FTD and MTD). 33 */ 34 35 #ifndef OPENTHREAD_DATASET_H_ 36 #define OPENTHREAD_DATASET_H_ 37 38 #include <openthread/instance.h> 39 #include <openthread/ip6.h> 40 #include <openthread/platform/radio.h> 41 42 #ifdef __cplusplus 43 extern "C" { 44 #endif 45 46 /** 47 * @addtogroup api-operational-dataset 48 * 49 * @{ 50 * 51 */ 52 53 #define OT_NETWORK_KEY_SIZE 16 ///< Size of the Thread Network Key (bytes) 54 55 /** 56 * @struct otNetworkKey 57 * 58 * This structure represents a Thread Network Key. 59 * 60 */ 61 OT_TOOL_PACKED_BEGIN 62 struct otNetworkKey 63 { 64 uint8_t m8[OT_NETWORK_KEY_SIZE]; ///< Byte values 65 } OT_TOOL_PACKED_END; 66 67 /** 68 * This structure represents a Thread Network Key. 69 * 70 */ 71 typedef struct otNetworkKey otNetworkKey; 72 73 #define OT_NETWORK_NAME_MAX_SIZE 16 ///< Maximum size of the Thread Network Name field (bytes) 74 75 /** 76 * This structure represents a Network Name. 77 * 78 * The `otNetworkName` is a null terminated C string (i.e., `m8` char array MUST end with null char `\0`). 79 * 80 */ 81 typedef struct otNetworkName 82 { 83 char m8[OT_NETWORK_NAME_MAX_SIZE + 1]; ///< Byte values. The `+ 1` is for null char. 84 } otNetworkName; 85 86 #define OT_EXT_PAN_ID_SIZE 8 ///< Size of a Thread PAN ID (bytes) 87 88 /** 89 * This structure represents an Extended PAN ID. 90 * 91 */ 92 OT_TOOL_PACKED_BEGIN 93 struct otExtendedPanId 94 { 95 uint8_t m8[OT_EXT_PAN_ID_SIZE]; ///< Byte values 96 } OT_TOOL_PACKED_END; 97 98 /** 99 * This structure represents an Extended PAN ID. 100 * 101 */ 102 typedef struct otExtendedPanId otExtendedPanId; 103 104 #define OT_MESH_LOCAL_PREFIX_SIZE OT_IP6_PREFIX_SIZE ///< Size of the Mesh Local Prefix (bytes) 105 106 /** 107 * This structure represents a Mesh Local Prefix. 108 * 109 */ 110 typedef otIp6NetworkPrefix otMeshLocalPrefix; 111 112 #define OT_PSKC_MAX_SIZE 16 ///< Maximum size of the PSKc (bytes) 113 114 /** 115 * This structure represents PSKc. 116 * 117 */ 118 OT_TOOL_PACKED_BEGIN 119 struct otPskc 120 { 121 uint8_t m8[OT_PSKC_MAX_SIZE]; ///< Byte values 122 } OT_TOOL_PACKED_END; 123 124 /** 125 * This structure represents a PSKc. 126 * 127 */ 128 typedef struct otPskc otPskc; 129 130 /** 131 * This structure represent Security Policy. 132 * 133 */ 134 typedef struct otSecurityPolicy 135 { 136 uint16_t mRotationTime; ///< The value for thrKeyRotation in units of hours. 137 138 bool mObtainNetworkKeyEnabled : 1; ///< Obtaining the Network Key for out-of-band commissioning is enabled 139 bool mNativeCommissioningEnabled : 1; ///< Native Commissioning using PSKc is allowed 140 bool mRoutersEnabled : 1; ///< Thread 1.0/1.1.x Routers are enabled 141 bool mExternalCommissioningEnabled : 1; ///< External Commissioner authentication is allowed 142 bool mBeaconsEnabled : 1; ///< Thread 1.0/1.1.x Beacons are enabled 143 bool mCommercialCommissioningEnabled : 1; ///< Commercial Commissioning is enabled 144 bool mAutonomousEnrollmentEnabled : 1; ///< Autonomous Enrollment is enabled 145 bool mNetworkKeyProvisioningEnabled : 1; ///< Network Key Provisioning is enabled 146 bool mTobleLinkEnabled : 1; ///< ToBLE link is enabled 147 bool mNonCcmRoutersEnabled : 1; ///< Non-CCM Routers enabled 148 uint8_t mVersionThresholdForRouting : 3; ///< Version-threshold for Routing 149 } otSecurityPolicy; 150 151 /** 152 * This type represents Channel Mask. 153 * 154 */ 155 typedef uint32_t otChannelMask; 156 157 #define OT_CHANNEL_1_MASK (1 << 1) ///< Channel 1 158 #define OT_CHANNEL_2_MASK (1 << 2) ///< Channel 2 159 #define OT_CHANNEL_3_MASK (1 << 3) ///< Channel 3 160 #define OT_CHANNEL_4_MASK (1 << 4) ///< Channel 4 161 #define OT_CHANNEL_5_MASK (1 << 5) ///< Channel 5 162 #define OT_CHANNEL_6_MASK (1 << 6) ///< Channel 6 163 #define OT_CHANNEL_7_MASK (1 << 7) ///< Channel 7 164 #define OT_CHANNEL_8_MASK (1 << 8) ///< Channel 8 165 #define OT_CHANNEL_9_MASK (1 << 9) ///< Channel 9 166 #define OT_CHANNEL_10_MASK (1 << 10) ///< Channel 10 167 #define OT_CHANNEL_11_MASK (1 << 11) ///< Channel 11 168 #define OT_CHANNEL_12_MASK (1 << 12) ///< Channel 12 169 #define OT_CHANNEL_13_MASK (1 << 13) ///< Channel 13 170 #define OT_CHANNEL_14_MASK (1 << 14) ///< Channel 14 171 #define OT_CHANNEL_15_MASK (1 << 15) ///< Channel 15 172 #define OT_CHANNEL_16_MASK (1 << 16) ///< Channel 16 173 #define OT_CHANNEL_17_MASK (1 << 17) ///< Channel 17 174 #define OT_CHANNEL_18_MASK (1 << 18) ///< Channel 18 175 #define OT_CHANNEL_19_MASK (1 << 19) ///< Channel 19 176 #define OT_CHANNEL_20_MASK (1 << 20) ///< Channel 20 177 #define OT_CHANNEL_21_MASK (1 << 21) ///< Channel 21 178 #define OT_CHANNEL_22_MASK (1 << 22) ///< Channel 22 179 #define OT_CHANNEL_23_MASK (1 << 23) ///< Channel 23 180 #define OT_CHANNEL_24_MASK (1 << 24) ///< Channel 24 181 #define OT_CHANNEL_25_MASK (1 << 25) ///< Channel 25 182 #define OT_CHANNEL_26_MASK (1 << 26) ///< Channel 26 183 184 /** 185 * This structure represents presence of different components in Active or Pending Operational Dataset. 186 * 187 */ 188 typedef struct otOperationalDatasetComponents 189 { 190 bool mIsActiveTimestampPresent : 1; ///< TRUE if Active Timestamp is present, FALSE otherwise. 191 bool mIsPendingTimestampPresent : 1; ///< TRUE if Pending Timestamp is present, FALSE otherwise. 192 bool mIsNetworkKeyPresent : 1; ///< TRUE if Network Key is present, FALSE otherwise. 193 bool mIsNetworkNamePresent : 1; ///< TRUE if Network Name is present, FALSE otherwise. 194 bool mIsExtendedPanIdPresent : 1; ///< TRUE if Extended PAN ID is present, FALSE otherwise. 195 bool mIsMeshLocalPrefixPresent : 1; ///< TRUE if Mesh Local Prefix is present, FALSE otherwise. 196 bool mIsDelayPresent : 1; ///< TRUE if Delay Timer is present, FALSE otherwise. 197 bool mIsPanIdPresent : 1; ///< TRUE if PAN ID is present, FALSE otherwise. 198 bool mIsChannelPresent : 1; ///< TRUE if Channel is present, FALSE otherwise. 199 bool mIsPskcPresent : 1; ///< TRUE if PSKc is present, FALSE otherwise. 200 bool mIsSecurityPolicyPresent : 1; ///< TRUE if Security Policy is present, FALSE otherwise. 201 bool mIsChannelMaskPresent : 1; ///< TRUE if Channel Mask is present, FALSE otherwise. 202 } otOperationalDatasetComponents; 203 204 /** 205 * This structure represents an Active or Pending Operational Dataset. 206 * 207 * Components in Dataset are optional. `mComponets` structure specifies which components are present in the Dataset. 208 * 209 */ 210 typedef struct otOperationalDataset 211 { 212 uint64_t mActiveTimestamp; ///< Active Timestamp 213 uint64_t mPendingTimestamp; ///< Pending Timestamp 214 otNetworkKey mNetworkKey; ///< Network Key 215 otNetworkName mNetworkName; ///< Network Name 216 otExtendedPanId mExtendedPanId; ///< Extended PAN ID 217 otMeshLocalPrefix mMeshLocalPrefix; ///< Mesh Local Prefix 218 uint32_t mDelay; ///< Delay Timer 219 otPanId mPanId; ///< PAN ID 220 uint16_t mChannel; ///< Channel 221 otPskc mPskc; ///< PSKc 222 otSecurityPolicy mSecurityPolicy; ///< Security Policy 223 otChannelMask mChannelMask; ///< Channel Mask 224 otOperationalDatasetComponents mComponents; ///< Specifies which components are set in the Dataset. 225 } otOperationalDataset; 226 227 /** 228 * Maximum length of Operational Dataset in bytes. 229 * 230 */ 231 #define OT_OPERATIONAL_DATASET_MAX_LENGTH 254 232 233 /** 234 * This structure represents an Active or Pending Operational Dataset. 235 * 236 * The Operational Dataset is TLV encoded as specified by Thread. 237 * 238 */ 239 typedef struct otOperationalDatasetTlvs 240 { 241 uint8_t mTlvs[OT_OPERATIONAL_DATASET_MAX_LENGTH]; ///< Operational Dataset TLVs. 242 uint8_t mLength; ///< Size of Operational Dataset in bytes. 243 } otOperationalDatasetTlvs; 244 245 /** 246 * This enumeration represents meshcop TLV types. 247 * 248 */ 249 typedef enum otMeshcopTlvType 250 { 251 OT_MESHCOP_TLV_CHANNEL = 0, ///< meshcop Channel TLV 252 OT_MESHCOP_TLV_PANID = 1, ///< meshcop Pan Id TLV 253 OT_MESHCOP_TLV_EXTPANID = 2, ///< meshcop Extended Pan Id TLV 254 OT_MESHCOP_TLV_NETWORKNAME = 3, ///< meshcop Network Name TLV 255 OT_MESHCOP_TLV_PSKC = 4, ///< meshcop PSKc TLV 256 OT_MESHCOP_TLV_NETWORKKEY = 5, ///< meshcop Network Key TLV 257 OT_MESHCOP_TLV_NETWORK_KEY_SEQUENCE = 6, ///< meshcop Network Key Sequence TLV 258 OT_MESHCOP_TLV_MESHLOCALPREFIX = 7, ///< meshcop Mesh Local Prefix TLV 259 OT_MESHCOP_TLV_STEERING_DATA = 8, ///< meshcop Steering Data TLV 260 OT_MESHCOP_TLV_BORDER_AGENT_RLOC = 9, ///< meshcop Border Agent Locator TLV 261 OT_MESHCOP_TLV_COMMISSIONER_ID = 10, ///< meshcop Commissioner ID TLV 262 OT_MESHCOP_TLV_COMM_SESSION_ID = 11, ///< meshcop Commissioner Session ID TLV 263 OT_MESHCOP_TLV_SECURITYPOLICY = 12, ///< meshcop Security Policy TLV 264 OT_MESHCOP_TLV_GET = 13, ///< meshcop Get TLV 265 OT_MESHCOP_TLV_ACTIVETIMESTAMP = 14, ///< meshcop Active Timestamp TLV 266 OT_MESHCOP_TLV_COMMISSIONER_UDP_PORT = 15, ///< meshcop Commissioner UDP Port TLV 267 OT_MESHCOP_TLV_STATE = 16, ///< meshcop State TLV 268 OT_MESHCOP_TLV_JOINER_DTLS = 17, ///< meshcop Joiner DTLS Encapsulation TLV 269 OT_MESHCOP_TLV_JOINER_UDP_PORT = 18, ///< meshcop Joiner UDP Port TLV 270 OT_MESHCOP_TLV_JOINER_IID = 19, ///< meshcop Joiner IID TLV 271 OT_MESHCOP_TLV_JOINER_RLOC = 20, ///< meshcop Joiner Router Locator TLV 272 OT_MESHCOP_TLV_JOINER_ROUTER_KEK = 21, ///< meshcop Joiner Router KEK TLV 273 OT_MESHCOP_TLV_PROVISIONING_URL = 32, ///< meshcop Provisioning URL TLV 274 OT_MESHCOP_TLV_VENDOR_NAME_TLV = 33, ///< meshcop Vendor Name TLV 275 OT_MESHCOP_TLV_VENDOR_MODEL_TLV = 34, ///< meshcop Vendor Model TLV 276 OT_MESHCOP_TLV_VENDOR_SW_VERSION_TLV = 35, ///< meshcop Vendor SW Version TLV 277 OT_MESHCOP_TLV_VENDOR_DATA_TLV = 36, ///< meshcop Vendor Data TLV 278 OT_MESHCOP_TLV_VENDOR_STACK_VERSION_TLV = 37, ///< meshcop Vendor Stack Version TLV 279 OT_MESHCOP_TLV_UDP_ENCAPSULATION_TLV = 48, ///< meshcop UDP encapsulation TLV 280 OT_MESHCOP_TLV_IPV6_ADDRESS_TLV = 49, ///< meshcop IPv6 address TLV 281 OT_MESHCOP_TLV_PENDINGTIMESTAMP = 51, ///< meshcop Pending Timestamp TLV 282 OT_MESHCOP_TLV_DELAYTIMER = 52, ///< meshcop Delay Timer TLV 283 OT_MESHCOP_TLV_CHANNELMASK = 53, ///< meshcop Channel Mask TLV 284 OT_MESHCOP_TLV_COUNT = 54, ///< meshcop Count TLV 285 OT_MESHCOP_TLV_PERIOD = 55, ///< meshcop Period TLV 286 OT_MESHCOP_TLV_SCAN_DURATION = 56, ///< meshcop Scan Duration TLV 287 OT_MESHCOP_TLV_ENERGY_LIST = 57, ///< meshcop Energy List TLV 288 OT_MESHCOP_TLV_DISCOVERYREQUEST = 128, ///< meshcop Discovery Request TLV 289 OT_MESHCOP_TLV_DISCOVERYRESPONSE = 129, ///< meshcop Discovery Response TLV 290 OT_MESHCOP_TLV_JOINERADVERTISEMENT = 241, ///< meshcop Joiner Advertisement TLV 291 } otMeshcopTlvType; 292 293 /** 294 * This function pointer is called when a response to a MGMT_SET request is received or times out. 295 * 296 * @param[in] aResult A result of the operation. 297 * @param[in] aContext A pointer to application-specific context. 298 * 299 * @retval OT_ERROR_NONE The request was accepted by the leader. 300 * @retval OT_ERROR_REJECTED The request was rejected by the leader. 301 * @retval OT_ERROR_PARSE An error occurred during parsing the response. 302 * @retval OT_ERROR_ABORT The request was reset by peer. 303 * @retval OT_ERROR_RESPONSE_TIMEOUT No response or acknowledgment received during timeout period. 304 * 305 */ 306 typedef void (*otDatasetMgmtSetCallback)(otError aResult, void *aContext); 307 308 /** 309 * This function indicates whether a valid network is present in the Active Operational Dataset or not. 310 * 311 * @param[in] aInstance A pointer to an OpenThread instance. 312 * 313 * @returns TRUE if a valid network is present in the Active Operational Dataset, FALSE otherwise. 314 * 315 */ 316 bool otDatasetIsCommissioned(otInstance *aInstance); 317 318 /** 319 * This function gets the Active Operational Dataset. 320 * 321 * @param[in] aInstance A pointer to an OpenThread instance. 322 * @param[out] aDataset A pointer to where the Active Operational Dataset will be placed. 323 * 324 * @retval OT_ERROR_NONE Successfully retrieved the Active Operational Dataset. 325 * @retval OT_ERROR_NOT_FOUND No corresponding value in the setting store. 326 * 327 */ 328 otError otDatasetGetActive(otInstance *aInstance, otOperationalDataset *aDataset); 329 330 /** 331 * This function gets the Active Operational Dataset. 332 * 333 * @param[in] aInstance A pointer to an OpenThread instance. 334 * @param[out] aDataset A pointer to where the Active Operational Dataset will be placed. 335 * 336 * @retval OT_ERROR_NONE Successfully retrieved the Active Operational Dataset. 337 * @retval OT_ERROR_NOT_FOUND No corresponding value in the setting store. 338 * 339 */ 340 otError otDatasetGetActiveTlvs(otInstance *aInstance, otOperationalDatasetTlvs *aDataset); 341 342 /** 343 * This function sets the Active Operational Dataset. 344 * 345 * If the dataset does not include an Active Timestamp, the dataset is only partially complete. 346 * 347 * If Thread is enabled on a device that has a partially complete Active Dataset, the device will attempt to attach to 348 * an existing Thread network using any existing information in the dataset. Only the Thread Network Key is needed to 349 * attach to a network. 350 * 351 * If channel is not included in the dataset, the device will send MLE Announce messages across different channels to 352 * find neighbors on other channels. 353 * 354 * If the device successfully attaches to a Thread network, the device will then retrieve the full Active Dataset from 355 * its Parent. Note that a router-capable device will not transition to the Router or Leader roles until it has a 356 * complete Active Dataset. 357 * 358 * @param[in] aInstance A pointer to an OpenThread instance. 359 * @param[in] aDataset A pointer to the Active Operational Dataset. 360 * 361 * @retval OT_ERROR_NONE Successfully set the Active Operational Dataset. 362 * @retval OT_ERROR_NO_BUFS Insufficient buffer space to set the Active Operational Dataset. 363 * @retval OT_ERROR_NOT_IMPLEMENTED The platform does not implement settings functionality. 364 * 365 */ 366 otError otDatasetSetActive(otInstance *aInstance, const otOperationalDataset *aDataset); 367 368 /** 369 * This function sets the Active Operational Dataset. 370 * 371 * If the dataset does not include an Active Timestamp, the dataset is only partially complete. 372 * 373 * If Thread is enabled on a device that has a partially complete Active Dataset, the device will attempt to attach to 374 * an existing Thread network using any existing information in the dataset. Only the Thread Network Key is needed to 375 * attach to a network. 376 * 377 * If channel is not included in the dataset, the device will send MLE Announce messages across different channels to 378 * find neighbors on other channels. 379 * 380 * If the device successfully attaches to a Thread network, the device will then retrieve the full Active Dataset from 381 * its Parent. Note that a router-capable device will not transition to the Router or Leader roles until it has a 382 * complete Active Dataset. 383 * 384 * @param[in] aInstance A pointer to an OpenThread instance. 385 * @param[in] aDataset A pointer to the Active Operational Dataset. 386 * 387 * @retval OT_ERROR_NONE Successfully set the Active Operational Dataset. 388 * @retval OT_ERROR_NO_BUFS Insufficient buffer space to set the Active Operational Dataset. 389 * @retval OT_ERROR_NOT_IMPLEMENTED The platform does not implement settings functionality. 390 * 391 */ 392 otError otDatasetSetActiveTlvs(otInstance *aInstance, const otOperationalDatasetTlvs *aDataset); 393 394 /** 395 * This function gets the Pending Operational Dataset. 396 * 397 * @param[in] aInstance A pointer to an OpenThread instance. 398 * @param[out] aDataset A pointer to where the Pending Operational Dataset will be placed. 399 * 400 * @retval OT_ERROR_NONE Successfully retrieved the Pending Operational Dataset. 401 * @retval OT_ERROR_NOT_FOUND No corresponding value in the setting store. 402 * 403 */ 404 otError otDatasetGetPending(otInstance *aInstance, otOperationalDataset *aDataset); 405 406 /** 407 * This function gets the Pending Operational Dataset. 408 * 409 * @param[in] aInstance A pointer to an OpenThread instance. 410 * @param[out] aDataset A pointer to where the Pending Operational Dataset will be placed. 411 * 412 * @retval OT_ERROR_NONE Successfully retrieved the Pending Operational Dataset. 413 * @retval OT_ERROR_NOT_FOUND No corresponding value in the setting store. 414 * 415 */ 416 otError otDatasetGetPendingTlvs(otInstance *aInstance, otOperationalDatasetTlvs *aDataset); 417 418 /** 419 * This function sets the Pending Operational Dataset. 420 * 421 * @param[in] aInstance A pointer to an OpenThread instance. 422 * @param[in] aDataset A pointer to the Pending Operational Dataset. 423 * 424 * @retval OT_ERROR_NONE Successfully set the Pending Operational Dataset. 425 * @retval OT_ERROR_NO_BUFS Insufficient buffer space to set the Pending Operational Dataset. 426 * @retval OT_ERROR_NOT_IMPLEMENTED The platform does not implement settings functionality. 427 * 428 */ 429 otError otDatasetSetPending(otInstance *aInstance, const otOperationalDataset *aDataset); 430 431 /** 432 * This function sets the Pending Operational Dataset. 433 * 434 * @param[in] aInstance A pointer to an OpenThread instance. 435 * @param[in] aDataset A pointer to the Pending Operational Dataset. 436 * 437 * @retval OT_ERROR_NONE Successfully set the Pending Operational Dataset. 438 * @retval OT_ERROR_NO_BUFS Insufficient buffer space to set the Pending Operational Dataset. 439 * @retval OT_ERROR_NOT_IMPLEMENTED The platform does not implement settings functionality. 440 * 441 */ 442 otError otDatasetSetPendingTlvs(otInstance *aInstance, const otOperationalDatasetTlvs *aDataset); 443 444 /** 445 * This function sends MGMT_ACTIVE_GET. 446 * 447 * @param[in] aInstance A pointer to an OpenThread instance. 448 * @param[in] aDatasetComponents A pointer to a Dataset Components structure specifying which components to request. 449 * @param[in] aTlvTypes A pointer to array containing additional raw TLV types to be requested. 450 * @param[in] aLength The length of @p aTlvTypes. 451 * @param[in] aAddress A pointer to the IPv6 destination, if it is NULL, will use Leader ALOC as default. 452 * 453 * @retval OT_ERROR_NONE Successfully send the meshcop dataset command. 454 * @retval OT_ERROR_NO_BUFS Insufficient buffer space to send. 455 * 456 */ 457 otError otDatasetSendMgmtActiveGet(otInstance * aInstance, 458 const otOperationalDatasetComponents *aDatasetComponents, 459 const uint8_t * aTlvTypes, 460 uint8_t aLength, 461 const otIp6Address * aAddress); 462 463 /** 464 * This function sends MGMT_ACTIVE_SET. 465 * 466 * @param[in] aInstance A pointer to an OpenThread instance. 467 * @param[in] aDataset A pointer to operational dataset. 468 * @param[in] aTlvs A pointer to TLVs. 469 * @param[in] aLength The length of TLVs. 470 * @param[in] aCallback A pointer to a function that is called on response reception or timeout. 471 * @param[in] aContext A pointer to application-specific context for @p aCallback. 472 * 473 * @retval OT_ERROR_NONE Successfully send the meshcop dataset command. 474 * @retval OT_ERROR_NO_BUFS Insufficient buffer space to send. 475 * @retval OT_ERROR_BUSY A previous request is ongoing. 476 * 477 */ 478 otError otDatasetSendMgmtActiveSet(otInstance * aInstance, 479 const otOperationalDataset *aDataset, 480 const uint8_t * aTlvs, 481 uint8_t aLength, 482 otDatasetMgmtSetCallback aCallback, 483 void * aContext); 484 485 /** 486 * This function sends MGMT_PENDING_GET. 487 * 488 * @param[in] aInstance A pointer to an OpenThread instance. 489 * @param[in] aDatasetComponents A pointer to a Dataset Components structure specifying which components to request. 490 * @param[in] aTlvTypes A pointer to array containing additional raw TLV types to be requested. 491 * @param[in] aLength The length of @p aTlvTypes. 492 * @param[in] aAddress A pointer to the IPv6 destination, if it is NULL, will use Leader ALOC as default. 493 * 494 * @retval OT_ERROR_NONE Successfully send the meshcop dataset command. 495 * @retval OT_ERROR_NO_BUFS Insufficient buffer space to send. 496 * 497 */ 498 otError otDatasetSendMgmtPendingGet(otInstance * aInstance, 499 const otOperationalDatasetComponents *aDatasetComponents, 500 const uint8_t * aTlvTypes, 501 uint8_t aLength, 502 const otIp6Address * aAddress); 503 504 /** 505 * This function sends MGMT_PENDING_SET. 506 * 507 * @param[in] aInstance A pointer to an OpenThread instance. 508 * @param[in] aDataset A pointer to operational dataset. 509 * @param[in] aTlvs A pointer to TLVs. 510 * @param[in] aLength The length of TLVs. 511 * @param[in] aCallback A pointer to a function that is called on response reception or timeout. 512 * @param[in] aContext A pointer to application-specific context for @p aCallback. 513 * 514 * @retval OT_ERROR_NONE Successfully send the meshcop dataset command. 515 * @retval OT_ERROR_NO_BUFS Insufficient buffer space to send. 516 * @retval OT_ERROR_BUSY A previous request is ongoing. 517 * 518 */ 519 otError otDatasetSendMgmtPendingSet(otInstance * aInstance, 520 const otOperationalDataset *aDataset, 521 const uint8_t * aTlvs, 522 uint8_t aLength, 523 otDatasetMgmtSetCallback aCallback, 524 void * aContext); 525 526 /** 527 * This function generates PSKc from a given pass-phrase, network name, and extended PAN ID. 528 * 529 * PSKc is used to establish the Commissioner Session. 530 * 531 * @param[in] aPassPhrase The commissioning pass-phrase. 532 * @param[in] aNetworkName The network name for PSKc computation. 533 * @param[in] aExtPanId The extended PAN ID for PSKc computation. 534 * @param[out] aPskc A pointer to variable to output the generated PSKc. 535 * 536 * @retval OT_ERROR_NONE Successfully generate PSKc. 537 * @retval OT_ERROR_INVALID_ARGS If any of the input arguments is invalid. 538 * 539 */ 540 otError otDatasetGeneratePskc(const char * aPassPhrase, 541 const otNetworkName * aNetworkName, 542 const otExtendedPanId *aExtPanId, 543 otPskc * aPskc); 544 545 /** 546 * This function sets an `otNetworkName` instance from a given null terminated C string. 547 * 548 * This function also validates that the given @p aNameString follows UTF-8 encoding and its length is not longer than 549 * `OT_NETWORK_NAME_MAX_SIZE`. 550 * 551 * @param[out] aNetworkName A pointer to the `otNetworkName` to set. 552 * @param[in] aNameString A name C string. 553 * 554 * @retval OT_ERROR_NONE Successfully set @p aNetworkName from @p aNameString. 555 * @retval OT_ERROR_INVALID_ARGS @p aNameStrng is invalid (too long or does not follow UTF-8 encoding). 556 * 557 */ 558 otError otNetworkNameFromString(otNetworkName *aNetworkName, const char *aNameString); 559 560 /** 561 * This function parses an Operational Dataset from a `otOperationalDatasetTlvs`. 562 * 563 * @param[in] aDatasetTlvs A pointer to dataset TLVs. 564 * @param[out] aDataset A pointer to where the dataset will be placed. 565 * 566 * @retval OT_ERROR_NONE Successfully set @p aDataset from @p aDatasetTlvs. 567 * @retval OT_ERROR_INVALID_ARGS @p aDatasetTlvs is invalid. 568 * 569 */ 570 otError otDatasetParseTlvs(const otOperationalDatasetTlvs *aDatasetTlvs, otOperationalDataset *aDataset); 571 572 /** 573 * @} 574 * 575 */ 576 577 #ifdef __cplusplus 578 } // extern "C" 579 #endif 580 581 #endif // OPENTHREAD_DATASET_H_ 582
