Operational Dataset

This module includes functions for Dataset Updater.

Summary

The functions in this module are available when Dataset Updater feature is enabled (i.e. OPENTHREAD_CONFIG_DATASET_UPDATER_ENABLE is set to 1). Further this feature is available only on an FTD build.

Enumerations

otMeshcopTlvType{   OT_MESHCOP_TLV_CHANNEL = 0,   OT_MESHCOP_TLV_PANID = 1,   OT_MESHCOP_TLV_EXTPANID = 2,   OT_MESHCOP_TLV_NETWORKNAME = 3,   OT_MESHCOP_TLV_PSKC = 4,   OT_MESHCOP_TLV_NETWORKKEY = 5,   OT_MESHCOP_TLV_NETWORK_KEY_SEQUENCE = 6,   OT_MESHCOP_TLV_MESHLOCALPREFIX = 7,   OT_MESHCOP_TLV_STEERING_DATA = 8,   OT_MESHCOP_TLV_BORDER_AGENT_RLOC = 9,   OT_MESHCOP_TLV_COMMISSIONER_ID = 10,   OT_MESHCOP_TLV_COMM_SESSION_ID = 11,   OT_MESHCOP_TLV_SECURITYPOLICY = 12,   OT_MESHCOP_TLV_GET = 13,   OT_MESHCOP_TLV_ACTIVETIMESTAMP = 14,   OT_MESHCOP_TLV_COMMISSIONER_UDP_PORT = 15,   OT_MESHCOP_TLV_STATE = 16,   OT_MESHCOP_TLV_JOINER_DTLS = 17,   OT_MESHCOP_TLV_JOINER_UDP_PORT = 18,   OT_MESHCOP_TLV_JOINER_IID = 19,   OT_MESHCOP_TLV_JOINER_RLOC = 20,   OT_MESHCOP_TLV_JOINER_ROUTER_KEK = 21,   OT_MESHCOP_TLV_PROVISIONING_URL = 32,   OT_MESHCOP_TLV_VENDOR_NAME_TLV = 33,   OT_MESHCOP_TLV_VENDOR_MODEL_TLV = 34,   OT_MESHCOP_TLV_VENDOR_SW_VERSION_TLV = 35,   OT_MESHCOP_TLV_VENDOR_DATA_TLV = 36,   OT_MESHCOP_TLV_VENDOR_STACK_VERSION_TLV = 37,   OT_MESHCOP_TLV_UDP_ENCAPSULATION_TLV = 48,   OT_MESHCOP_TLV_IPV6_ADDRESS_TLV = 49,   OT_MESHCOP_TLV_PENDINGTIMESTAMP = 51,   OT_MESHCOP_TLV_DELAYTIMER = 52,   OT_MESHCOP_TLV_CHANNELMASK = 53,   OT_MESHCOP_TLV_COUNT = 54,   OT_MESHCOP_TLV_PERIOD = 55,   OT_MESHCOP_TLV_SCAN_DURATION = 56,   OT_MESHCOP_TLV_ENERGY_LIST = 57,   OT_MESHCOP_TLV_DISCOVERYREQUEST = 128,   OT_MESHCOP_TLV_DISCOVERYRESPONSE = 129,   OT_MESHCOP_TLV_JOINERADVERTISEMENT = 241 }

enum This enumeration represents meshcop TLV types.

Typedefs
otChannelMask	typedef uint32_t This type represents Channel Mask.
otDatasetMgmtSetCallback)(otError aResult, void *aContext)	typedef void(* This function pointer is called when a response to a MGMT_SET request is received or times out.
otDatasetUpdaterCallback)(otError aError, void *aContext)	typedef void(* This callback function pointer is called when a Dataset update request finishes, reporting success or failure status of the Dataset update request.
otExtendedPanId	typedef struct otExtendedPanId This structure represents an Extended PAN ID.
otMeshLocalPrefix	typedef otIp6NetworkPrefix This structure represents a Mesh Local Prefix.
otMeshcopTlvType	typedef enum otMeshcopTlvType This enumeration represents meshcop TLV types.
otNetworkKey	typedef struct otNetworkKey This structure represents a Thread Network Key.
otNetworkKeyRef	typedef otCryptoKeyRef This datatype represents KeyRef to NetworkKey.
otNetworkName	typedef struct otNetworkName This structure represents a Network Name.
otOperationalDataset	typedef struct otOperationalDataset This structure represents an Active or Pending Operational Dataset.
otOperationalDatasetComponents	typedef struct otOperationalDatasetComponents This structure represents presence of different components in Active or Pending Operational Dataset.
otOperationalDatasetTlvs	typedef struct otOperationalDatasetTlvs This structure represents an Active or Pending Operational Dataset.
otPskc	typedef struct otPskc This structure represents a PSKc.
otPskcRef	typedef otCryptoKeyRef This datatype represents KeyRef to PSKc.
otSecurityPolicy	typedef struct otSecurityPolicy This structure represent Security Policy.
otTimestamp	typedef struct otTimestamp This structure represents a Thread Dataset timestamp component.

Variables
OT_TOOL_PACKED_END	OT_TOOL_PACKED_BEGIN struct otNetworkKey

Functions
otDatasetCreateNewNetwork(otInstance *aInstance, otOperationalDataset *aDataset)	otError This method creates a new Operational Dataset to use when forming a new network.
otDatasetGeneratePskc(const char *aPassPhrase, const otNetworkName *aNetworkName, const otExtendedPanId *aExtPanId, otPskc *aPskc)	otError This function generates PSKc from a given pass-phrase, network name, and extended PAN ID.
otDatasetGetActive(otInstance *aInstance, otOperationalDataset *aDataset)	otError This function gets the Active Operational Dataset.
otDatasetGetActiveTlvs(otInstance *aInstance, otOperationalDatasetTlvs *aDataset)	otError This function gets the Active Operational Dataset.
otDatasetGetDelayTimerMinimal(otInstance *aInstance)	uint32_t Get minimal delay timer.
otDatasetGetPending(otInstance *aInstance, otOperationalDataset *aDataset)	otError This function gets the Pending Operational Dataset.
otDatasetGetPendingTlvs(otInstance *aInstance, otOperationalDatasetTlvs *aDataset)	otError This function gets the Pending Operational Dataset.
otDatasetIsCommissioned(otInstance *aInstance)	bool This function indicates whether a valid network is present in the Active Operational Dataset or not.
otDatasetParseTlvs(const otOperationalDatasetTlvs *aDatasetTlvs, otOperationalDataset *aDataset)	otError This function parses an Operational Dataset from a otOperationalDatasetTlvs.
otDatasetSendMgmtActiveGet(otInstance *aInstance, const otOperationalDatasetComponents *aDatasetComponents, const uint8_t *aTlvTypes, uint8_t aLength, const otIp6Address *aAddress)	otError This function sends MGMT_ACTIVE_GET.
otDatasetSendMgmtActiveSet(otInstance *aInstance, const otOperationalDataset *aDataset, const uint8_t *aTlvs, uint8_t aLength, otDatasetMgmtSetCallback aCallback, void *aContext)	otError This function sends MGMT_ACTIVE_SET.
otDatasetSendMgmtPendingGet(otInstance *aInstance, const otOperationalDatasetComponents *aDatasetComponents, const uint8_t *aTlvTypes, uint8_t aLength, const otIp6Address *aAddress)	otError This function sends MGMT_PENDING_GET.
otDatasetSendMgmtPendingSet(otInstance *aInstance, const otOperationalDataset *aDataset, const uint8_t *aTlvs, uint8_t aLength, otDatasetMgmtSetCallback aCallback, void *aContext)	otError This function sends MGMT_PENDING_SET.
otDatasetSetActive(otInstance *aInstance, const otOperationalDataset *aDataset)	otError This function sets the Active Operational Dataset.
otDatasetSetActiveTlvs(otInstance *aInstance, const otOperationalDatasetTlvs *aDataset)	otError This function sets the Active Operational Dataset.
otDatasetSetDelayTimerMinimal(otInstance *aInstance, uint32_t aDelayTimerMinimal)	otError Set minimal delay timer.
otDatasetSetPending(otInstance *aInstance, const otOperationalDataset *aDataset)	otError This function sets the Pending Operational Dataset.
otDatasetSetPendingTlvs(otInstance *aInstance, const otOperationalDatasetTlvs *aDataset)	otError This function sets the Pending Operational Dataset.
otDatasetUpdaterCancelUpdate(otInstance *aInstance)	void This function cancels an ongoing (if any) Operational Dataset update request.
otDatasetUpdaterIsUpdateOngoing(otInstance *aInstance)	bool This function indicates whether there is an ongoing Operation Dataset update request.
otDatasetUpdaterRequestUpdate(otInstance *aInstance, const otOperationalDataset *aDataset, otDatasetUpdaterCallback aCallback, void *aContext)	otError This function requests an update to Operational Dataset.
otNetworkNameFromString(otNetworkName *aNetworkName, const char *aNameString)	otError This function sets an otNetworkName instance from a given null terminated C string.

Macros
OT_CHANNEL_10_MASK (1 << 10)	Channel 10.
OT_CHANNEL_11_MASK (1 << 11)	Channel 11.
OT_CHANNEL_12_MASK (1 << 12)	Channel 12.
OT_CHANNEL_13_MASK (1 << 13)	Channel 13.
OT_CHANNEL_14_MASK (1 << 14)	Channel 14.
OT_CHANNEL_15_MASK (1 << 15)	Channel 15.
OT_CHANNEL_16_MASK (1 << 16)	Channel 16.
OT_CHANNEL_17_MASK (1 << 17)	Channel 17.
OT_CHANNEL_18_MASK (1 << 18)	Channel 18.
OT_CHANNEL_19_MASK (1 << 19)	Channel 19.
OT_CHANNEL_1_MASK (1 << 1)	Channel 1.
OT_CHANNEL_20_MASK (1 << 20)	Channel 20.
OT_CHANNEL_21_MASK (1 << 21)	Channel 21.
OT_CHANNEL_22_MASK (1 << 22)	Channel 22.
OT_CHANNEL_23_MASK (1 << 23)	Channel 23.
OT_CHANNEL_24_MASK (1 << 24)	Channel 24.
OT_CHANNEL_25_MASK (1 << 25)	Channel 25.
OT_CHANNEL_26_MASK (1 << 26)	Channel 26.
OT_CHANNEL_2_MASK (1 << 2)	Channel 2.
OT_CHANNEL_3_MASK (1 << 3)	Channel 3.
OT_CHANNEL_4_MASK (1 << 4)	Channel 4.
OT_CHANNEL_5_MASK (1 << 5)	Channel 5.
OT_CHANNEL_6_MASK (1 << 6)	Channel 6.
OT_CHANNEL_7_MASK (1 << 7)	Channel 7.
OT_CHANNEL_8_MASK (1 << 8)	Channel 8.
OT_CHANNEL_9_MASK (1 << 9)	Channel 9.
OT_EXT_PAN_ID_SIZE 8	Size of a Thread PAN ID (bytes)
OT_MESH_LOCAL_PREFIX_SIZE OT_IP6_PREFIX_SIZE	Size of the Mesh Local Prefix (bytes)
OT_NETWORK_KEY_SIZE 16	Size of the Thread Network Key (bytes)
OT_NETWORK_NAME_MAX_SIZE 16	Maximum size of the Thread Network Name field (bytes)
OT_OPERATIONAL_DATASET_MAX_LENGTH 254	Maximum length of Operational Dataset in bytes.
OT_PSKC_MAX_SIZE 16	Maximum size of the PSKc (bytes)

Structs
otExtendedPanId	This structure represents an Extended PAN ID.
otNetworkKey	This structure represents a Thread Network Key.
otNetworkName	This structure represents a Network Name.
otOperationalDataset	This structure represents an Active or Pending Operational Dataset.
otOperationalDatasetComponents	This structure represents presence of different components in Active or Pending Operational Dataset.
otOperationalDatasetTlvs	This structure represents an Active or Pending Operational Dataset.
otPskc	This structure represents PSKc.
otSecurityPolicy	This structure represent Security Policy.
otTimestamp	This structure represents a Thread Dataset timestamp component.

Enumerations

otMeshcopTlvType

 otMeshcopTlvType

This enumeration represents meshcop TLV types.

Properties
OT_MESHCOP_TLV_ACTIVETIMESTAMP	meshcop Active Timestamp TLV
OT_MESHCOP_TLV_BORDER_AGENT_RLOC	meshcop Border Agent Locator TLV
OT_MESHCOP_TLV_CHANNEL	meshcop Channel TLV
OT_MESHCOP_TLV_CHANNELMASK	meshcop Channel Mask TLV
OT_MESHCOP_TLV_COMMISSIONER_ID	meshcop Commissioner ID TLV
OT_MESHCOP_TLV_COMMISSIONER_UDP_PORT	meshcop Commissioner UDP Port TLV
OT_MESHCOP_TLV_COMM_SESSION_ID	meshcop Commissioner Session ID TLV
OT_MESHCOP_TLV_COUNT	meshcop Count TLV
OT_MESHCOP_TLV_DELAYTIMER	meshcop Delay Timer TLV
OT_MESHCOP_TLV_DISCOVERYREQUEST	meshcop Discovery Request TLV
OT_MESHCOP_TLV_DISCOVERYRESPONSE	meshcop Discovery Response TLV
OT_MESHCOP_TLV_ENERGY_LIST	meshcop Energy List TLV
OT_MESHCOP_TLV_EXTPANID	meshcop Extended Pan Id TLV
OT_MESHCOP_TLV_GET	meshcop Get TLV
OT_MESHCOP_TLV_IPV6_ADDRESS_TLV	meshcop IPv6 address TLV
OT_MESHCOP_TLV_JOINERADVERTISEMENT	meshcop Joiner Advertisement TLV
OT_MESHCOP_TLV_JOINER_DTLS	meshcop Joiner DTLS Encapsulation TLV
OT_MESHCOP_TLV_JOINER_IID	meshcop Joiner IID TLV
OT_MESHCOP_TLV_JOINER_RLOC	meshcop Joiner Router Locator TLV
OT_MESHCOP_TLV_JOINER_ROUTER_KEK	meshcop Joiner Router KEK TLV
OT_MESHCOP_TLV_JOINER_UDP_PORT	meshcop Joiner UDP Port TLV
OT_MESHCOP_TLV_MESHLOCALPREFIX	meshcop Mesh Local Prefix TLV
OT_MESHCOP_TLV_NETWORKKEY	meshcop Network Key TLV
OT_MESHCOP_TLV_NETWORKNAME	meshcop Network Name TLV
OT_MESHCOP_TLV_NETWORK_KEY_SEQUENCE	meshcop Network Key Sequence TLV
OT_MESHCOP_TLV_PANID	meshcop Pan Id TLV
OT_MESHCOP_TLV_PENDINGTIMESTAMP	meshcop Pending Timestamp TLV
OT_MESHCOP_TLV_PERIOD	meshcop Period TLV
OT_MESHCOP_TLV_PROVISIONING_URL	meshcop Provisioning URL TLV
OT_MESHCOP_TLV_PSKC	meshcop PSKc TLV
OT_MESHCOP_TLV_SCAN_DURATION	meshcop Scan Duration TLV
OT_MESHCOP_TLV_SECURITYPOLICY	meshcop Security Policy TLV
OT_MESHCOP_TLV_STATE	meshcop State TLV
OT_MESHCOP_TLV_STEERING_DATA	meshcop Steering Data TLV
OT_MESHCOP_TLV_UDP_ENCAPSULATION_TLV	meshcop UDP encapsulation TLV
OT_MESHCOP_TLV_VENDOR_DATA_TLV	meshcop Vendor Data TLV
OT_MESHCOP_TLV_VENDOR_MODEL_TLV	meshcop Vendor Model TLV
OT_MESHCOP_TLV_VENDOR_NAME_TLV	meshcop Vendor Name TLV
OT_MESHCOP_TLV_VENDOR_STACK_VERSION_TLV	meshcop Vendor Stack Version TLV
OT_MESHCOP_TLV_VENDOR_SW_VERSION_TLV	meshcop Vendor SW Version TLV

Typedefs

otChannelMask

uint32_t otChannelMask

This type represents Channel Mask.

otDatasetMgmtSetCallback

void(* otDatasetMgmtSetCallback)(otError aResult, void *aContext)

This function pointer is called when a response to a MGMT_SET request is received or times out.

Details
Parameters	[in] aResult A result of the operation. [in] aContext A pointer to application-specific context.
Return Values	OT_ERROR_NONE The request was accepted by the leader. OT_ERROR_REJECTED The request was rejected by the leader. OT_ERROR_PARSE An error occurred during parsing the response. OT_ERROR_ABORT The request was reset by peer. OT_ERROR_RESPONSE_TIMEOUT No response or acknowledgment received during timeout period.

otDatasetUpdaterCallback

void(* otDatasetUpdaterCallback)(otError aError, void *aContext)

This callback function pointer is called when a Dataset update request finishes, reporting success or failure status of the Dataset update request.

Details
Parameters	[in] aError The error status. OT_ERROR_NONE indicates successful Dataset update. OT_ERROR_INVALID_STATE indicates failure due invalid state (MLE being disabled). OT_ERROR_ALREADY indicates failure due to another device within network requesting a conflicting Dataset update. [in] aContext A pointer to the arbitrary context (provided by user in otDatasetUpdaterRequestUpdate()).

otExtendedPanId

struct otExtendedPanId otExtendedPanId

This structure represents an Extended PAN ID.

otMeshLocalPrefix

otIp6NetworkPrefix otMeshLocalPrefix

This structure represents a Mesh Local Prefix.

otMeshcopTlvType

enum otMeshcopTlvType otMeshcopTlvType

This enumeration represents meshcop TLV types.

otNetworkKey

struct otNetworkKey otNetworkKey

This structure represents a Thread Network Key.

otNetworkKeyRef

otCryptoKeyRef otNetworkKeyRef

This datatype represents KeyRef to NetworkKey.

Reference to Key

otNetworkName

struct otNetworkName otNetworkName

This structure represents a Network Name.

The otNetworkName is a null terminated C string (i.e., m8 char array MUST end with null char \0).

otOperationalDataset

struct otOperationalDataset otOperationalDataset

This structure represents an Active or Pending Operational Dataset.

Components in Dataset are optional. mComponets structure specifies which components are present in the Dataset.

otOperationalDatasetComponents

struct otOperationalDatasetComponents otOperationalDatasetComponents

This structure represents presence of different components in Active or Pending Operational Dataset.

otOperationalDatasetTlvs

struct otOperationalDatasetTlvs otOperationalDatasetTlvs

This structure represents an Active or Pending Operational Dataset.

The Operational Dataset is TLV encoded as specified by Thread.

otPskc

struct otPskc otPskc

This structure represents a PSKc.

otPskcRef

otCryptoKeyRef otPskcRef

This datatype represents KeyRef to PSKc.

Reference to Key

otSecurityPolicy

struct otSecurityPolicy otSecurityPolicy

This structure represent Security Policy.

otTimestamp

struct otTimestamp otTimestamp

This structure represents a Thread Dataset timestamp component.

Variables

OT_TOOL_PACKED_END

OT_TOOL_PACKED_BEGIN struct otNetworkKey OT_TOOL_PACKED_END

Functions

otDatasetCreateNewNetwork

otError otDatasetCreateNewNetwork(
  otInstance *aInstance,
  otOperationalDataset *aDataset
)

This method creates a new Operational Dataset to use when forming a new network.

Details
Parameters	[in] aInstance A pointer to an OpenThread instance. [out] aDataset The Operational Dataset.
Return Values	OT_ERROR_NONE Successfully created a new Operational Dataset. OT_ERROR_FAILED Failed to generate random values for new parameters.

otDatasetGeneratePskc

otError otDatasetGeneratePskc(
  const char *aPassPhrase,
  const otNetworkName *aNetworkName,
  const otExtendedPanId *aExtPanId,
  otPskc *aPskc
)

This function generates PSKc from a given pass-phrase, network name, and extended PAN ID.

PSKc is used to establish the Commissioner Session.

Details
Parameters	[in] aPassPhrase The commissioning pass-phrase. [in] aNetworkName The network name for PSKc computation. [in] aExtPanId The extended PAN ID for PSKc computation. [out] aPskc A pointer to variable to output the generated PSKc.
Return Values	OT_ERROR_NONE Successfully generate PSKc. OT_ERROR_INVALID_ARGS If any of the input arguments is invalid.

otDatasetGetActive

otError otDatasetGetActive(
  otInstance *aInstance,
  otOperationalDataset *aDataset
)

This function gets the Active Operational Dataset.

Details
Parameters	[in] aInstance A pointer to an OpenThread instance. [out] aDataset A pointer to where the Active Operational Dataset will be placed.
Return Values	OT_ERROR_NONE Successfully retrieved the Active Operational Dataset. OT_ERROR_NOT_FOUND No corresponding value in the setting store.

otDatasetGetActiveTlvs

otError otDatasetGetActiveTlvs(
  otInstance *aInstance,
  otOperationalDatasetTlvs *aDataset
)

This function gets the Active Operational Dataset.

Details
Parameters	[in] aInstance A pointer to an OpenThread instance. [out] aDataset A pointer to where the Active Operational Dataset will be placed.
Return Values	OT_ERROR_NONE Successfully retrieved the Active Operational Dataset. OT_ERROR_NOT_FOUND No corresponding value in the setting store.

otDatasetGetDelayTimerMinimal

uint32_t otDatasetGetDelayTimerMinimal(
  otInstance *aInstance
)

Get minimal delay timer.

Details
Parameters	[in] aInstance A pointer to an OpenThread instance.
Return Values	the value of minimal delay timer (in ms).

otDatasetGetPending

otError otDatasetGetPending(
  otInstance *aInstance,
  otOperationalDataset *aDataset
)

This function gets the Pending Operational Dataset.

Details
Parameters	[in] aInstance A pointer to an OpenThread instance. [out] aDataset A pointer to where the Pending Operational Dataset will be placed.
Return Values	OT_ERROR_NONE Successfully retrieved the Pending Operational Dataset. OT_ERROR_NOT_FOUND No corresponding value in the setting store.

otDatasetGetPendingTlvs

otError otDatasetGetPendingTlvs(
  otInstance *aInstance,
  otOperationalDatasetTlvs *aDataset
)

This function gets the Pending Operational Dataset.

Details
Parameters	[in] aInstance A pointer to an OpenThread instance. [out] aDataset A pointer to where the Pending Operational Dataset will be placed.
Return Values	OT_ERROR_NONE Successfully retrieved the Pending Operational Dataset. OT_ERROR_NOT_FOUND No corresponding value in the setting store.

otDatasetIsCommissioned

bool otDatasetIsCommissioned(
  otInstance *aInstance
)

This function indicates whether a valid network is present in the Active Operational Dataset or not.

Details
Parameters	[in] aInstance A pointer to an OpenThread instance.
Returns	TRUE if a valid network is present in the Active Operational Dataset, FALSE otherwise.

otDatasetParseTlvs

otError otDatasetParseTlvs(
  const otOperationalDatasetTlvs *aDatasetTlvs,
  otOperationalDataset *aDataset
)

This function parses an Operational Dataset from a otOperationalDatasetTlvs.

Details
Parameters	[in] aDatasetTlvs A pointer to dataset TLVs. [out] aDataset A pointer to where the dataset will be placed.
Return Values	OT_ERROR_NONE Successfully set aDataset from aDatasetTlvs. OT_ERROR_INVALID_ARGS aDatasetTlvs is invalid.

otDatasetSendMgmtActiveGet

otError otDatasetSendMgmtActiveGet(
  otInstance *aInstance,
  const otOperationalDatasetComponents *aDatasetComponents,
  const uint8_t *aTlvTypes,
  uint8_t aLength,
  const otIp6Address *aAddress
)

This function sends MGMT_ACTIVE_GET.

Details
Parameters	[in] aInstance A pointer to an OpenThread instance. [in] aDatasetComponents A pointer to a Dataset Components structure specifying which components to request. [in] aTlvTypes A pointer to array containing additional raw TLV types to be requested. [in] aLength The length of aTlvTypes. [in] aAddress A pointer to the IPv6 destination, if it is NULL, will use Leader ALOC as default.
Return Values	OT_ERROR_NONE Successfully send the meshcop dataset command. OT_ERROR_NO_BUFS Insufficient buffer space to send.

otDatasetSendMgmtActiveSet

otError otDatasetSendMgmtActiveSet(
  otInstance *aInstance,
  const otOperationalDataset *aDataset,
  const uint8_t *aTlvs,
  uint8_t aLength,
  otDatasetMgmtSetCallback aCallback,
  void *aContext
)

This function sends MGMT_ACTIVE_SET.

Details
Parameters	[in] aInstance A pointer to an OpenThread instance. [in] aDataset A pointer to operational dataset. [in] aTlvs A pointer to TLVs. [in] aLength The length of TLVs. [in] aCallback A pointer to a function that is called on response reception or timeout. [in] aContext A pointer to application-specific context for aCallback.
Return Values	OT_ERROR_NONE Successfully send the meshcop dataset command. OT_ERROR_NO_BUFS Insufficient buffer space to send. OT_ERROR_BUSY A previous request is ongoing.

otDatasetSendMgmtPendingGet

otError otDatasetSendMgmtPendingGet(
  otInstance *aInstance,
  const otOperationalDatasetComponents *aDatasetComponents,
  const uint8_t *aTlvTypes,
  uint8_t aLength,
  const otIp6Address *aAddress
)

This function sends MGMT_PENDING_GET.

Details
Parameters	[in] aInstance A pointer to an OpenThread instance. [in] aDatasetComponents A pointer to a Dataset Components structure specifying which components to request. [in] aTlvTypes A pointer to array containing additional raw TLV types to be requested. [in] aLength The length of aTlvTypes. [in] aAddress A pointer to the IPv6 destination, if it is NULL, will use Leader ALOC as default.
Return Values	OT_ERROR_NONE Successfully send the meshcop dataset command. OT_ERROR_NO_BUFS Insufficient buffer space to send.

otDatasetSendMgmtPendingSet

otError otDatasetSendMgmtPendingSet(
  otInstance *aInstance,
  const otOperationalDataset *aDataset,
  const uint8_t *aTlvs,
  uint8_t aLength,
  otDatasetMgmtSetCallback aCallback,
  void *aContext
)

This function sends MGMT_PENDING_SET.

Details
Parameters	[in] aInstance A pointer to an OpenThread instance. [in] aDataset A pointer to operational dataset. [in] aTlvs A pointer to TLVs. [in] aLength The length of TLVs. [in] aCallback A pointer to a function that is called on response reception or timeout. [in] aContext A pointer to application-specific context for aCallback.
Return Values	OT_ERROR_NONE Successfully send the meshcop dataset command. OT_ERROR_NO_BUFS Insufficient buffer space to send. OT_ERROR_BUSY A previous request is ongoing.

otDatasetSetActive

otError otDatasetSetActive(
  otInstance *aInstance,
  const otOperationalDataset *aDataset
)

This function sets the Active Operational Dataset.

If the dataset does not include an Active Timestamp, the dataset is only partially complete.

If Thread is enabled on a device that has a partially complete Active Dataset, the device will attempt to attach to an existing Thread network using any existing information in the dataset. Only the Thread Network Key is needed to attach to a network.

If channel is not included in the dataset, the device will send MLE Announce messages across different channels to find neighbors on other channels.

If the device successfully attaches to a Thread network, the device will then retrieve the full Active Dataset from its Parent. Note that a router-capable device will not transition to the Router or Leader roles until it has a complete Active Dataset.

Details
Parameters	[in] aInstance A pointer to an OpenThread instance. [in] aDataset A pointer to the Active Operational Dataset.
Return Values	OT_ERROR_NONE Successfully set the Active Operational Dataset. OT_ERROR_NO_BUFS Insufficient buffer space to set the Active Operational Dataset. OT_ERROR_NOT_IMPLEMENTED The platform does not implement settings functionality.

otDatasetSetActiveTlvs

otError otDatasetSetActiveTlvs(
  otInstance *aInstance,
  const otOperationalDatasetTlvs *aDataset
)

This function sets the Active Operational Dataset.

If the dataset does not include an Active Timestamp, the dataset is only partially complete.

If Thread is enabled on a device that has a partially complete Active Dataset, the device will attempt to attach to an existing Thread network using any existing information in the dataset. Only the Thread Network Key is needed to attach to a network.

If channel is not included in the dataset, the device will send MLE Announce messages across different channels to find neighbors on other channels.

If the device successfully attaches to a Thread network, the device will then retrieve the full Active Dataset from its Parent. Note that a router-capable device will not transition to the Router or Leader roles until it has a complete Active Dataset.

Details
Parameters	[in] aInstance A pointer to an OpenThread instance. [in] aDataset A pointer to the Active Operational Dataset.
Return Values	OT_ERROR_NONE Successfully set the Active Operational Dataset. OT_ERROR_NO_BUFS Insufficient buffer space to set the Active Operational Dataset. OT_ERROR_NOT_IMPLEMENTED The platform does not implement settings functionality.

otDatasetSetDelayTimerMinimal

otError otDatasetSetDelayTimerMinimal(
  otInstance *aInstance,
  uint32_t aDelayTimerMinimal
)

Set minimal delay timer.

Note: This API is reserved for testing and demo purposes only. Changing settings with this API will render a production application non-compliant with the Thread Specification.

Details
Parameters	[in] aInstance A pointer to an OpenThread instance. [in] aDelayTimerMinimal The value of minimal delay timer (in ms).
Return Values	OT_ERROR_NONE Successfully set minimal delay timer. OT_ERROR_INVALID_ARGS If aDelayTimerMinimal is not valid.

otDatasetSetPending

otError otDatasetSetPending(
  otInstance *aInstance,
  const otOperationalDataset *aDataset
)

This function sets the Pending Operational Dataset.

Details
Parameters	[in] aInstance A pointer to an OpenThread instance. [in] aDataset A pointer to the Pending Operational Dataset.
Return Values	OT_ERROR_NONE Successfully set the Pending Operational Dataset. OT_ERROR_NO_BUFS Insufficient buffer space to set the Pending Operational Dataset. OT_ERROR_NOT_IMPLEMENTED The platform does not implement settings functionality.

otDatasetSetPendingTlvs

otError otDatasetSetPendingTlvs(
  otInstance *aInstance,
  const otOperationalDatasetTlvs *aDataset
)

This function sets the Pending Operational Dataset.

Details
Parameters	[in] aInstance A pointer to an OpenThread instance. [in] aDataset A pointer to the Pending Operational Dataset.
Return Values	OT_ERROR_NONE Successfully set the Pending Operational Dataset. OT_ERROR_NO_BUFS Insufficient buffer space to set the Pending Operational Dataset. OT_ERROR_NOT_IMPLEMENTED The platform does not implement settings functionality.

otDatasetUpdaterCancelUpdate

void otDatasetUpdaterCancelUpdate(
  otInstance *aInstance
)

This function cancels an ongoing (if any) Operational Dataset update request.

Details
Parameters	[in] aInstance A pointer to an OpenThread instance.

otDatasetUpdaterIsUpdateOngoing

bool otDatasetUpdaterIsUpdateOngoing(
  otInstance *aInstance
)

This function indicates whether there is an ongoing Operation Dataset update request.

Details
Parameters	[in] aInstance A pointer to an OpenThread instance.
Return Values	TRUE There is an ongoing update. FALSE There is no ongoing update.

otDatasetUpdaterRequestUpdate

otError otDatasetUpdaterRequestUpdate(
  otInstance *aInstance,
  const otOperationalDataset *aDataset,
  otDatasetUpdaterCallback aCallback,
  void *aContext
)

This function requests an update to Operational Dataset.

aDataset should contain the fields to be updated and their new value. It must not contain Active or Pending Timestamp fields. The Delay field is optional, if not provided a default value (1000 ms) would be used.

Details
Parameters	[in] aInstance A pointer to an OpenThread instance. [in] aDataset A pointer to the Dataset containing the fields to change. [in] aCallback A callback to indicate when Dataset update request finishes. [in] aContext An arbitrary context passed to callback.
Return Values	OT_ERROR_NONE Dataset update started successfully (aCallback will be invoked on completion). OT_ERROR_INVALID_STATE Device is disabled (MLE is disabled). OT_ERROR_INVALID_ARGS The aDataset is not valid (contains Active or Pending Timestamp). OT_ERROR_BUSY Cannot start update, a previous one is ongoing. OT_ERROR_NO_BUFS Could not allocated buffer to save Dataset.

otNetworkNameFromString

otError otNetworkNameFromString(
  otNetworkName *aNetworkName,
  const char *aNameString
)

This function sets an otNetworkName instance from a given null terminated C string.

This function also validates that the given aNameString follows UTF-8 encoding and its length is not longer than OT_NETWORK_NAME_MAX_SIZE.

Details
Parameters	[out] aNetworkName A pointer to the otNetworkName to set. [in] aNameString A name C string.
Return Values	OT_ERROR_NONE Successfully set aNetworkName from aNameString. OT_ERROR_INVALID_ARGS aNameStrng is invalid (too long or does not follow UTF-8 encoding).

Macros

OT_CHANNEL_10_MASK

 OT_CHANNEL_10_MASK (1 << 10)

Channel 10.

OT_CHANNEL_11_MASK

 OT_CHANNEL_11_MASK (1 << 11)

Channel 11.

OT_CHANNEL_12_MASK

 OT_CHANNEL_12_MASK (1 << 12)

Channel 12.

OT_CHANNEL_13_MASK

 OT_CHANNEL_13_MASK (1 << 13)

Channel 13.

OT_CHANNEL_14_MASK

 OT_CHANNEL_14_MASK (1 << 14)

Channel 14.

OT_CHANNEL_15_MASK

 OT_CHANNEL_15_MASK (1 << 15)

Channel 15.

OT_CHANNEL_16_MASK

 OT_CHANNEL_16_MASK (1 << 16)

Channel 16.

OT_CHANNEL_17_MASK

 OT_CHANNEL_17_MASK (1 << 17)

Channel 17.

OT_CHANNEL_18_MASK

 OT_CHANNEL_18_MASK (1 << 18)

Channel 18.

OT_CHANNEL_19_MASK

 OT_CHANNEL_19_MASK (1 << 19)

Channel 19.

OT_CHANNEL_1_MASK

 OT_CHANNEL_1_MASK (1 << 1)

Channel 1.

OT_CHANNEL_20_MASK

 OT_CHANNEL_20_MASK (1 << 20)

Channel 20.

OT_CHANNEL_21_MASK

 OT_CHANNEL_21_MASK (1 << 21)

Channel 21.

OT_CHANNEL_22_MASK

 OT_CHANNEL_22_MASK (1 << 22)

Channel 22.

OT_CHANNEL_23_MASK

 OT_CHANNEL_23_MASK (1 << 23)

Channel 23.

OT_CHANNEL_24_MASK

 OT_CHANNEL_24_MASK (1 << 24)

Channel 24.

OT_CHANNEL_25_MASK

 OT_CHANNEL_25_MASK (1 << 25)

Channel 25.

OT_CHANNEL_26_MASK

 OT_CHANNEL_26_MASK (1 << 26)

Channel 26.

OT_CHANNEL_2_MASK

 OT_CHANNEL_2_MASK (1 << 2)

Channel 2.

OT_CHANNEL_3_MASK

 OT_CHANNEL_3_MASK (1 << 3)

Channel 3.

OT_CHANNEL_4_MASK

 OT_CHANNEL_4_MASK (1 << 4)

Channel 4.

OT_CHANNEL_5_MASK

 OT_CHANNEL_5_MASK (1 << 5)

Channel 5.

OT_CHANNEL_6_MASK

 OT_CHANNEL_6_MASK (1 << 6)

Channel 6.

OT_CHANNEL_7_MASK

 OT_CHANNEL_7_MASK (1 << 7)

Channel 7.

OT_CHANNEL_8_MASK

 OT_CHANNEL_8_MASK (1 << 8)

Channel 8.

OT_CHANNEL_9_MASK

 OT_CHANNEL_9_MASK (1 << 9)

Channel 9.

OT_EXT_PAN_ID_SIZE

 OT_EXT_PAN_ID_SIZE 8

Size of a Thread PAN ID (bytes)

OT_MESH_LOCAL_PREFIX_SIZE

 OT_MESH_LOCAL_PREFIX_SIZE OT_IP6_PREFIX_SIZE

Size of the Mesh Local Prefix (bytes)

OT_NETWORK_KEY_SIZE

 OT_NETWORK_KEY_SIZE 16

Size of the Thread Network Key (bytes)

OT_NETWORK_NAME_MAX_SIZE

 OT_NETWORK_NAME_MAX_SIZE 16

Maximum size of the Thread Network Name field (bytes)

OT_OPERATIONAL_DATASET_MAX_LENGTH

 OT_OPERATIONAL_DATASET_MAX_LENGTH 254

Maximum length of Operational Dataset in bytes.

OT_PSKC_MAX_SIZE

 OT_PSKC_MAX_SIZE 16

Maximum size of the PSKc (bytes)

Resources

OpenThread API Reference topics originate from the source code, available on GitHub. For more information, or to contribute to our documentation, refer to Resources.