IPv6 Addressing Utilities.

Data Structures
struct	EmberDnsResponse
	Structure for returning information from a DNS lookup. A structure is used to make it easier to add additional values.

Macros
#define	EMBER_MAX_IPV6_ADDRESS_COUNT 10
	The maximum number of IPv6 addresses configured for the device. See emberGetLocalIpAddress .

#define	EMBER_MAX_IPV6_GLOBAL_ADDRESS_COUNT ( EMBER_MAX_IPV6_ADDRESS_COUNT - 2)

#define	EMBER_MAX_IPV6_EXTERNAL_ROUTE_COUNT ( EMBER_MAX_IPV6_ADDRESS_COUNT - 2)

#define	EMBER_MAX_LIFETIME_DELAY_SEC (( HALF_MAX_INT32U_VALUE - 1) / 1000)
	We enforce this limit to avoid overflow when converting lifetimes from seconds to milliseconds.

#define	EMBER_MIN_PREFERRED_LIFETIME_SEC 1800
	There should be at least half an hour of preferred lifetime remaining to advertise a DHCP server.

#define	EMBER_MIN_VALID_LIFETIME_SEC 60
	Renew when we are down to one minute of valid lifetime.

#define	EMBER_MAX_DNS_NAME_LENGTH 128
	The maximum length of a domain name that may be passed to emberDnsLookup() .

#define	EMBER_MAX_DNS_QUERY_APP_DATA_LENGTH 64
	The maximum number of bytes of application data that may be passed to emberDnsLookup() .

Typedefs
typedef uint16_t	EmberBorderRouterTlvFlag

typedef uint8_t	EmberDefaultRouteTlvFlag

typedef uint8_t	LocalServerFlag

typedef void(*	EmberDnsResponseHandler ) ( EmberDnsLookupStatus status, const uint8_t domainName, uint8_t domainNameLength, const EmberDnsResponse response, void *applicationData, uint16_t applicationDataLength)
	Type definition for callback handlers for DNS responses.

Enumerations
enum	EmberLocalAddressScope { REALM_SCOPE = 0, LINK_SCOPE = 1, GLOBAL_SCOPE = 2 }

enum	EmberBorderRouterTlvFlag_e { EMBER_BORDER_ROUTER_DOMAIN_PREFIX_FLAG = 0x0040, EMBER_BORDER_ROUTER_ND_DNS_FLAG = 0x0080, EMBER_BORDER_ROUTER_ON_MESH_FLAG = 0x0100, EMBER_BORDER_ROUTER_DEFAULT_ROUTE_FLAG = 0x0200, EMBER_BORDER_ROUTER_CONFIGURE_FLAG = 0x0400, EMBER_BORDER_ROUTER_DHCP_FLAG = 0x0800, EMBER_BORDER_ROUTER_SLAAC_FLAG = 0x1000, EMBER_BORDER_ROUTER_PREFERRED_FLAG = 0x2000, EMBER_BORDER_ROUTER_PREFERENCE_MASK = 0xC000, EMBER_BORDER_ROUTER_HIGH_PREFERENCE = 0x4000, EMBER_BORDER_ROUTER_MEDIUM_PREFERENCE = 0x0000, EMBER_BORDER_ROUTER_LOW_PREFERENCE = 0xC000 }
	Border router flags (see Thread spec chapter 5 for more information)

enum	EmberExternalRouteTlvFlag_e { EMBER_EXTERNAL_ROUTE_PREFERENCE_MASK = 0xC0, EMBER_EXTERNAL_ROUTE_HIGH_PREFERENCE = 0x40, EMBER_EXTERNAL_ROUTE_MEDIUM_PREFERENCE = 0x00, EMBER_EXTERNAL_ROUTE_LOW_PREFERENCE = 0xC0 }
	External route router flags (see Thread spec chapter 5 for more information)

enum	LocalServerFlag_e { EMBER_DOMAIN_ADDRESS = 0, EMBER_GLOBAL_ADDRESS_AM_GATEWAY = 0x01, EMBER_GLOBAL_ADDRESS_AM_DHCP_SERVER = 0x02, EMBER_GLOBAL_ADDRESS_AM_SLAAC_SERVER = 0x04, EMBER_GLOBAL_ADDRESS_DHCP = 0x08, EMBER_GLOBAL_ADDRESS_SLAAC = 0x10, EMBER_GLOBAL_ADDRESS_CONFIGURED = 0x20, EMBER_GLOBAL_ADDRESS_REQUEST_SENT = 0x40, EMBER_GLOBAL_ADDRESS_REQUEST_FAILED = 0x80, EMBER_LOCAL_ADDRESS = 0xFF }
	Address configuration flags. These flags denote the properties of a Thread IPv6 address.

enum	EmberDnsLookupStatus { EMBER_DNS_LOOKUP_SUCCESS , EMBER_DNS_LOOKUP_NO_BORDER_ROUTER , EMBER_DNS_LOOKUP_NO_BORDER_ROUTER_RESPONSE , EMBER_DNS_LOOKUP_BORDER_ROUTER_RESPONSE_ERROR , EMBER_DNS_LOOKUP_NO_DNS_SERVER , EMBER_DNS_LOOKUP_NO_DNS_RESPONSE , EMBER_DNS_LOOKUP_NO_DNS_RESPONSE_ERROR , EMBER_DNS_LOOKUP_NO_ENTRY_FOR_NAME , EMBER_DNS_LOOKUP_NO_BUFFERS }
	Status values passed to DNS response handlers.

Functions
bool	emberGetLocalIpAddress (uint8_t index, EmberIpv6Address *address)
	This function fetches one of the device IPv6 addresses into the supplied pointer. Since there may be multiple addresses, an index argument between 0 and EMBER_MAX_IPV6_ADDRESS_COUNT must be supplied.

void	emberGetRoutingLocator (void)
	This function fetches the Thread Routing Locator (RLOC).

void	emberGetRoutingLocatorReturn (const EmberIpv6Address *rloc)
	This function provides the result of a call to emberGetRoutingLocator .

void	emberSetLocalNetworkData (const uint8_t *networkData, uint16_t length)
	Sets the Network Data that describes the local node's Border Router and server capabilities. This is passed a set of Network Data TLVs that may include Prefix, Has Route, Border Router, Service and Server TLVS.

void	emberSetLocalNetworkDataReturn ( EmberStatus status, uint16_t length)
	Provides the result of a call to ::emberSetServerNetworkData.

void	emberConfigureGateway ( EmberBorderRouterTlvFlag borderRouterFlags, bool isStable, const uint8_t *prefix, const uint8_t prefixLengthInBits, uint8_t domainId, uint32_t preferredLifetime, uint32_t validLifetime)
	This function configures the border router behavior, such as whether this device has a default route to the Internet, and whether it have a prefix that can be used by network devices to configure routable addresses.

void	emberConfigureGatewayReturn ( EmberStatus status)
	This function provides the result of a call to emberConfigureGateway .

void	emberSetNdData (const uint8_t *data, uint16_t length)

void	emberSetNdDataReturn ( EmberStatus status, uint16_t length)
	This function provides the result of a call to emberSetNdData .

void	emberConfigureExternalRoute ( EmberDefaultRouteTlvFlag extRouteFlags, bool isStable, const uint8_t *extRoutePrefix, uint8_t extRoutePrefixLengthInBits, uint8_t extRouteDomainId)
	This function defines an external route set, a route for a Thread network IPv6 packet that must traverse a border router and be forwarded to an exterior network.

void	emberConfigureExternalRouteReturn ( EmberStatus status)
	This function provides the result of a call to emberConfigureExternalRoute .

void	emberAddressConfigurationChangeHandler (const EmberIpv6Address *address, uint32_t preferredLifetime, uint32_t validLifetime, uint8_t addressFlags)
	This function is called when a new address is configured on the application.

void	emberGetGlobalPrefixes (void)
	This function returns the list of global prefixes that we know about.

void	emberGetGlobalPrefixReturn (uint8_t flags, bool isStable, const uint8_t *prefix, uint8_t prefixLengthInBits, uint8_t domainId, uint32_t preferredLifetime, uint32_t validLifetime)
	This function provides the result of a call to ::emberGetGlobalPrefix.

void	emberDhcpServerChangeHandler (const uint8_t *prefix, uint8_t prefixLengthInBits, bool available)
	This function is called when the stack knows about a new dhcp server or if a dhcp server has become unavailable.

void	emberRequestDhcpAddress (const uint8_t *prefix, uint8_t prefixLengthInBits)
	The application can choose to request a new DHCP address when it is informed via emberDhcpServerChangeHandler of an available DHCP server.

void	emberRequestDhcpAddressReturn ( EmberStatus status, const uint8_t *prefix, uint8_t prefixLengthInBits)
	This function provides the result of a call to emberRequestDhcpAddress .

void	emberSlaacServerChangeHandler (const uint8_t *prefix, uint8_t prefixLengthInBits, bool available)
	This function is called when the stack knows about a new SLAAC prefix or if a SLAAC server has become unavailable.

void	emberRequestSlaacAddress (const uint8_t *prefix, uint8_t prefixLengthInBits)
	The application can choose to request a new SLAAC address when it is informed via emberSlaacServerChangeHandler of an available SLAAC prefix.

void	emberRequestSlaacAddressReturn ( EmberStatus status, const uint8_t *prefix, uint8_t prefixLengthInBits)
	This function provides the result of a call to emberRequestSlaacAddress .

void	emberConfigureDefaultDomainPrefix (const uint8_t *prefix, uint8_t prefixLengthInBits)
	This function sets the domain prefix on a network. This is normally set by the commissioner for each device that is added on to the network, but this provides an alternate approach. This call is mandatory on at least one node on the network so that it can be communicated by the leader in the network data.

void	emberConfigureDefaultDomainPrefixReturn ( EmberStatus status, const uint8_t *prefix, uint8_t prefixLengthInBits)
	This function provides the result of a call to emberConfigureDefaultDomainPrefix .

void	emberBecomeBackboneRouter (void)
	This function requests the device to act in a backbone router role. Note that requisite backbone router support and a working backbone link are required, as per the Thread specification. If the stack determines that a valid border router with this support is not present, this call will fail, as indicated in emberBecomeBackboneRouterReturn . Additionally, on success, the primary or secondary role of the BBR is also indicated.

void	emberBecomeBackboneRouterReturn ( EmberStatus status, bool primary)
	This function provides the result of a call to emberConfigureDefaultDomainPrefix .

void	emberSetBbrDataset (uint32_t duaReregistrationDelayMs, uint32_t mlrTimeoutSec, uint32_t duaDelayMs)
	This function sets the properties of the active BBR dataset. Note that the leader must accept our changes to the network data, therefore the value returned in emberSetBbrDatasetReturn only indicates processing of the change request.

void	emberSetBbrDatasetReturn ( EmberStatus status)
	This function provides the result of a call to emberSetBbrDataset .

void	emberRequestMulticastListener (const EmberIpv6Address *multicastGroupAddress)
	Request a listener for an multicast group address of any scope. This call is only supported on a network that has a BBR, and therefore will not have any effect if a BBR is not present.

void	emberRequestMulticastListenerReturn ( EmberStatus status, const EmberIpv6Address *multicastGroupAddress)
	This function provides the result of a call to emberRequestMulticastListener . This call only indicates the status of the request.

void	emberMulticastListenerHandler (const EmberIpv6Address *multicastGroupAddress)
	This function is called when a multicast group listener registration was successful, indicating that multicast packets coming from non-Thread IPv6 hosts can be sent to this device by the (primary) BBR.

void	emberBackbonePrefixHandler (const uint8_t *prefix, uint8_t prefixLengthInBits, bool available)
	This function is called when the stack knows about a new backbone prefix or if a backbone server has become unavailable.

void	emberRequestDomainUniqueAddress (const uint8_t *prefix, uint8_t prefixLengthInBits)
	The application can choose to request a new DUA when it is informed via emberBackbonePrefixHandler of an available backbone router prefix.

void	emberRequestDomainUniqueAddressReturn ( EmberStatus status, const uint8_t *prefix, uint8_t prefixLengthInBits)
	This function provides the result of a call to emberRequestDomainUniqueAddress .

void	emberAddMeshDuaEntry (const EmberIpv6Address *dua)
	Create a copy of DUA table entries for mesh address resolution on the stack. Normally, we maintain the DUA table on the host for easy access to the backbone link. For certain address resolution decisions on the stack however, we need a separate copy.

void	emberAddMeshDuaEntryReturn ( EmberStatus status, const EmberIpv6Address *dua)
	This function provides the result of a call to emberAddMeshDuaEntry .

void	emberRemoveMeshDuaEntry (const EmberIpv6Address *dua)
	Remove a copy of the DUA table entry to aid mesh address resolution on the stack. Normally, we maintain the DUA table on the host for easy access to the backbone link. For certain address resolution decisions on the stack however, we need a separate copy.

void	emberRemoveMeshDuaEntryReturn ( EmberStatus status, const EmberIpv6Address *dua)
	This function provides the result of a call to emberRemoveMeshDuaEntry .

void	emberGetGlobalAddresses (const uint8_t *prefix, uint8_t prefixLengthInBits)
	This function returns the list of global addresses configured on this device.

void	emberGetGlobalAddressReturn (const EmberIpv6Address *address, uint32_t preferredLifetime, uint32_t validLifetime, uint8_t addressFlags)
	This function provides the result of a call to emberGetGlobalAddresses .

void	emberResignGlobalAddress (const EmberIpv6Address *address)
	This function resigns this IPv6 global address from this node. If this is a DHCP address, then the server is informed about it. If it is a SLAAC address, we remove it locally.

void	emberResignGlobalAddressReturn ( EmberStatus status)
	This function provides the result of a call to emberResignGlobalAddress() .

void	emberExternalRouteChangeHandler (const uint8_t *prefix, uint8_t prefixLengthInBits, bool available)
	This function is called when the stack knows about a border router that has an external route to a prefix.

void	emberNetworkDataChangeHandler (const uint8_t *networkData, uint16_t length)
	This function is called when the stack receives new Thread Network Data. The networkData argument may be NULL, in which case emberGetNetworkData can be used to obtain the new Thread Network Data.

void	emberGetNetworkData (uint8_t *networkDataBuffer, uint16_t bufferLength)
	This function is called to obtain the current Thread Network Data.

void	emberGetNetworkDataReturn ( EmberStatus status, uint8_t *networkData, uint16_t bufferLength)
	This function provides the result of a call to emberGetNetworkData .

EmberStatus	emberDnsLookup (const uint8_t domainName, uint8_t domainNameLength, const uint8_t prefix64, EmberDnsResponseHandler responseHandler, uint8_t *appData, uint16_t appDataLength)
	This function initiates a DNS name lookup.

Detailed Description

See network-management.h for source code.

Macro Definition Documentation

#define EMBER_MAX_DNS_NAME_LENGTH 128

#define EMBER_MAX_DNS_QUERY_APP_DATA_LENGTH 64

#define EMBER_MAX_IPV6_ADDRESS_COUNT 10

#define EMBER_MAX_IPV6_EXTERNAL_ROUTE_COUNT ( EMBER_MAX_IPV6_ADDRESS_COUNT - 2)

#define EMBER_MAX_IPV6_GLOBAL_ADDRESS_COUNT ( EMBER_MAX_IPV6_ADDRESS_COUNT - 2)

#define EMBER_MAX_LIFETIME_DELAY_SEC (( HALF_MAX_INT32U_VALUE - 1) / 1000)

#define EMBER_MIN_PREFERRED_LIFETIME_SEC 1800

#define EMBER_MIN_VALID_LIFETIME_SEC 60

Typedef Documentation

typedef uint16_t EmberBorderRouterTlvFlag

typedef uint8_t EmberDefaultRouteTlvFlag

typedef void(* EmberDnsResponseHandler) ( EmberDnsLookupStatus status, const uint8_t *domainName, uint8_t domainNameLength, const EmberDnsResponse *response, void *applicationData, uint16_t applicationDataLength)

Parameters

`status`	A EmberDnsLookupSatus indicating success or failure.
`domainName`	The name that was looked up.
`domainNameLength`	Length of domainName in bytes.
`response`	Response information, NULL if no response was received.
`applicationData`	Application data that was passed to emberDnsLookup .
`applicationDataLength`	Length of applicationData in bytes.

typedef uint8_t LocalServerFlag

Enumeration Type Documentation

enum EmberBorderRouterTlvFlag_e

Enumerator
EMBER_BORDER_ROUTER_DOMAIN_PREFIX_FLAG
EMBER_BORDER_ROUTER_ND_DNS_FLAG
EMBER_BORDER_ROUTER_ON_MESH_FLAG
EMBER_BORDER_ROUTER_DEFAULT_ROUTE_FLAG
EMBER_BORDER_ROUTER_CONFIGURE_FLAG
EMBER_BORDER_ROUTER_DHCP_FLAG
EMBER_BORDER_ROUTER_SLAAC_FLAG
EMBER_BORDER_ROUTER_PREFERRED_FLAG
EMBER_BORDER_ROUTER_PREFERENCE_MASK
EMBER_BORDER_ROUTER_HIGH_PREFERENCE
EMBER_BORDER_ROUTER_MEDIUM_PREFERENCE
EMBER_BORDER_ROUTER_LOW_PREFERENCE

enum EmberDnsLookupStatus

Enumerator
EMBER_DNS_LOOKUP_SUCCESS
EMBER_DNS_LOOKUP_NO_BORDER_ROUTER
EMBER_DNS_LOOKUP_NO_BORDER_ROUTER_RESPONSE
EMBER_DNS_LOOKUP_BORDER_ROUTER_RESPONSE_ERROR
EMBER_DNS_LOOKUP_NO_DNS_SERVER
EMBER_DNS_LOOKUP_NO_DNS_RESPONSE
EMBER_DNS_LOOKUP_NO_DNS_RESPONSE_ERROR
EMBER_DNS_LOOKUP_NO_ENTRY_FOR_NAME
EMBER_DNS_LOOKUP_NO_BUFFERS

enum EmberExternalRouteTlvFlag_e

Enumerator
EMBER_EXTERNAL_ROUTE_PREFERENCE_MASK
EMBER_EXTERNAL_ROUTE_HIGH_PREFERENCE
EMBER_EXTERNAL_ROUTE_MEDIUM_PREFERENCE
EMBER_EXTERNAL_ROUTE_LOW_PREFERENCE

enum EmberLocalAddressScope

Enumerator
REALM_SCOPE
LINK_SCOPE
GLOBAL_SCOPE

enum LocalServerFlag_e

The EMBER_GLOBAL_ADDRESS_AM_ flags are set for a border router that is supplying prefixes.

The rest of the EMBER_GLOBAL_ADDRESS_ flags are set for prefixes that have been administered on other devices.

EMBER_LOCAL_ADDRESS is supplied if this a Thread mesh-local or link-local IPv6 address. No other flags are set in this case.

Enumerator
EMBER_DOMAIN_ADDRESS
EMBER_GLOBAL_ADDRESS_AM_GATEWAY
EMBER_GLOBAL_ADDRESS_AM_DHCP_SERVER
EMBER_GLOBAL_ADDRESS_AM_SLAAC_SERVER
EMBER_GLOBAL_ADDRESS_DHCP
EMBER_GLOBAL_ADDRESS_SLAAC
EMBER_GLOBAL_ADDRESS_CONFIGURED
EMBER_GLOBAL_ADDRESS_REQUEST_SENT
EMBER_GLOBAL_ADDRESS_REQUEST_FAILED
EMBER_LOCAL_ADDRESS

Function Documentation

void emberAddMeshDuaEntry ( const EmberIpv6Address * dua )

Parameters

dua The DUA address of a node on our mesh

void emberAddMeshDuaEntryReturn	(	EmberStatus	`status,`
		const EmberIpv6Address *	`dua`
	)

Parameters

status EMBER_SUCCESS or EMBER_TABLE_FULL

void emberAddressConfigurationChangeHandler	(	const EmberIpv6Address *	`address,`
		uint32_t	`preferredLifetime,`
		uint32_t	`validLifetime,`
		uint8_t	`addressFlags`
	)

If addressFlags is EMBER_LOCAL_ADDRESS, it means that the address configured is a Thread-local address.

Otherwise, it means that the address assigned is a global address (DHCP or SLAAC).

In either case, if the valid lifetime is zero, then the address is no longer available.

Parameters

`address`	the address
`preferredLifetime`	the preferred lifetime of the address (in seconds)
`validLifetime`	the valid lifetime of the address (in seconds)
`addressFlags`	address configuration flags (see LocalServerFlag_e)

This function is called when a new address is configured on the application.

If addressFlags is EMBER_LOCAL_ADDRESS, it means that the address configured is a Thread-local address.

Otherwise, it means that the address assigned is a global address (DHCP or SLAAC).

In either case, if the valid lifetime is zero, then the address is no longer available.

Parameters

`address`	the address
`preferredLifetime`	the preferred lifetime of the address (in seconds)
`validLifetime`	the valid lifetime of the address (in seconds)
`addressFlags`	address configuration flags (see LocalServerFlag_e)

void emberBackbonePrefixHandler	(	const uint8_t *	`prefix,`
		uint8_t	`prefixLengthInBits,`
		bool	`available`
	)

"available" means we can configure a DUA address.

Parameters

`prefix`	DUA prefix
`prefixLengthInBits`	length in bits of the prefix
`available`	whether we can configure a DUA address

void emberBecomeBackboneRouter ( void )

void emberBecomeBackboneRouterReturn	(	EmberStatus	`status,`
		bool	`primary`
	)

Parameters

`status`	EMBER_SUCCESS or EMBER_INVALID_CALL
`primary`	true indicates that we are active in a primary BBR role.

void emberConfigureDefaultDomainPrefix	(	const uint8_t *	`prefix,`
		uint8_t	`prefixLengthInBits`
	)

Parameters

`prefix`	Default domain prefix
`prefixLengthInBits`	Length in bits of the prefix

void emberConfigureDefaultDomainPrefixReturn	(	EmberStatus	`status,`
		const uint8_t *	`prefix,`
		uint8_t	`prefixLengthInBits`
	)

Parameters

`status`	EMBER_SUCCESS or EMBER_BAD_ARGUMENT
`prefix`	Default domain prefix
`prefixLengthInBits`	Length in bits of the prefix

void emberConfigureExternalRoute	(	EmberDefaultRouteTlvFlag	`extRouteFlags,`
		bool	`isStable,`
		const uint8_t *	`extRoutePrefix,`
		uint8_t	`extRoutePrefixLengthInBits,`
		uint8_t	`extRouteDomainId`
	)

Also de-configures an external route prefix (if it exists), if the extRoutePrefix and extRoutePrefixLengthInBits arguments are specified, and externalRouteFlags equals 0xFF.

Parameters

`extRouteFlags`	-> See EmberDefaultRouteTlvFlag -> 0xFF to de-configure the specified route.
`isStable`	If true, the route is expected to be available for at least MIN_STABLE_LIFETIME (168) hours.
`extRoutePrefix`	Prefix for the route
`extRoutePrefixLengthInBits`	Prefix length in bits
`extRouteDomainId`	Domain ID

void emberConfigureExternalRouteReturn ( EmberStatus status )

This function provides the result of a call to emberConfigureExternalRoute .

void emberConfigureGateway	(	EmberBorderRouterTlvFlag	`borderRouterFlags,`
		bool	`isStable,`
		const uint8_t *	`prefix,`
		const uint8_t	`prefixLengthInBits,`
		uint8_t	`domainId,`
		uint32_t	`preferredLifetime,`
		uint32_t	`validLifetime`
	)

Also de-configures a border router prefix (if it exists), if the prefix and prefixLengthInBits are specified, and borderRouterFlags equals 0x00FF.

This triggers an address configuration change on the border router, and the application is informed of this by emberAddressConfigurationChangeHandler .

Note: If the application wants to manually configure an address and not have the stack create one, then it should pass in the entire IPv6 address (in bytes) for the prefix argument, with prefixLengthInBits as 128.

Examples:

SLAAC:

To configure a valid SLAAC border router, use: EMBER_BORDER_ROUTER_SLAAC_FLAG | EMBER_BORDER_ROUTER_DEFAULT_ROUTE_FLAG

The preference of the SLAAC prefix can be set using EMBER_BORDER_ROUTER_HIGH_PREFERENCE or EMBER_BORDER_ROUTER_LOW_PREFERENCE

NOTE: Preferred and valid lifetimes are ignored for SLAAC prefixes.

Configuring a SLAAC prefix will trigger emberAddressConfigurationChangeHandler on other nodes that may choose to configure a SLAAC address.

DHCP:

To configure a valid DHCP border router, use: EMBER_BORDER_ROUTER_DHCP_FLAG | EMBER_BORDER_ROUTER_DEFAULT_ROUTE_FLAG)

Note that this function only informs the network that this device is a DHCP server. The application is responsible for handling all messages send to the DHCP server port.

EMBER_BORDER_ROUTER_CONFIGURE_FLAG may be set if this border router is a DHCP server that supplies other configurationd data, such as the identity of DNS servers.

Configuring a DHCP prefix will trigger emberDhcpServerChangeHandler and other devices may choose to request a DHCP address by calling emberRequestDhcpAddress . If they get an address, they are informed via emberAddressConfigurationChangeHandler .

Parameters

`borderRouterFlags`	-> See EmberBorderRouterTlvFlag -> 0x00FF to de-configure the specified prefix.
`isStable`	If true, the border router that uses this prefix offers a route that is expected to be available for at least MIN_STABLE_LIFETIME (168) hours.
`prefix`	Prefix for the border router.
`prefixLengthInBits`	Prefix length in bits.
`domainId`	Domain ID.
`preferredLifetime`	Ignored; included for backward compatibility.
`validLifetime`	Ignored; included for backward compatibility.

void emberConfigureGatewayReturn ( EmberStatus status )

This function provides the result of a call to emberConfigureGateway .

void emberDhcpServerChangeHandler	(	const uint8_t *	`prefix,`
		uint8_t	`prefixLengthInBits,`
		bool	`available`
	)

"available" means the DHCP server can offer us an address if requested.

Parameters

`prefix`	dhcp server prefix
`prefixLengthInBits`	length in bits of the prefix
`available`	whether this dhcp server is available

This function is called when the stack knows about a new dhcp server or if a dhcp server has become unavailable.

"available" means the DHCP server can offer us an address if requested.

Parameters

`prefix`	dhcp server prefix
`prefixLengthInBits`	length in bits of the prefix
`available`	whether this dhcp server is available

EmberStatus emberDnsLookup	(	const uint8_t *	`domainName,`
		uint8_t	`domainNameLength,`
		const uint8_t *	`prefix64,`
		EmberDnsResponseHandler	`responseHandler,`
		uint8_t *	`appData,`
		uint16_t	`appDataLength`
	)

Parameters

`domainName`	The name to be looked up.
`domainNameLength`	Length of domainName in bytes.
`prefix64`	A 64-bit prefix that specifies the domain in which to perform the lookup. A NULL value will perform a lookup in all available domains.
`responseHandler`	Handler to which the response will be passed.
`applicationData`	Application data to be passed to responseHandler.
`applicationDataLength`	Length of applicationData in bytes.

void emberExternalRouteChangeHandler	(	const uint8_t *	`prefix,`
		uint8_t	`prefixLengthInBits,`
		bool	`available`
	)

Parameters

`prefix`	External route prefix
`prefixLengthInBits`	Length in bits of the prefix
`available`	Whether this external route is available.

This function is called when the stack knows about a border router that has an external route to a prefix.

Parameters

`prefix`	external route prefix
`prefixLengthInBits`	length in bits of the prefix
`available`	whether this external route is available.

void emberGetGlobalAddresses	(	const uint8_t *	`prefix,`
		uint8_t	`prefixLengthInBits`
	)

emberGetGlobalAddressReturn callbacks contain information about these global addresses.

Once all valid entries have been returned, an extra zeroed-out entry is returned to indicate completion.

Parameters

`prefix`	Address prefix
`prefixLengthInBits`	Length in bits of the prefix

void emberGetGlobalAddressReturn	(	const EmberIpv6Address *	`address,`
		uint32_t	`preferredLifetime,`
		uint32_t	`validLifetime,`
		uint8_t	`addressFlags`
	)

Parameters

`address`	IPv6 global address
`preferredLifetime`	Preferred lifetime (in seconds)
`validLifetime`	Valid lifetime (in seconds)
`addressFlags`	Address configuration flags (EMBER_GLOBAL_ADDRESS_*)

This function provides the result of a call to emberGetGlobalAddresses .

Parameters

`address`	IPv6 global address
`preferredLifetime`	Preferred lifetime (in seconds)
`validLifetime`	Valid lifetime (in seconds)
`addressFlags`	Address configuration flags (EMBER_GLOBAL_ADDRESS_*)

void emberGetGlobalPrefixes ( void )

emberGetGlobalPrefixReturn callbacks contain information about the border routers.

Once all valid entries have been returned, an extra zeroed-out entry is returned to indicate completion.

void emberGetGlobalPrefixReturn	(	uint8_t	`flags,`
		bool	`isStable,`
		const uint8_t *	`prefix,`
		uint8_t	`prefixLengthInBits,`
		uint8_t	`domainId,`
		uint32_t	`preferredLifetime,`
		uint32_t	`validLifetime`
	)

Parameters

`flags`	Please ignore this param, it is currently unused. (returns 0)
`isStable`	Stable or temporary prefix
`prefix`	Border router prefix
`prefixLengthInBits`	Prefix length in bits
`domainId`	Provisioning domain ID
`preferredLifetime`	Preferred lifetime (in seconds)
`validLifetime`	Valid lifetime (in seconds)

This function provides the result of a call to ::emberGetGlobalPrefix.

Parameters

`flags`	Please ignore this param, it is currently unused. (returns 0)
`isStable`	Stable or temporary prefix
`prefix`	Border router prefix
`prefixLengthInBits`	Prefix length in bits
`domainId`	Provisioning domain ID
`preferredLifetime`	Preferred lifetime (in seconds)
`validLifetime`	Valid lifetime (in seconds)

bool emberGetLocalIpAddress	(	uint8_t	`index,`
		EmberIpv6Address *	`address`
	)

Index 0 contains the mesh-local 64 address of the node. Index 1 contains the link-local 64 address of the node. Index 2 contains the domain-unique address of the node, if it exists. Index 3 and greater will return any global unicast addresses (GUAs) of this node.

Returns: false if no IPv6 address is stored at the given index.

void emberGetNetworkData	(	uint8_t *	`networkDataBuffer,`
		uint16_t	`bufferLength`
	)

Parameters

`networkDataBuffer`	Network Data will be copied to here
`bufferLength`	Length in bytes of the buffer

void emberGetNetworkDataReturn	(	EmberStatus	`status,`
		uint8_t *	`networkData,`
		uint16_t	`bufferLength`
	)

The status value is one of:

EMBER_SUCCESS
EMBER_NETWORK_DOWN
EMBER_BAD_ARGUMENT (the supplied buffer was too small)

Parameters

`status`
`networkData`	Location of the Network Data
`dataLength`	Length in bytes of the Network Data

This function provides the result of a call to emberGetNetworkData .

The status value is one of:

EMBER_SUCCESS
EMBER_NETWORK_DOWN
EMBER_BAD_ARGUMENT (the supplied buffer was too small)

Parameters

`status`
`networkData`	location of the Network Data
`dataLength`	length in bytes of the Network Data

void emberGetRoutingLocator ( void )

A Thread Routing Locator (RLOC) is an IPv6 address that identifies the location of a Thread interface within a Thread partition. Thread devices use RLOCs internally for communicating control traffic.

NOTE: Using RLOCs for application messaging is NOT recommended since device identifiers used to build these RLOC addresses may change at any time based on the current network state. Please note that message delivery is not guaranteed when an RLOC address is used.

It is recommended that application developers use emberGetLocalIpAddress .

void emberGetRoutingLocatorReturn ( const EmberIpv6Address * rloc )

Parameters

rloc The Routing Locator as a full IPv6 address.

This function provides the result of a call to emberGetRoutingLocator .

Parameters

rloc The Routing Locator as a full IPv6 address.

void emberMulticastListenerHandler ( const EmberIpv6Address * multicastGroupAddress )

The off-mesh multicasts are sent to the Thread network in MPL packets, via IPv6-in-IPv6 encapsulation.

On a BBR, this handler can be used to configure the multicast groups on the backbone link. The application must use MLDv2 to communicate to the wider IPv6 LAN/WAN about the groups it needs to listen to.

Parameters

multicastGroupAddress IPv6 address representing the multicast group

void emberNetworkDataChangeHandler	(	const uint8_t *	`networkData,`
		uint16_t	`length`
	)

Parameters

`networkData`	Network Data
`length`	Length in bytes of the Network Data

This function is called when the stack receives new Thread Network Data. The networkData argument may be NULL, in which case emberGetNetworkData can be used to obtain the new Thread Network Data.

Parameters

`networkData`	the Network Data
`length`	length in bytes of the Network Data

void emberRemoveMeshDuaEntry ( const EmberIpv6Address * dua )

Parameters

dua The DUA address of a node on our mesh

void emberRemoveMeshDuaEntryReturn	(	EmberStatus	`status,`
		const EmberIpv6Address *	`dua`
	)

Parameters

status EMBER_SUCCESS or EMBER_BAD_ARGUMENT

void emberRequestDhcpAddress	(	const uint8_t *	`prefix,`
		uint8_t	`prefixLengthInBits`
	)

The application can also call emberGetGlobalPrefixes to look for DHCP servers that it can request for an address.

When the address is obtained, the application is informed of this via emberAddressConfigurationChangeHandler .

Parameters

`prefix`	dhcp server prefix
`prefixLengthInBits`	length in bits of the prefix

void emberRequestDhcpAddressReturn	(	EmberStatus	`status,`
		const uint8_t *	`prefix,`
		uint8_t	`prefixLengthInBits`
	)

This call only indicates the status of the request (EMBER_ERR_FATAL if no DHCP server is found, and EMBER_SUCCESS otherwise). The assigned IPv6 address is returned via emberAddressConfigurationChangeHandler

Parameters

`status`	Status of DHCP Address Request
`prefix`	Prefix requested in emberRequestDhcpAddress
`prefixLengthInBits`	Prefix length in bits requested in emberRequestDhcpAddress

This function provides the result of a call to emberRequestDhcpAddress .

This call only indicates the status of the request (EMBER_ERR_FATAL if no DHCP server is found, and EMBER_SUCCESS otherwise). The assigned IPv6 address is returned via emberAddressConfigurationChangeHandler

Parameters

`status`	Status of DHCP Address Request
`prefix`	Prefix requested in emberRequestDhcpAddress
`prefixLengthInBits`	Prefix length in bits requested in emberRequestDhcpAddress

void emberRequestDomainUniqueAddress	(	const uint8_t *	`prefix,`
		uint8_t	`prefixLengthInBits`
	)

If the application wants to manually configure an address and not have the stack choose one, then it should pass in the entire IPv6 address (in bytes) for the prefix argument, with prefixLengthInBits as 128.

When the address is obtained, the application is informed of this via emberAddressConfigurationChangeHandler .

Parameters

`prefix`	DUA prefix
`prefixLengthInBits`	Length in bits of the prefix

void emberRequestDomainUniqueAddressReturn	(	EmberStatus	`status,`
		const uint8_t *	`prefix,`
		uint8_t	`prefixLengthInBits`
	)

This call only indicates the status of the request (EMBER_ERR_FATAL if no PBBR is found, and EMBER_SUCCESS otherwise). The assigned IPv6 address is returned via emberAddressConfigurationChangeHandler

Parameters

`status`	Status of DUA Request
`prefix`	Prefix requested in emberRequestDomainUniqueAddress
`prefixLengthInBits`	Prefix length in bits requested in emberRequestDomainUniqueAddress

void emberRequestMulticastListener ( const EmberIpv6Address * multicastGroupAddress )

Parameters

multicastGroupAddress IPv6 address representing the multicast group

void emberRequestMulticastListenerReturn	(	EmberStatus	`status,`
		const EmberIpv6Address *	`address`
	)

Parameters

`status`	Status of MLR Request
`multicastGroupAddress`	IPv6 address representing the multicast group

void emberRequestSlaacAddress	(	const uint8_t *	`prefix,`
		uint8_t	`prefixLengthInBits`
	)

The application can also call emberGetGlobalPrefixes to look for SLAAC prefixes that it can use to configure an address.

If the application wants to manually configure an address and not have the stack create one, then it should pass in the entire IPv6 address (in bytes) for the prefix argument, with prefixLengthInBits as 128.

When the address is obtained, the application is informed of this via emberAddressConfigurationChangeHandler .

Parameters

`prefix`	SLAAC prefix
`prefixLengthInBits`	Length in bits of the prefix

void emberRequestSlaacAddressReturn	(	EmberStatus	`status,`
		const uint8_t *	`prefix,`
		uint8_t	`prefixLengthInBits`
	)

This call only indicates the status of the request (EMBER_ERR_FATAL if no SLAAC server is found, and EMBER_SUCCESS otherwise). The assigned IPv6 address is returned via emberAddressConfigurationChangeHandler

Parameters

`status`	Status of SLAAC Address Request
`prefix`	Prefix requested in emberRequestSlaacAddress
`prefixLengthInBits`	Prefix length in bits requested in emberRequestSlaacAddress

This function provides the result of a call to emberRequestSlaacAddress .

This call only indicates the status of the request (EMBER_ERR_FATAL if no SLAAC server is found, and EMBER_SUCCESS otherwise). The assigned IPv6 address is returned via emberAddressConfigurationChangeHandler

Parameters

`status`	Status of SLAAC Address Request
`prefix`	Prefix requested in emberRequestSlaacAddress
`prefixLengthInBits`	Prefix length in bits requested in emberRequestSlaacAddress

void emberResignGlobalAddress ( const EmberIpv6Address * address )

void emberResignGlobalAddressReturn ( EmberStatus status )

This function provides the result of a call to emberResignGlobalAddress() .

void emberSetBbrDataset	(	uint32_t	`duaReregistrationDelayMs,`
		uint32_t	`mlrTimeoutSec,`
		uint32_t	`duaDelayMs`
	)

Parameters

`duaReregistrationDelayMs`	DUA re-registration delay in ms.
`mlrTimeoutSec`	MLR timeout in seconds
`duaDelayMs`	DUA jitter/delay in ms.

void emberSetBbrDatasetReturn ( EmberStatus status )

Parameters

status EMBER_SUCCESS

void emberSetLocalNetworkData	(	const uint8_t *	`networkData,`
		uint16_t	`length`
	)

The stack will set the correct local node ID into the TLVs.

This function is an alternative to the emberConfigureGateway emberConfigureExternalRoute functions that provides full access to Network Data configuration. A call to this function removes any previous configuration, including uses of emberConfigureGateway and emberConfigureExternalRoute .

Parameters

`networkData`	A pointer to a set of Thread Network Data TLVs that describe the local nodes Border Router and Server capabilities.
`length`	The number of bytes in the supplied network data.

void emberSetLocalNetworkDataReturn	(	EmberStatus	`status,`
		uint16_t	`length`
	)

Provides the result of a call to ::emberSetServerNetworkData.

void emberSetNdData	(	const uint8_t *	`data,`
		uint16_t	`length`
	)

void emberSetNdDataReturn	(	EmberStatus	`status,`
		uint16_t	`length`
	)

This function provides the result of a call to emberSetNdData .

void emberSlaacServerChangeHandler	(	const uint8_t *	`prefix,`
		uint8_t	`prefixLengthInBits,`
		bool	`available`
	)

"available" means we can configure a SLAAC address.

Parameters

`prefix`	SLAAC prefix
`prefixLengthInBits`	length in bits of the prefix
`available`	whether we can configure an address

This function is called when the stack knows about a new SLAAC prefix or if a SLAAC server has become unavailable.

"available" means we can configure a SLAAC address.

Parameters

`prefix`	SLAAC prefix
`prefixLengthInBits`	length in bits of the prefix
`available`	whether we can configure an address

IPv6 Thread Stack API Reference Thread Stack API Reference > | Network Utilities

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation

SLAAC:

NOTE: Preferred and valid lifetimes are ignored for SLAAC prefixes.

DHCP:

IPv6
Thread Stack API Reference Thread Stack API Reference > | Network Utilities