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 * This structure 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 * This structure 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 * This structure 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 * This structure 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 * This structure 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 * This structure 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 * This structure 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 * This structure 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 * This structure 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 * This type 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 * This structure represents presence of different components in Active or Pending Operational Dataset. 200 * 201 */ 202 typedef struct otOperationalDatasetComponents 203 { 204 bool mIsActiveTimestampPresent : 1; ///< TRUE if Active Timestamp is present, FALSE otherwise. 205 bool mIsPendingTimestampPresent : 1; ///< TRUE if Pending Timestamp is present, FALSE otherwise. 206 bool mIsNetworkKeyPresent : 1; ///< TRUE if Network Key is present, FALSE otherwise. 207 bool mIsNetworkNamePresent : 1; ///< TRUE if Network Name is present, FALSE otherwise. 208 bool mIsExtendedPanIdPresent : 1; ///< TRUE if Extended PAN ID is present, FALSE otherwise. 209 bool mIsMeshLocalPrefixPresent : 1; ///< TRUE if Mesh Local Prefix is present, FALSE otherwise. 210 bool mIsDelayPresent : 1; ///< TRUE if Delay Timer is present, FALSE otherwise. 211 bool mIsPanIdPresent : 1; ///< TRUE if PAN ID is present, FALSE otherwise. 212 bool mIsChannelPresent : 1; ///< TRUE if Channel is present, FALSE otherwise. 213 bool mIsPskcPresent : 1; ///< TRUE if PSKc is present, FALSE otherwise. 214 bool mIsSecurityPolicyPresent : 1; ///< TRUE if Security Policy is present, FALSE otherwise. 215 bool mIsChannelMaskPresent : 1; ///< TRUE if Channel Mask is present, FALSE otherwise. 216 } otOperationalDatasetComponents; 217 218 /** 219 * This structure 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 * This structure 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 * This structure 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 * This enumeration 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 * This function 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 * This function 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 * This function 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 * @param[in] aInstance A pointer to an OpenThread instance. 384 * @param[in] aDataset A pointer to the Active Operational Dataset. 385 * 386 * @retval OT_ERROR_NONE Successfully set the Active Operational Dataset. 387 * @retval OT_ERROR_NO_BUFS Insufficient buffer space to set the Active Operational Dataset. 388 * @retval OT_ERROR_NOT_IMPLEMENTED The platform does not implement settings functionality. 389 * 390 */ 391 otError otDatasetSetActive(otInstance *aInstance, const otOperationalDataset *aDataset); 392 393 /** 394 * This function sets the Active Operational Dataset. 395 * 396 * If the dataset does not include an Active Timestamp, the dataset is only partially complete. 397 * 398 * If Thread is enabled on a device that has a partially complete Active Dataset, the device will attempt to attach to 399 * an existing Thread network using any existing information in the dataset. Only the Thread Network Key is needed to 400 * attach to a network. 401 * 402 * If channel is not included in the dataset, the device will send MLE Announce messages across different channels to 403 * find neighbors on other channels. 404 * 405 * If the device successfully attaches to a Thread network, the device will then retrieve the full Active Dataset from 406 * its Parent. Note that a router-capable device will not transition to the Router or Leader roles until it has a 407 * complete Active Dataset. 408 * 409 * @param[in] aInstance A pointer to an OpenThread instance. 410 * @param[in] aDataset A pointer to the Active Operational Dataset. 411 * 412 * @retval OT_ERROR_NONE Successfully set the Active Operational Dataset. 413 * @retval OT_ERROR_NO_BUFS Insufficient buffer space to set the Active Operational Dataset. 414 * @retval OT_ERROR_NOT_IMPLEMENTED The platform does not implement settings functionality. 415 * 416 */ 417 otError otDatasetSetActiveTlvs(otInstance *aInstance, const otOperationalDatasetTlvs *aDataset); 418 419 /** 420 * This function gets the Pending Operational Dataset. 421 * 422 * @param[in] aInstance A pointer to an OpenThread instance. 423 * @param[out] aDataset A pointer to where the Pending Operational Dataset will be placed. 424 * 425 * @retval OT_ERROR_NONE Successfully retrieved the Pending Operational Dataset. 426 * @retval OT_ERROR_NOT_FOUND No corresponding value in the setting store. 427 * 428 */ 429 otError otDatasetGetPending(otInstance *aInstance, otOperationalDataset *aDataset); 430 431 /** 432 * This function gets the Pending Operational Dataset. 433 * 434 * @param[in] aInstance A pointer to an OpenThread instance. 435 * @param[out] aDataset A pointer to where the Pending Operational Dataset will be placed. 436 * 437 * @retval OT_ERROR_NONE Successfully retrieved the Pending Operational Dataset. 438 * @retval OT_ERROR_NOT_FOUND No corresponding value in the setting store. 439 * 440 */ 441 otError otDatasetGetPendingTlvs(otInstance *aInstance, otOperationalDatasetTlvs *aDataset); 442 443 /** 444 * Sets the Pending Operational Dataset. 445 * 446 * @param[in] aInstance A pointer to an OpenThread instance. 447 * @param[in] aDataset A pointer to the Pending Operational Dataset. 448 * 449 * @retval OT_ERROR_NONE Successfully set the Pending Operational Dataset. 450 * @retval OT_ERROR_NO_BUFS Insufficient buffer space to set the Pending Operational Dataset. 451 * @retval OT_ERROR_NOT_IMPLEMENTED The platform does not implement settings functionality. 452 * 453 */ 454 otError otDatasetSetPending(otInstance *aInstance, const otOperationalDataset *aDataset); 455 456 /** 457 * This function sets the Pending Operational Dataset. 458 * 459 * @param[in] aInstance A pointer to an OpenThread instance. 460 * @param[in] aDataset A pointer to the Pending Operational Dataset. 461 * 462 * @retval OT_ERROR_NONE Successfully set the Pending Operational Dataset. 463 * @retval OT_ERROR_NO_BUFS Insufficient buffer space to set the Pending Operational Dataset. 464 * @retval OT_ERROR_NOT_IMPLEMENTED The platform does not implement settings functionality. 465 * 466 */ 467 otError otDatasetSetPendingTlvs(otInstance *aInstance, const otOperationalDatasetTlvs *aDataset); 468 469 /** 470 * Sends MGMT_ACTIVE_GET. 471 * 472 * @param[in] aInstance A pointer to an OpenThread instance. 473 * @param[in] aDatasetComponents A pointer to a Dataset Components structure specifying which components to request. 474 * @param[in] aTlvTypes A pointer to array containing additional raw TLV types to be requested. 475 * @param[in] aLength The length of @p aTlvTypes. 476 * @param[in] aAddress A pointer to the IPv6 destination, if it is NULL, will use Leader ALOC as default. 477 * 478 * @retval OT_ERROR_NONE Successfully send the meshcop dataset command. 479 * @retval OT_ERROR_NO_BUFS Insufficient buffer space to send. 480 * 481 */ 482 otError otDatasetSendMgmtActiveGet(otInstance *aInstance, 483 const otOperationalDatasetComponents *aDatasetComponents, 484 const uint8_t *aTlvTypes, 485 uint8_t aLength, 486 const otIp6Address *aAddress); 487 488 /** 489 * Sends MGMT_ACTIVE_SET. 490 * 491 * @param[in] aInstance A pointer to an OpenThread instance. 492 * @param[in] aDataset A pointer to operational dataset. 493 * @param[in] aTlvs A pointer to TLVs. 494 * @param[in] aLength The length of TLVs. 495 * @param[in] aCallback A pointer to a function that is called on response reception or timeout. 496 * @param[in] aContext A pointer to application-specific context for @p aCallback. 497 * 498 * @retval OT_ERROR_NONE Successfully send the meshcop dataset command. 499 * @retval OT_ERROR_NO_BUFS Insufficient buffer space to send. 500 * @retval OT_ERROR_BUSY A previous request is ongoing. 501 * 502 */ 503 otError otDatasetSendMgmtActiveSet(otInstance *aInstance, 504 const otOperationalDataset *aDataset, 505 const uint8_t *aTlvs, 506 uint8_t aLength, 507 otDatasetMgmtSetCallback aCallback, 508 void *aContext); 509 510 /** 511 * Sends MGMT_PENDING_GET. 512 * 513 * @param[in] aInstance A pointer to an OpenThread instance. 514 * @param[in] aDatasetComponents A pointer to a Dataset Components structure specifying which components to request. 515 * @param[in] aTlvTypes A pointer to array containing additional raw TLV types to be requested. 516 * @param[in] aLength The length of @p aTlvTypes. 517 * @param[in] aAddress A pointer to the IPv6 destination, if it is NULL, will use Leader ALOC as default. 518 * 519 * @retval OT_ERROR_NONE Successfully send the meshcop dataset command. 520 * @retval OT_ERROR_NO_BUFS Insufficient buffer space to send. 521 * 522 */ 523 otError otDatasetSendMgmtPendingGet(otInstance *aInstance, 524 const otOperationalDatasetComponents *aDatasetComponents, 525 const uint8_t *aTlvTypes, 526 uint8_t aLength, 527 const otIp6Address *aAddress); 528 529 /** 530 * Sends MGMT_PENDING_SET. 531 * 532 * @param[in] aInstance A pointer to an OpenThread instance. 533 * @param[in] aDataset A pointer to operational dataset. 534 * @param[in] aTlvs A pointer to TLVs. 535 * @param[in] aLength The length of TLVs. 536 * @param[in] aCallback A pointer to a function that is called on response reception or timeout. 537 * @param[in] aContext A pointer to application-specific context for @p aCallback. 538 * 539 * @retval OT_ERROR_NONE Successfully send the meshcop dataset command. 540 * @retval OT_ERROR_NO_BUFS Insufficient buffer space to send. 541 * @retval OT_ERROR_BUSY A previous request is ongoing. 542 * 543 */ 544 otError otDatasetSendMgmtPendingSet(otInstance *aInstance, 545 const otOperationalDataset *aDataset, 546 const uint8_t *aTlvs, 547 uint8_t aLength, 548 otDatasetMgmtSetCallback aCallback, 549 void *aContext); 550 551 /** 552 * This function generates PSKc from a given pass-phrase, network name, and extended PAN ID. 553 * 554 * PSKc is used to establish the Commissioner Session. 555 * 556 * @param[in] aPassPhrase The commissioning pass-phrase. 557 * @param[in] aNetworkName The network name for PSKc computation. 558 * @param[in] aExtPanId The extended PAN ID for PSKc computation. 559 * @param[out] aPskc A pointer to variable to output the generated PSKc. 560 * 561 * @retval OT_ERROR_NONE Successfully generate PSKc. 562 * @retval OT_ERROR_INVALID_ARGS If any of the input arguments is invalid. 563 * 564 */ 565 otError otDatasetGeneratePskc(const char *aPassPhrase, 566 const otNetworkName *aNetworkName, 567 const otExtendedPanId *aExtPanId, 568 otPskc *aPskc); 569 570 /** 571 * Sets an `otNetworkName` instance from a given null terminated C string. 572 * 573 * @p aNameString must follow UTF-8 encoding and the Network Name length must not be longer than 574 * `OT_NETWORK_NAME_MAX_SIZE`. 575 * 576 * @param[out] aNetworkName A pointer to the `otNetworkName` to set. 577 * @param[in] aNameString A name C string. 578 * 579 * @retval OT_ERROR_NONE Successfully set @p aNetworkName from @p aNameString. 580 * @retval OT_ERROR_INVALID_ARGS @p aNameStrng is invalid (too long or does not follow UTF-8 encoding). 581 * 582 */ 583 otError otNetworkNameFromString(otNetworkName *aNetworkName, const char *aNameString); 584 585 /** 586 * Parses an Operational Dataset from a given `otOperationalDatasetTlvs`. 587 * 588 * @param[in] aDatasetTlvs A pointer to dataset TLVs. 589 * @param[out] aDataset A pointer to where the dataset will be placed. 590 * 591 * @retval OT_ERROR_NONE Successfully set @p aDataset from @p aDatasetTlvs. 592 * @retval OT_ERROR_INVALID_ARGS @p aDatasetTlvs is invalid. 593 * 594 */ 595 otError otDatasetParseTlvs(const otOperationalDatasetTlvs *aDatasetTlvs, otOperationalDataset *aDataset); 596 597 /** 598 * Converts a given Operational Dataset to `otOperationalDatasetTlvs`. 599 * 600 * @param[in] aDataset An Operational dataset to convert to TLVs. 601 * @param[out] aDatasetTlvs A pointer to dataset TLVs to return the result. 602 * 603 * @retval OT_ERROR_NONE Successfully converted @p aDataset and updated @p aDatasetTlvs. 604 * @retval OT_ERROR_INVALID_ARGS @p aDataset is invalid, does not contain active or pending timestamps. 605 * 606 */ 607 otError otDatasetConvertToTlvs(const otOperationalDataset *aDataset, otOperationalDatasetTlvs *aDatasetTlvs); 608 609 /** 610 * Updates a given Operational Dataset. 611 * 612 * @p aDataset contains the fields to be updated and their new value. 613 * 614 * @param[in] aDataset Specifies the set of types and values to update. 615 * @param[in,out] aDatasetTlvs A pointer to dataset TLVs to update. 616 * 617 * @retval OT_ERROR_NONE Successfully updated @p aDatasetTlvs. 618 * @retval OT_ERROR_INVALID_ARGS @p aDataset contains invalid values. 619 * @retval OT_ERROR_NO_BUFS Not enough space space in @p aDatasetTlvs to apply the update. 620 * 621 */ 622 otError otDatasetUpdateTlvs(const otOperationalDataset *aDataset, otOperationalDatasetTlvs *aDatasetTlvs); 623 624 /** 625 * @} 626 * 627 */ 628 629 #ifdef __cplusplus 630 } // extern "C" 631 #endif 632 633 #endif // OPENTHREAD_DATASET_H_ 634
