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