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