IPv6

This module includes functions that control IPv6 communication.

Summary

Enumerations

otNetifInterfaceId{
  OT_NETIF_INTERFACE_ID_HOST = -1,
  OT_NETIF_INTERFACE_ID_THREAD = 1
}
enum
This enumeration represents the list of allowable values for an InterfaceId.

Typedefs

otIp6Address typedef
struct otIp6Address
This structure represents an IPv6 address.
otIp6AddressCallback)(const otIp6Address *aAddress, uint8_t aPrefixLength, bool aIsAdded, void *aContext) typedef
void(*
This function pointer is called when an internal IPv6 address is added or removed.
otIp6Prefix typedef
struct otIp6Prefix
This structure represents an IPv6 prefix.
otIp6ReceiveCallback)(otMessage *aMessage, void *aContext) typedef
void(*
This function pointer is called when an IPv6 datagram is received.
otIp6SlaacPrefixFilter)(otInstance *aInstance, const otIp6Prefix *aPrefix) typedef
bool(*
This function pointer allows user to filter prefixes and not allow an SLAAC address based on a prefix to be added.
otMessageInfo typedef
struct otMessageInfo
This structure represents the local and peer IPv6 socket addresses.
otNetifAddress typedef
This structure represents an IPv6 network interface unicast address.
otNetifInterfaceId typedef
This enumeration represents the list of allowable values for an InterfaceId.
otNetifMulticastAddress typedef
This structure represents an IPv6 network interface multicast address.
otSockAddr typedef
struct otSockAddr
This structure represents an IPv6 socket address.

Variables

OT_TOOL_PACKED_END

Functions

otIp6AddUnicastAddress(otInstance *aInstance, const otNetifAddress *aAddress)
Add a Network Interface Address to the Thread interface.
otIp6AddUnsecurePort(otInstance *aInstance, uint16_t aPort)
This function adds a port to the allowed unsecured port list.
otIp6AddressFromString(const char *aString, otIp6Address *aAddress)
Convert a human-readable IPv6 address string into a binary representation.
otIp6GetMulticastAddresses(otInstance *aInstance)
Get the list of IPv6 multicast addresses subscribed to the Thread interface.
otIp6GetUnicastAddresses(otInstance *aInstance)
Get the list of IPv6 addresses assigned to the Thread interface.
otIp6GetUnsecurePorts(otInstance *aInstance, uint8_t *aNumEntries)
const uint16_t *
This function returns a pointer to the unsecure port list.
otIp6IsAddressEqual(const otIp6Address *aFirst, const otIp6Address *aSecond)
OTAPI bool OTCALL
Test if two IPv6 addresses are the same.
otIp6IsAddressUnspecified(const otIp6Address *aAddress)
bool
This function indicates whether or not a given IPv6 address is the Unspecified Address.
otIp6IsEnabled(otInstance *aInstance)
OTAPI bool OTCALL
This function indicates whether or not the IPv6 interface is up.
otIp6IsMulticastPromiscuousEnabled(otInstance *aInstance)
bool
Check if multicast promiscuous mode is enabled on the Thread interface.
otIp6IsReceiveFilterEnabled(otInstance *aInstance)
bool
This function indicates whether or not Thread control traffic is filtered out when delivering IPv6 datagrams via the callback specified in otIp6SetReceiveCallback().
otIp6IsSlaacEnabled(otInstance *aInstance)
bool
This function indicates whether the SLAAC module is enabled or not.
otIp6NewMessage(otInstance *aInstance, const otMessageSettings *aSettings)
Allocate a new message buffer for sending an IPv6 message.
otIp6NewMessageFromBuffer(otInstance *aInstance, const uint8_t *aData, uint16_t aDataLength, const otMessageSettings *aSettings)
Allocate a new message buffer and write the IPv6 datagram to the message buffer for sending an IPv6 message.
otIp6PrefixMatch(const otIp6Address *aFirst, const otIp6Address *aSecond)
OTAPI uint8_t OTCALL
This function returns the prefix match length (bits) for two IPv6 addresses.
otIp6RemoveAllUnsecurePorts(otInstance *aInstance)
void
This function removes all ports from the allowed unsecure port list.
otIp6RemoveUnicastAddress(otInstance *aInstance, const otIp6Address *aAddress)
Remove a Network Interface Address from the Thread interface.
otIp6RemoveUnsecurePort(otInstance *aInstance, uint16_t aPort)
This function removes a port from the allowed unsecure port list.
otIp6SelectSourceAddress(otInstance *aInstance, otMessageInfo *aMessageInfo)
This function perform OpenThread source address selection.
otIp6Send(otInstance *aInstance, otMessage *aMessage)
This function sends an IPv6 datagram via the Thread interface.
otIp6SetAddressCallback(otInstance *aInstance, otIp6AddressCallback aCallback, void *aCallbackContext)
void
This function registers a callback to notify internal IPv6 address changes.
otIp6SetEnabled(otInstance *aInstance, bool aEnabled)
This function brings up/down the IPv6 interface.
otIp6SetMulticastPromiscuousEnabled(otInstance *aInstance, bool aEnabled)
void
Enable multicast promiscuous mode on the Thread interface.
otIp6SetReceiveCallback(otInstance *aInstance, otIp6ReceiveCallback aCallback, void *aCallbackContext)
void
This function registers a callback to provide received IPv6 datagrams.
otIp6SetReceiveFilterEnabled(otInstance *aInstance, bool aEnabled)
void
This function sets whether or not Thread control traffic is filtered out when delivering IPv6 datagrams via the callback specified in otIp6SetReceiveCallback().
otIp6SetSlaacEnabled(otInstance *aInstance, bool aEnabled)
void
This function enables/disables the SLAAC module.
otIp6SetSlaacPrefixFilter(otInstance *aInstance, otIp6SlaacPrefixFilter aFilter)
void
This function sets the SLAAC module filter handler.
otIp6SubscribeMulticastAddress(otInstance *aInstance, const otIp6Address *aAddress)
Subscribe the Thread interface to a Network Interface Multicast Address.
otIp6UnsubscribeMulticastAddress(otInstance *aInstance, const otIp6Address *aAddress)
Unsubscribe the Thread interface to a Network Interface Multicast Address.

Structs

otIp6Address

This structure represents an IPv6 address.

otIp6Prefix

This structure represents an IPv6 prefix.

otMessageInfo

This structure represents the local and peer IPv6 socket addresses.

otNetifAddress

This structure represents an IPv6 network interface unicast address.

otNetifMulticastAddress

This structure represents an IPv6 network interface multicast address.

otSockAddr

This structure represents an IPv6 socket address.

Unions

otIp6Address::OT_TOOL_PACKED_FIELD

Enumerations

otNetifInterfaceId

 otNetifInterfaceId

This enumeration represents the list of allowable values for an InterfaceId.

Properties
OT_NETIF_INTERFACE_ID_HOST

The interface ID telling packets received by host side interfaces.

OT_NETIF_INTERFACE_ID_THREAD

The Thread Network interface ID.

Typedefs

otIp6Address

struct otIp6Address otIp6Address

This structure represents an IPv6 address.

otIp6AddressCallback

void(* otIp6AddressCallback)(const otIp6Address *aAddress, uint8_t aPrefixLength, bool aIsAdded, void *aContext)

This function pointer is called when an internal IPv6 address is added or removed.

Details
Parameters
[in] aAddress
A pointer to the IPv6 address.
[in] aPrefixLength
The prefix length if aAddress is unicast address, and 128 for multicast address.
[in] aIsAdded
TRUE if the aAddress was added, FALSE if aAddress was removed.
[in] aContext
A pointer to application-specific context.

otIp6Prefix

struct otIp6Prefix otIp6Prefix

This structure represents an IPv6 prefix.

otIp6ReceiveCallback

void(* otIp6ReceiveCallback)(otMessage *aMessage, void *aContext)

This function pointer is called when an IPv6 datagram is received.

Details
Parameters
[in] aMessage
A pointer to the message buffer containing the received IPv6 datagram. This function transfers the ownership of the aMessage to the receiver of the callback. The message should be freed by the receiver of the callback after it is processed (
Parameters
[in] aContext
A pointer to application-specific context.
See also:
otMessageFree).

otIp6SlaacPrefixFilter

bool(* otIp6SlaacPrefixFilter)(otInstance *aInstance, const otIp6Prefix *aPrefix)

This function pointer allows user to filter prefixes and not allow an SLAAC address based on a prefix to be added.

otIp6SetSlaacPrefixFilter() can be used to set the filter handler. The filter handler is invoked by SLAAC module when it is about to add a SLAAC address based on a prefix. Its boolean return value determines whether the address is filtered (not added) or not.

Details
Parameters
[in] aInstacne
A pointer to an OpenThread instance.
[in] aPrefix
A pointer to prefix for which SLAAC address is about to be added.
Return Values
TRUE
Indicates that the SLAAC address based on the prefix should be filtered and NOT added.
FALSE
Indicates that the SLAAC address based on the prefix should be added.

otMessageInfo

struct otMessageInfo otMessageInfo

This structure represents the local and peer IPv6 socket addresses.

otNetifAddress

struct otNetifAddress otNetifAddress

This structure represents an IPv6 network interface unicast address.

otNetifInterfaceId

enum otNetifInterfaceId otNetifInterfaceId

This enumeration represents the list of allowable values for an InterfaceId.

otNetifMulticastAddress

struct otNetifMulticastAddress otNetifMulticastAddress

This structure represents an IPv6 network interface multicast address.

otSockAddr

struct otSockAddr otSockAddr

This structure represents an IPv6 socket address.

Variables

OT_TOOL_PACKED_END

OT_TOOL_PACKED_BEGIN struct otIp6Address OT_TOOL_PACKED_END

Functions

otIp6AddUnicastAddress

OTAPI otError OTCALL otIp6AddUnicastAddress(
  otInstance *aInstance,
  const otNetifAddress *aAddress
)

Add a Network Interface Address to the Thread interface.

The passed-in instance aAddress is copied by the Thread interface. The Thread interface only supports a fixed number of externally added unicast addresses. See OPENTHREAD_CONFIG_MAX_EXT_IP_ADDRS.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
[in] aAddress
A pointer to a Network Interface Address.
Return Values
OT_ERROR_NONE
Successfully added (or updated) the Network Interface Address.
OT_ERROR_INVALID_ARGS
The IP Address indicated by aAddress is an internal address.
OT_ERROR_NO_BUFS
The Network Interface is already storing the maximum allowed external addresses.

otIp6AddUnsecurePort

otError otIp6AddUnsecurePort(
  otInstance *aInstance,
  uint16_t aPort
)

This function adds a port to the allowed unsecured port list.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
[in] aPort
The port value.
Return Values
OT_ERROR_NONE
The port was successfully added to the allowed unsecure port list.
OT_ERROR_NO_BUFS
The unsecure port list is full.

otIp6AddressFromString

OTAPI otError OTCALL otIp6AddressFromString(
  const char *aString,
  otIp6Address *aAddress
)

Convert a human-readable IPv6 address string into a binary representation.

Details
Parameters
[in] aString
A pointer to a NULL-terminated string.
[out] aAddress
A pointer to an IPv6 address.
Return Values
OT_ERROR_NONE
Successfully parsed the string.
OT_ERROR_INVALID_ARGS
Failed to parse the string.

otIp6GetMulticastAddresses

const otNetifMulticastAddress * otIp6GetMulticastAddresses(
  otInstance *aInstance
)

Get the list of IPv6 multicast addresses subscribed to the Thread interface.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
Returns
A pointer to the first Network Interface Multicast Address.

otIp6GetUnicastAddresses

OTAPI const otNetifAddress *OTCALL otIp6GetUnicastAddresses(
  otInstance *aInstance
)

Get the list of IPv6 addresses assigned to the Thread interface.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
Returns
A pointer to the first Network Interface Address.

otIp6GetUnsecurePorts

const uint16_t * otIp6GetUnsecurePorts(
  otInstance *aInstance,
  uint8_t *aNumEntries
)

This function returns a pointer to the unsecure port list.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
[out] aNumEntries
The number of entries in the list.
Returns
A pointer to the unsecure port list.

otIp6IsAddressEqual

OTAPI bool OTCALL otIp6IsAddressEqual(
  const otIp6Address *aFirst,
  const otIp6Address *aSecond
)

Test if two IPv6 addresses are the same.

Details
Parameters
[in] aFirst
A pointer to the first IPv6 address to compare.
[in] aSecond
A pointer to the second IPv6 address to compare.
Return Values
TRUE
The two IPv6 addresses are the same.
FALSE
The two IPv6 addresses are not the same.

otIp6IsAddressUnspecified

bool otIp6IsAddressUnspecified(
  const otIp6Address *aAddress
)

This function indicates whether or not a given IPv6 address is the Unspecified Address.

Details
Parameters
[in] aAddress
A pointer to an IPv6 address.
Return Values
TRUE
If the IPv6 address is the Unspecified Address.
FALSE
If the IPv6 address is not the Unspecified Address.

otIp6IsEnabled

OTAPI bool OTCALL otIp6IsEnabled(
  otInstance *aInstance
)

This function indicates whether or not the IPv6 interface is up.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
Return Values
TRUE
The IPv6 interface is enabled.
FALSE
The IPv6 interface is disabled.

otIp6IsMulticastPromiscuousEnabled

bool otIp6IsMulticastPromiscuousEnabled(
  otInstance *aInstance
)

Check if multicast promiscuous mode is enabled on the Thread interface.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
See also:
otIp6SetMulticastPromiscuousEnabled

otIp6IsReceiveFilterEnabled

bool otIp6IsReceiveFilterEnabled(
  otInstance *aInstance
)

This function indicates whether or not Thread control traffic is filtered out when delivering IPv6 datagrams via the callback specified in otIp6SetReceiveCallback().

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
Returns
TRUE if Thread control traffic is filtered out, FALSE otherwise.
See also:
otIp6SetReceiveCallback
otIp6SetReceiveFilterEnabled

otIp6IsSlaacEnabled

bool otIp6IsSlaacEnabled(
  otInstance *aInstance
)

This function indicates whether the SLAAC module is enabled or not.

This function requires the build-time feature OPENTHREAD_CONFIG_ENABLE_SLAAC to be enabled.

Details
Return Values
TRUE
SLAAC module is enabled.
FALSE
SLAAC module is disabled.

otIp6NewMessage

otMessage * otIp6NewMessage(
  otInstance *aInstance,
  const otMessageSettings *aSettings
)

Allocate a new message buffer for sending an IPv6 message.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
[in] aSettings
A pointer to the message settings or NULL to set default settings.
Returns
A pointer to the message buffer or NULL if no message buffers are available or parameters are invalid.
See also:
otMessageFree

otIp6NewMessageFromBuffer

otMessage * otIp6NewMessageFromBuffer(
  otInstance *aInstance,
  const uint8_t *aData,
  uint16_t aDataLength,
  const otMessageSettings *aSettings
)

Allocate a new message buffer and write the IPv6 datagram to the message buffer for sending an IPv6 message.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
[in] aData
A pointer to the IPv6 datagram buffer.
[in] aDataLength
The size of the IPv6 datagram buffer pointed by aData.
[in] aSettings
A pointer to the message settings or NULL to set default settings.
Returns
A pointer to the message or NULL if malformed IPv6 header or insufficient message buffers are available.
See also:
otMessageFree

otIp6PrefixMatch

OTAPI uint8_t OTCALL otIp6PrefixMatch(
  const otIp6Address *aFirst,
  const otIp6Address *aSecond
)

This function returns the prefix match length (bits) for two IPv6 addresses.

Details
Parameters
[in] aFirst
A pointer to the first IPv6 address.
[in] aSecond
A pointer to the second IPv6 address.
Returns
The prefix match length in bits.

otIp6RemoveAllUnsecurePorts

void otIp6RemoveAllUnsecurePorts(
  otInstance *aInstance
)

This function removes all ports from the allowed unsecure port list.

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

otIp6RemoveUnicastAddress

OTAPI otError OTCALL otIp6RemoveUnicastAddress(
  otInstance *aInstance,
  const otIp6Address *aAddress
)

Remove a Network Interface Address from the Thread interface.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
[in] aAddress
A pointer to an IP Address.
Return Values
OT_ERROR_NONE
Successfully removed the Network Interface Address.
OT_ERROR_INVALID_ARGS
The IP Address indicated by aAddress is an internal address.
OT_ERROR_NOT_FOUND
The IP Address indicated by aAddress was not found.

otIp6RemoveUnsecurePort

otError otIp6RemoveUnsecurePort(
  otInstance *aInstance,
  uint16_t aPort
)

This function removes a port from the allowed unsecure port list.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
[in] aPort
The port value.
Return Values
OT_ERROR_NONE
The port was successfully removed from the allowed unsecure port list.
OT_ERROR_NOT_FOUND
The port was not found in the unsecure port list.

otIp6SelectSourceAddress

otError otIp6SelectSourceAddress(
  otInstance *aInstance,
  otMessageInfo *aMessageInfo
)

This function perform OpenThread source address selection.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
[in,out] aMessageInfo
A pointer to the message information.
Return Values
OT_ERROR_NONE
Found a source address and is filled into mSockAddr of aMessageInfo.
OT_ERROR_NOT_FOUND
No source address was found and aMessageInfo is unchanged.

otIp6Send

otError otIp6Send(
  otInstance *aInstance,
  otMessage *aMessage
)

This function sends an IPv6 datagram via the Thread interface.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
[in] aMessage
A pointer to the message buffer containing the IPv6 datagram.

otIp6SetAddressCallback

void otIp6SetAddressCallback(
  otInstance *aInstance,
  otIp6AddressCallback aCallback,
  void *aCallbackContext
)

This function registers a callback to notify internal IPv6 address changes.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
[in] aCallback
A pointer to a function that is called when an internal IPv6 address is added or removed. NULL to disable the callback.
[in] aCallbackContext
A pointer to application-specific context.

otIp6SetEnabled

OTAPI otError OTCALL otIp6SetEnabled(
  otInstance *aInstance,
  bool aEnabled
)

This function brings up/down the IPv6 interface.

Call this function to enable/disable IPv6 communication.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
[in] aEnabled
TRUE to enable IPv6, FALSE otherwise.
Return Values
OT_ERROR_NONE
Successfully brought the IPv6 interface up/down.
OT_ERROR_INVALID_STATE
IPv6 interface is not available since device is operating in raw-link mode (applicable only when OPENTHREAD_ENABLE_RAW_LINK_API feature is enabled).

otIp6SetMulticastPromiscuousEnabled

void otIp6SetMulticastPromiscuousEnabled(
  otInstance *aInstance,
  bool aEnabled
)

Enable multicast promiscuous mode on the Thread interface.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
[in] aEnabled
TRUE to enable Multicast Promiscuous mode, FALSE otherwise.
See also:
otIp6IsMulticastPromiscuousEnabled

otIp6SetReceiveCallback

void otIp6SetReceiveCallback(
  otInstance *aInstance,
  otIp6ReceiveCallback aCallback,
  void *aCallbackContext
)

This function registers a callback to provide received IPv6 datagrams.

By default, this callback does not pass Thread control traffic. See otIp6SetReceiveFilterEnabled() to change the Thread control traffic filter setting.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
[in] aCallback
A pointer to a function that is called when an IPv6 datagram is received or NULL to disable the callback.
[in] aCallbackContext
A pointer to application-specific context.
See also:
otIp6IsReceiveFilterEnabled
otIp6SetReceiveFilterEnabled

otIp6SetReceiveFilterEnabled

void otIp6SetReceiveFilterEnabled(
  otInstance *aInstance,
  bool aEnabled
)

This function sets whether or not Thread control traffic is filtered out when delivering IPv6 datagrams via the callback specified in otIp6SetReceiveCallback().

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
[in] aEnabled
TRUE if Thread control traffic is filtered out, FALSE otherwise.
See also:
otIp6SetReceiveCallback
otIsReceiveIp6FilterEnabled

otIp6SetSlaacEnabled

void otIp6SetSlaacEnabled(
  otInstance *aInstance,
  bool aEnabled
)

This function enables/disables the SLAAC module.

This function requires the build-time feature OPENTHREAD_CONFIG_ENABLE_SLAAC to be enabled.

When SLAAC module is enabled, SLAAC addresses (based on on-mesh prefixes in Network Data) are added to the interface. When SLAAC module is disabled any previously added SLAAC address is removed.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
[in] aEnabled
TRUE to enable, FALSE to disable.

otIp6SetSlaacPrefixFilter

void otIp6SetSlaacPrefixFilter(
  otInstance *aInstance,
  otIp6SlaacPrefixFilter aFilter
)

This function sets the SLAAC module filter handler.

This function requires the build-time feature OPENTHREAD_CONFIG_ENABLE_SLAAC to be enabled.

The filter handler is called by SLAAC module when it is about to add a SLAAC address based on a prefix to decide whether the address should be added or not.

A NULL filter handler disables filtering and allows all SLAAC addresses to be added.

If this function is not called, the default filter used by SLAAC module will be NULL (filtering is disabled).

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
[in] aFilter
A pointer to SLAAC prefix filter handler, or NULL to disable filtering.

otIp6SubscribeMulticastAddress

otError otIp6SubscribeMulticastAddress(
  otInstance *aInstance,
  const otIp6Address *aAddress
)

Subscribe the Thread interface to a Network Interface Multicast Address.

The passed in instance aAddress will be copied by the Thread interface. The Thread interface only supports a fixed number of externally added multicast addresses. See OPENTHREAD_CONFIG_MAX_EXT_MULTICAST_IP_ADDRS.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
[in] aAddress
A pointer to an IP Address.
Return Values
OT_ERROR_NONE
Successfully subscribed to the Network Interface Multicast Address.
OT_ERROR_ALREADY
The multicast address is already subscribed.
OT_ERROR_INVALID_ARGS
The IP Address indicated by aAddress is invalid address.
OT_ERROR_INVALID_STATE
The Network Interface is not up.
OT_ERROR_NO_BUFS
The Network Interface is already storing the maximum allowed external multicast addresses.

otIp6UnsubscribeMulticastAddress

otError otIp6UnsubscribeMulticastAddress(
  otInstance *aInstance,
  const otIp6Address *aAddress
)

Unsubscribe the Thread interface to a Network Interface Multicast Address.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
[in] aAddress
A pointer to an IP Address.
Return Values
OT_ERROR_NONE
Successfully unsubscribed to the Network Interface Multicast Address.
OT_ERROR_INVALID_ARGS
The IP Address indicated by aAddress is an internal address.
OT_ERROR_NOT_FOUND
The IP Address indicated by aAddress was not found.

Macros

OT_IP6_ADDRESS_SIZE

 OT_IP6_ADDRESS_SIZE 16

Size of an IPv6 address (bytes)

OT_IP6_IID_SIZE

 OT_IP6_IID_SIZE 8

Size of an IPv6 Interface Identifier (bytes)

OT_IP6_PREFIX_SIZE

 OT_IP6_PREFIX_SIZE 8

Size of an IPv6 prefix (bytes)