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 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

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
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
Enumerator
EMBER_EXTERNAL_ROUTE_PREFERENCE_MASK
EMBER_EXTERNAL_ROUTE_HIGH_PREFERENCE
EMBER_EXTERNAL_ROUTE_MEDIUM_PREFERENCE
EMBER_EXTERNAL_ROUTE_LOW_PREFERENCE
Enumerator
REALM_SCOPE
LINK_SCOPE
GLOBAL_SCOPE

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