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