IPv6

This module includes functions that control IPv6 communication.

Summary

Enumerations
`Anonymous Enum 3{ OT_ADDRESS_ORIGIN_THREAD = 0, OT_ADDRESS_ORIGIN_SLAAC = 1, OT_ADDRESS_ORIGIN_DHCPV6 = 2, OT_ADDRESS_ORIGIN_MANUAL = 3 }`	enum IPv6 Address origins.
`Anonymous Enum 4{ OT_ECN_NOT_CAPABLE = 0x0, OT_ECN_CAPABLE_0 = 0x2, OT_ECN_CAPABLE_1 = 0x1, OT_ECN_MARKED = 0x3 }`	enum ECN statuses, represented as in the IP header.
`Anonymous Enum 5{ OT_IP6_PROTO_HOP_OPTS = 0, OT_IP6_PROTO_TCP = 6, OT_IP6_PROTO_UDP = 17, OT_IP6_PROTO_IP6 = 41, OT_IP6_PROTO_ROUTING = 43, OT_IP6_PROTO_FRAGMENT = 44, OT_IP6_PROTO_ICMP6 = 58, OT_IP6_PROTO_NONE = 59, OT_IP6_PROTO_DST_OPTS = 60 }`	enum Internet Protocol Numbers.

Typedefs
`otBorderRoutingCounters`	typedef `struct otBorderRoutingCounters` Represents the counters of packets forwarded via Border Routing.
`otIp6Address`	typedef `struct otIp6Address` Represents an IPv6 address.
`otIp6AddressCallback)(const otIp6AddressInfo aAddressInfo, bool aIsAdded, void aContext)`	typedef `void(*` Pointer is called when an internal IPv6 address is added or removed.
`otIp6AddressComponents`	typedef `struct otIp6AddressComponents` Represents the components of an IPv6 address.
`otIp6AddressInfo`	typedef `struct otIp6AddressInfo` Represents IPv6 address information.
`otIp6InterfaceIdentifier`	typedef `struct otIp6InterfaceIdentifier` Represents the Interface Identifier of an IPv6 address.
`otIp6NetworkPrefix`	typedef `struct otIp6NetworkPrefix` Represents the Network Prefix of an IPv6 address (most significant 64 bits of the address).
`otIp6Prefix`	typedef `struct otIp6Prefix` Represents an IPv6 prefix.
`otIp6ReceiveCallback)(otMessage aMessage, void aContext)`	typedef `void(*` Pointer is called when an IPv6 datagram is received.
`otIp6RegisterMulticastListenersCallback)(void aContext, otError aError, uint8_t aMlrStatus, const otIp6Address aFailedAddresses, uint8_t aFailedAddressNum)`	typedef `void(*` Pointer is called with results of `otIp6RegisterMulticastListeners`.
`otIp6SlaacPrefixFilter)(otInstance aInstance, const otIp6Prefix aPrefix)`	typedef `bool(*` Pointer allows user to filter prefixes and not allow an SLAAC address based on a prefix to be added.
`otMessageInfo`	typedef `struct otMessageInfo` Represents the local and peer IPv6 socket addresses.
`otNetifAddress`	typedef `struct otNetifAddress` Represents an IPv6 network interface unicast address.
`otNetifMulticastAddress`	typedef `struct otNetifMulticastAddress` Represents an IPv6 network interface multicast address.
`otPacketsAndBytes`	typedef `struct otPacketsAndBytes` Represents the counters for packets and bytes.
`otSockAddr`	typedef `struct otSockAddr` Represents an IPv6 socket address.

Variables
`OT_TOOL_PACKED_END`	`OT_TOOL_PACKED_BEGIN struct otIp6InterfaceIdentifier`

Functions
`otIp6AddUnicastAddress(otInstance aInstance, const otNetifAddress aAddress)`	`otError` Adds a Network Interface Address to the Thread interface.
`otIp6AddUnsecurePort(otInstance *aInstance, uint16_t aPort)`	`otError` Adds a port to the allowed unsecured port list.
`otIp6AddressFromString(const char aString, otIp6Address aAddress)`	`otError` Converts a human-readable IPv6 address string into a binary representation.
`otIp6AddressToString(const otIp6Address aAddress, char aBuffer, uint16_t aSize)`	`void` Converts a given IPv6 address to a human-readable string.
`otIp6ArePrefixesEqual(const otIp6Prefix aFirst, const otIp6Prefix aSecond)`	`bool` Test if two IPv6 prefixes are the same.
`otIp6GetBorderRoutingCounters(otInstance *aInstance)`	`const otBorderRoutingCounters *` Gets the Border Routing counters.
`otIp6GetMulticastAddresses(otInstance *aInstance)`	`const otNetifMulticastAddress *` Gets the list of IPv6 multicast addresses subscribed to the Thread interface.
`otIp6GetPrefix(const otIp6Address aAddress, uint8_t aLength, otIp6Prefix aPrefix)`	`void` Gets a prefix with `aLength` from `aAddress`.
`otIp6GetUnicastAddresses(otInstance *aInstance)`	`const otNetifAddress *` Gets the list of IPv6 addresses assigned to the Thread interface.
`otIp6GetUnsecurePorts(otInstance aInstance, uint8_t aNumEntries)`	`const uint16_t *` Returns a pointer to the unsecure port list.
`otIp6HasUnicastAddress(otInstance aInstance, const otIp6Address aAddress)`	`bool` Indicates whether or not a unicast IPv6 address is assigned to the Thread interface.
`otIp6IsAddressEqual(const otIp6Address aFirst, const otIp6Address aSecond)`	`bool` Test if two IPv6 addresses are the same.
`otIp6IsAddressUnspecified(const otIp6Address *aAddress)`	`bool` Indicates whether or not a given IPv6 address is the Unspecified Address.
`otIp6IsEnabled(otInstance *aInstance)`	`bool` Indicates whether or not the IPv6 interface is up.
`otIp6IsReceiveFilterEnabled(otInstance *aInstance)`	`bool` Indicates whether or not Thread control traffic is filtered out when delivering IPv6 datagrams via the callback specified in otIp6SetReceiveCallback().
`otIp6IsSlaacEnabled(otInstance *aInstance)`	`bool` Indicates whether the SLAAC module is enabled or not.
`otIp6NewMessage(otInstance aInstance, const otMessageSettings aSettings)`	`otMessage *` Allocate a new message buffer for sending an IPv6 message.
`otIp6NewMessageFromBuffer(otInstance aInstance, const uint8_t aData, uint16_t aDataLength, const otMessageSettings *aSettings)`	`otMessage *` Allocate a new message buffer and write the IPv6 datagram to the message buffer for sending an IPv6 message.
`otIp6PrefixFromString(const char aString, otIp6Prefix aPrefix)`	`otError` Converts a human-readable IPv6 prefix string into a binary representation.
`otIp6PrefixMatch(const otIp6Address aFirst, const otIp6Address aSecond)`	`uint8_t` Returns the prefix match length (bits) for two IPv6 addresses.
`otIp6PrefixToString(const otIp6Prefix aPrefix, char aBuffer, uint16_t aSize)`	`void` Converts a given IPv6 prefix to a human-readable string.
`otIp6ProtoToString(uint8_t aIpProto)`	`const char *` Converts a given IP protocol number to a human-readable string.
`otIp6RegisterMulticastListeners(otInstance aInstance, const otIp6Address aAddresses, uint8_t aAddressNum, const uint32_t aTimeout, otIp6RegisterMulticastListenersCallback aCallback, void aContext)`	`otError` Registers Multicast Listeners to Primary Backbone Router.
`otIp6RemoveAllUnsecurePorts(otInstance *aInstance)`	`void` Removes all ports from the allowed unsecure port list.
`otIp6RemoveUnicastAddress(otInstance aInstance, const otIp6Address aAddress)`	`otError` Removes a Network Interface Address from the Thread interface.
`otIp6RemoveUnsecurePort(otInstance *aInstance, uint16_t aPort)`	`otError` Removes a port from the allowed unsecure port list.
`otIp6ResetBorderRoutingCounters(otInstance *aInstance)`	`void` Resets the Border Routing counters.
`otIp6SelectSourceAddress(otInstance aInstance, otMessageInfo aMessageInfo)`	`otError` Perform OpenThread source address selection.
`otIp6Send(otInstance aInstance, otMessage aMessage)`	`otError` Sends an IPv6 datagram via the Thread interface.
`otIp6SetAddressCallback(otInstance aInstance, otIp6AddressCallback aCallback, void aCallbackContext)`	`void` Registers a callback to notify internal IPv6 address changes.
`otIp6SetEnabled(otInstance *aInstance, bool aEnabled)`	`otError` Brings the IPv6 interface up or down.
`otIp6SetMeshLocalIid(otInstance aInstance, const otIp6InterfaceIdentifier aIid)`	`otError` Sets the Mesh Local IID (for test purpose).
`otIp6SetReceiveCallback(otInstance aInstance, otIp6ReceiveCallback aCallback, void aCallbackContext)`	`void` Registers a callback to provide received IPv6 datagrams.
`otIp6SetReceiveFilterEnabled(otInstance *aInstance, bool aEnabled)`	`void` 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` Enables/disables the SLAAC module.
`otIp6SetSlaacPrefixFilter(otInstance *aInstance, otIp6SlaacPrefixFilter aFilter)`	`void` Sets the SLAAC module filter handler.
`otIp6SockAddrToString(const otSockAddr aSockAddr, char aBuffer, uint16_t aSize)`	`void` Converts a given IPv6 socket address to a human-readable string.
`otIp6SubscribeMulticastAddress(otInstance aInstance, const otIp6Address aAddress)`	`otError` Subscribes the Thread interface to a Network Interface Multicast Address.
`otIp6UnsubscribeMulticastAddress(otInstance aInstance, const otIp6Address aAddress)`	`otError` Unsubscribes the Thread interface to a Network Interface Multicast Address.

Macros
`OT_IP6_ADDRESS_BITSIZE (OT_IP6_ADDRESS_SIZE * 8)`	Size of an IPv6 address (bits)
`OT_IP6_ADDRESS_SIZE 16`	Size of an IPv6 address (bytes)
`OT_IP6_ADDRESS_STRING_SIZE 40`	Recommended size for string representation of an IPv6 address.
`OT_IP6_HEADER_PROTO_OFFSET 6`	Offset of the proto field in the IPv6 header (bytes)
`OT_IP6_HEADER_SIZE 40`	Size of an IPv6 header (bytes)
`OT_IP6_IID_SIZE 8`	Size of an IPv6 Interface Identifier (bytes)
`OT_IP6_MAX_MLR_ADDRESSES 15`	Max number of IPv6 addresses supported by Multicast Listener Registration.
`OT_IP6_PREFIX_BITSIZE (OT_IP6_PREFIX_SIZE * 8)`	Size of an IPv6 prefix (bits)
`OT_IP6_PREFIX_SIZE 8`	Size of an IPv6 prefix (bytes)
`OT_IP6_PREFIX_STRING_SIZE 45`	Recommended size for string representation of an IPv6 prefix.
`OT_IP6_SOCK_ADDR_STRING_SIZE 48`	Recommended size for string representation of an IPv6 socket address.

Structs
otBorderRoutingCounters	Represents the counters of packets forwarded via Border Routing.
otIp6Address	Represents an IPv6 address.
otIp6AddressComponents	Represents the components of an IPv6 address.
otIp6AddressInfo	Represents IPv6 address information.
otIp6InterfaceIdentifier	Represents the Interface Identifier of an IPv6 address.
otIp6NetworkPrefix	Represents the Network Prefix of an IPv6 address (most significant 64 bits of the address).
otIp6Prefix	Represents an IPv6 prefix.
otMessageInfo	Represents the local and peer IPv6 socket addresses.
otNetifAddress	Represents an IPv6 network interface unicast address.
otNetifMulticastAddress	Represents an IPv6 network interface multicast address.
otPacketsAndBytes	Represents the counters for packets and bytes.
otSockAddr	Represents an IPv6 socket address.

Unions
otIp6InterfaceIdentifier::OT_TOOL_PACKED_FIELD

Enumerations

Anonymous Enum 3

 Anonymous Enum 3

IPv6 Address origins.

Properties
`OT_ADDRESS_ORIGIN_DHCPV6`	DHCPv6 assigned address.
`OT_ADDRESS_ORIGIN_MANUAL`	Manually assigned address.
`OT_ADDRESS_ORIGIN_SLAAC`	SLAAC assigned address.
`OT_ADDRESS_ORIGIN_THREAD`	Thread assigned address (ALOC, RLOC, MLEID, etc)

Anonymous Enum 4

 Anonymous Enum 4

ECN statuses, represented as in the IP header.

Properties
`OT_ECN_CAPABLE_0`	ECT(0)
`OT_ECN_CAPABLE_1`	ECT(1)
`OT_ECN_MARKED`	Congestion encountered (CE)
`OT_ECN_NOT_CAPABLE`	Non-ECT.

Anonymous Enum 5

 Anonymous Enum 5

Internet Protocol Numbers.

Properties
`OT_IP6_PROTO_DST_OPTS`	Destination Options for IPv6.
`OT_IP6_PROTO_FRAGMENT`	Fragment Header for IPv6.
`OT_IP6_PROTO_HOP_OPTS`	IPv6 Hop-by-Hop Option.
`OT_IP6_PROTO_ICMP6`	ICMP for IPv6.
`OT_IP6_PROTO_IP6`	IPv6 encapsulation.
`OT_IP6_PROTO_NONE`	No Next Header for IPv6.
`OT_IP6_PROTO_ROUTING`	Routing Header for IPv6.
`OT_IP6_PROTO_TCP`	Transmission Control Protocol.
`OT_IP6_PROTO_UDP`	User Datagram.

Typedefs

otBorderRoutingCounters

struct otBorderRoutingCounters otBorderRoutingCounters

Represents the counters of packets forwarded via Border Routing.

otIp6Address

struct otIp6Address otIp6Address

Represents an IPv6 address.

otIp6AddressCallback

void(* otIp6AddressCallback)(const otIp6AddressInfo *aAddressInfo, bool aIsAdded, void *aContext)

Pointer is called when an internal IPv6 address is added or removed.

Details

Parameters

`[in] aAddressInfo`	A pointer to the IPv6 address information.
`[in] aIsAdded`	TRUE if the `aAddress` was added, FALSE if `aAddress` was removed.
`[in] aContext`	A pointer to application-specific context.

otIp6AddressComponents

struct otIp6AddressComponents otIp6AddressComponents

Represents the components of an IPv6 address.

otIp6AddressInfo

struct otIp6AddressInfo otIp6AddressInfo

Represents IPv6 address information.

otIp6InterfaceIdentifier

struct otIp6InterfaceIdentifier otIp6InterfaceIdentifier

Represents the Interface Identifier of an IPv6 address.

otIp6NetworkPrefix

struct otIp6NetworkPrefix otIp6NetworkPrefix

Represents the Network Prefix of an IPv6 address (most significant 64 bits of the address).

otIp6Prefix

struct otIp6Prefix otIp6Prefix

Represents an IPv6 prefix.

otIp6ReceiveCallback

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

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 (see otMessageFree()).
`[in] aContext`	A pointer to application-specific context.

otIp6RegisterMulticastListenersCallback

void(* otIp6RegisterMulticastListenersCallback)(void *aContext, otError aError, uint8_t aMlrStatus, const otIp6Address *aFailedAddresses, uint8_t aFailedAddressNum)

Pointer is called with results of otIp6RegisterMulticastListeners.

Details

Parameters

`[in] aContext`	A pointer to the user context.
`[in] aError`	OT_ERROR_NONE when successfully sent MLR.req and received MLR.rsp, OT_ERROR_RESPONSE_TIMEOUT when failed to receive MLR.rsp, OT_ERROR_PARSE when failed to parse MLR.rsp.
`[in] aMlrStatus`	The Multicast Listener Registration status when `aError` is OT_ERROR_NONE.
`[in] aFailedAddresses`	A pointer to the failed IPv6 addresses when `aError` is OT_ERROR_NONE.
`[in] aFailedAddressNum`	The number of failed IPv6 addresses when `aError` is OT_ERROR_NONE.

See also:
otIp6RegisterMulticastListeners

otIp6SlaacPrefixFilter

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

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] aInstance`	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

Represents the local and peer IPv6 socket addresses.

otNetifAddress

struct otNetifAddress otNetifAddress

Represents an IPv6 network interface unicast address.

otNetifMulticastAddress

struct otNetifMulticastAddress otNetifMulticastAddress

Represents an IPv6 network interface multicast address.

otPacketsAndBytes

struct otPacketsAndBytes otPacketsAndBytes

Represents the counters for packets and bytes.

otSockAddr

struct otSockAddr otSockAddr

Represents an IPv6 socket address.

Variables

OT_TOOL_PACKED_END

OT_TOOL_PACKED_BEGIN struct otIp6InterfaceIdentifier OT_TOOL_PACKED_END

Functions

otIp6AddUnicastAddress

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

Adds 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_IP6_MAX_EXT_UCAST_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
)

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_INVALID_ARGS`	The port is invalid (value 0 is reserved for internal use).
`OT_ERROR_NO_BUFS`	The unsecure port list is full.

otIp6AddressFromString

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

Converts 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 `aString` and updated `aAddress`.
`OT_ERROR_PARSE`	Failed to parse `aString` as an IPv6 address.

otIp6AddressToString

void otIp6AddressToString(
  const otIp6Address *aAddress,
  char *aBuffer,
  uint16_t aSize
)

Converts a given IPv6 address to a human-readable string.

The IPv6 address string is formatted as 16 hex values separated by ':' (i.e., "%x:%x:%x:...:%x").

If the resulting string does not fit in aBuffer (within its aSize characters), the string will be truncated but the outputted string is always null-terminated.

Details

Parameters

`[in] aAddress`	A pointer to an IPv6 address (MUST NOT be NULL).
`[out] aBuffer`	A pointer to a char array to output the string (MUST NOT be NULL).
`[in] aSize`	The size of `aBuffer` (in bytes). Recommended to use `OT_IP6_ADDRESS_STRING_SIZE`.

otIp6ArePrefixesEqual

bool otIp6ArePrefixesEqual(
  const otIp6Prefix *aFirst,
  const otIp6Prefix *aSecond
)

Test if two IPv6 prefixes are the same.

Details

Parameters

`[in] aFirst`	A pointer to the first IPv6 prefix to compare.
`[in] aSecond`	A pointer to the second IPv6 prefix to compare.

Return Values

`TRUE`	The two IPv6 prefixes are the same.
`FALSE`	The two IPv6 prefixes are not the same.

otIp6GetBorderRoutingCounters

const otBorderRoutingCounters * otIp6GetBorderRoutingCounters(
  otInstance *aInstance
)

Gets the Border Routing counters.

OPENTHREAD_CONFIG_IP6_BR_COUNTERS_ENABLE build-time feature must be enabled.

Details

Parameters

[in] aInstance

A pointer to an OpenThread instance.

Returns

A pointer to the Border Routing counters.

otIp6GetMulticastAddresses

const otNetifMulticastAddress * otIp6GetMulticastAddresses(
  otInstance *aInstance
)

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

otIp6GetPrefix

void otIp6GetPrefix(
  const otIp6Address *aAddress,
  uint8_t aLength,
  otIp6Prefix *aPrefix
)

Gets a prefix with aLength from aAddress.

Details

Parameters

`[in] aAddress`	A pointer to an IPv6 address.
`[in] aLength`	The length of prefix in bits.
`[out] aPrefix`	A pointer to output the IPv6 prefix.

otIp6GetUnicastAddresses

const otNetifAddress * otIp6GetUnicastAddresses(
  otInstance *aInstance
)

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

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.

otIp6HasUnicastAddress

bool otIp6HasUnicastAddress(
  otInstance *aInstance,
  const otIp6Address *aAddress
)

Indicates whether or not a unicast IPv6 address is assigned to the Thread interface.

Details

Parameters

`[in] aInstance`	A pointer to an OpenThread instance.
`[in] aAddress`	A pointer to the unicast address.

Return Values

`TRUE`	If `aAddress` is assigned to the Thread interface.
`FALSE`	If `aAddress` is not assigned to the Thread interface.

otIp6IsAddressEqual

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

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

bool otIp6IsEnabled(
  otInstance *aInstance
)

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.

otIp6IsReceiveFilterEnabled

bool otIp6IsReceiveFilterEnabled(
  otInstance *aInstance
)

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
)

Indicates whether the SLAAC module is enabled or not.

OPENTHREAD_CONFIG_IP6_SLAAC_ENABLE build-time feature must 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.

Note: If aSettings is 'NULL', the link layer security is enabled and the message priority is set to OT_MESSAGE_PRIORITY_NORMAL by default.

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.

Note: If aSettings is NULL, the link layer security is enabled and the message priority is obtained from IPv6 message itself. If aSettings is not NULL, the aSetting->mPriority is ignored and obtained from IPv6 message itself.

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

otIp6PrefixFromString

otError otIp6PrefixFromString(
  const char *aString,
  otIp6Prefix *aPrefix
)

Converts a human-readable IPv6 prefix string into a binary representation.

The aString parameter should be a string in the format "

/", where

is an IPv6 address and is a prefix length.

Details

Parameters

`[in] aString`	A pointer to a NULL-terminated string.
`[out] aPrefix`	A pointer to an IPv6 prefix.

Return Values

`OT_ERROR_NONE`	Successfully parsed the string as an IPv6 prefix and updated `aPrefix`.
`OT_ERROR_PARSE`	Failed to parse `aString` as an IPv6 prefix.

otIp6PrefixMatch

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

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.

otIp6PrefixToString

void otIp6PrefixToString(
  const otIp6Prefix *aPrefix,
  char *aBuffer,
  uint16_t aSize
)

Converts a given IPv6 prefix to a human-readable string.

The IPv6 address string is formatted as "%x:%x:%x:...[::]/plen".

If the resulting string does not fit in aBuffer (within its aSize characters), the string will be truncated but the outputted string is always null-terminated.

Details

Parameters

`[in] aPrefix`	A pointer to an IPv6 prefix (MUST NOT be NULL).
`[out] aBuffer`	A pointer to a char array to output the string (MUST NOT be NULL).
`[in] aSize`	The size of `aBuffer` (in bytes). Recommended to use `OT_IP6_PREFIX_STRING_SIZE`.

otIp6ProtoToString

const char * otIp6ProtoToString(
  uint8_t aIpProto
)

Converts a given IP protocol number to a human-readable string.

Details

Parameters

[in] aIpProto

An IP protocol number (OT_IP6_PROTO_* enumeration).

Returns

A string representing aIpProto.

otIp6RegisterMulticastListeners

otError otIp6RegisterMulticastListeners(
  otInstance *aInstance,
  const otIp6Address *aAddresses,
  uint8_t aAddressNum,
  const uint32_t *aTimeout,
  otIp6RegisterMulticastListenersCallback aCallback,
  void *aContext
)

Registers Multicast Listeners to Primary Backbone Router.

OPENTHREAD_CONFIG_TMF_PROXY_MLR_ENABLE and OPENTHREAD_CONFIG_COMMISSIONER_ENABLE must be enabled.

Details

Parameters

`[in] aInstance`	A pointer to an OpenThread instance.
`[in] aAddresses`	A Multicast Address Array to register.
`[in] aAddressNum`	The number of Multicast Address to register (0 if `aAddresses` is NULL).
`[in] aTimeout`	A pointer to the timeout value (in seconds) to be included in MLR.req. A timeout value of 0 removes the corresponding Multicast Listener. If NULL, MLR.req would have no Timeout Tlv by default.
`[in] aCallback`	A pointer to the callback function.
`[in] aContext`	A pointer to the user context.

Return Values

`OT_ERROR_NONE`	Successfully sent MLR.req. The `aCallback` will be called iff this method returns OT_ERROR_NONE.
`OT_ERROR_BUSY`	If a previous registration was ongoing.
`OT_ERROR_INVALID_ARGS`	If one or more arguments are invalid.
`OT_ERROR_INVALID_STATE`	If the device was not in a valid state to send MLR.req (e.g. Commissioner not started, Primary Backbone Router not found).
`OT_ERROR_NO_BUFS`	If insufficient message buffers available.

See also:
otIp6RegisterMulticastListenersCallback

otIp6RemoveAllUnsecurePorts

void otIp6RemoveAllUnsecurePorts(
  otInstance *aInstance
)

Removes all ports from the allowed unsecure port list.

Details

Parameters

[in] aInstance

A pointer to an OpenThread instance.

otIp6RemoveUnicastAddress

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

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

Removes a port from the allowed unsecure port list.

Note: This function removes aPort by overwriting aPort with the element after aPort in the internal port list. Be careful when calling otIp6GetUnsecurePorts() followed by otIp6RemoveUnsecurePort() to remove unsecure ports.

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_INVALID_ARGS`	The port is invalid (value 0 is reserved for internal use).
`OT_ERROR_NOT_FOUND`	The port was not found in the unsecure port list.

otIp6ResetBorderRoutingCounters

void otIp6ResetBorderRoutingCounters(
  otInstance *aInstance
)

Resets the Border Routing counters.

Details

Parameters

[in] aInstance

A pointer to an OpenThread instance.

otIp6SelectSourceAddress

otError otIp6SelectSourceAddress(
  otInstance *aInstance,
  otMessageInfo *aMessageInfo
)

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
)

Sends an IPv6 datagram via the Thread interface.

The caller transfers ownership of aMessage when making this call. OpenThread will free aMessage when processing is complete, including when a value other than OT_ERROR_NONE is returned.

Details

Parameters

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

Return Values

`OT_ERROR_NONE`	Successfully processed the message.
`OT_ERROR_DROP`	Message was well-formed but not fully processed due to packet processing rules.
`OT_ERROR_NO_BUFS`	Could not allocate necessary message buffers when processing the datagram.
`OT_ERROR_NO_ROUTE`	No route to host.
`OT_ERROR_INVALID_SOURCE_ADDRESS`	Source address is invalid, e.g. an anycast address or a multicast address.
`OT_ERROR_PARSE`	Encountered a malformed header when processing the message.
`OT_ERROR_INVALID_ARGS`	The message's metadata is invalid, e.g. the message uses `OT_MESSAGE_ORIGIN_THREAD_NETIF` as the origin.

otIp6SetAddressCallback

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

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

otError otIp6SetEnabled(
  otInstance *aInstance,
  bool aEnabled
)

Brings the IPv6 interface up or down.

Call this to enable or 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_CONFIG_LINK_RAW_ENABLE` feature is enabled).

otIp6SetMeshLocalIid

otError otIp6SetMeshLocalIid(
  otInstance *aInstance,
  const otIp6InterfaceIdentifier *aIid
)

Sets the Mesh Local IID (for test purpose).

Requires OPENTHREAD_CONFIG_REFERENCE_DEVICE_ENABLE.

Details

Parameters

`[in] aInstance`	A pointer to an OpenThread instance.
`[in] aIid`	A pointer to the Mesh Local IID to set.

Return Values

`OT_ERROR_NONE`	Successfully set the Mesh Local IID.
`OT_ERROR_INVALID_STATE`	Thread protocols are enabled.

otIp6SetReceiveCallback

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

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
)

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
)

Enables/disables the SLAAC module.

OPENTHREAD_CONFIG_IP6_SLAAC_ENABLE build-time feature must 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
)

Sets the SLAAC module filter handler.

OPENTHREAD_CONFIG_IP6_SLAAC_ENABLE build-time feature must 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.

otIp6SockAddrToString

void otIp6SockAddrToString(
  const otSockAddr *aSockAddr,
  char *aBuffer,
  uint16_t aSize
)

Converts a given IPv6 socket address to a human-readable string.

The IPv6 socket address string is formatted as [address]:port where address is shown as 16 hex values separated by : and port is the port number in decimal format, for example "[%x:%x:...:%x]:%u".

If the resulting string does not fit in aBuffer (within its aSize characters), the string will be truncated but the outputted string is always null-terminated.

Details

Parameters

`[in] aSockAddr`	A pointer to an IPv6 socket address (MUST NOT be NULL).
`[out] aBuffer`	A pointer to a char array to output the string (MUST NOT be NULL).
`[in] aSize`	The size of `aBuffer` (in bytes). Recommended to use `OT_IP6_SOCK_ADDR_STRING_SIZE`.

otIp6SubscribeMulticastAddress

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

Subscribes 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_IP6_MAX_EXT_MCAST_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 an invalid multicast address.
`OT_ERROR_REJECTED`	The IP Address indicated by `aAddress` is an internal multicast address.
`OT_ERROR_NO_BUFS`	The Network Interface is already storing the maximum allowed external multicast addresses.

otIp6UnsubscribeMulticastAddress

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

Unsubscribes 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_REJECTED`	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_BITSIZE

 OT_IP6_ADDRESS_BITSIZE (OT_IP6_ADDRESS_SIZE * 8)

Size of an IPv6 address (bits)

OT_IP6_ADDRESS_SIZE

 OT_IP6_ADDRESS_SIZE 16

Size of an IPv6 address (bytes)

OT_IP6_ADDRESS_STRING_SIZE

 OT_IP6_ADDRESS_STRING_SIZE 40

Recommended size for string representation of an IPv6 address.

OT_IP6_HEADER_PROTO_OFFSET

 OT_IP6_HEADER_PROTO_OFFSET 6

Offset of the proto field in the IPv6 header (bytes)

OT_IP6_HEADER_SIZE

 OT_IP6_HEADER_SIZE 40

Size of an IPv6 header (bytes)

OT_IP6_IID_SIZE

 OT_IP6_IID_SIZE 8

Size of an IPv6 Interface Identifier (bytes)

OT_IP6_MAX_MLR_ADDRESSES

 OT_IP6_MAX_MLR_ADDRESSES 15

Max number of IPv6 addresses supported by Multicast Listener Registration.

OT_IP6_PREFIX_BITSIZE

 OT_IP6_PREFIX_BITSIZE (OT_IP6_PREFIX_SIZE * 8)

Size of an IPv6 prefix (bits)

OT_IP6_PREFIX_SIZE

 OT_IP6_PREFIX_SIZE 8

Size of an IPv6 prefix (bytes)

OT_IP6_PREFIX_STRING_SIZE

 OT_IP6_PREFIX_STRING_SIZE 45

Recommended size for string representation of an IPv6 prefix.

OT_IP6_SOCK_ADDR_STRING_SIZE

 OT_IP6_SOCK_ADDR_STRING_SIZE 48

Recommended size for string representation of an IPv6 socket address.

Resources

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

IPv6

Summary

Enumerations

Typedefs

Variables

Functions

Macros

Structs

Unions

Enumerations

Anonymous Enum 3

Anonymous Enum 4

Anonymous Enum 5

Typedefs

otBorderRoutingCounters

otIp6Address

otIp6AddressCallback

otIp6AddressComponents

otIp6AddressInfo

otIp6InterfaceIdentifier

otIp6NetworkPrefix

otIp6Prefix

otIp6ReceiveCallback

otIp6RegisterMulticastListenersCallback

otIp6SlaacPrefixFilter

otMessageInfo

otNetifAddress

otNetifMulticastAddress

otPacketsAndBytes

otSockAddr

Variables

OT_TOOL_PACKED_END

Functions

otIp6AddUnicastAddress

otIp6AddUnsecurePort

otIp6AddressFromString

otIp6AddressToString

otIp6ArePrefixesEqual

otIp6GetBorderRoutingCounters

otIp6GetMulticastAddresses

otIp6GetPrefix

otIp6GetUnicastAddresses

otIp6GetUnsecurePorts

otIp6HasUnicastAddress

otIp6IsAddressEqual

otIp6IsAddressUnspecified

otIp6IsEnabled

otIp6IsReceiveFilterEnabled

otIp6IsSlaacEnabled

otIp6NewMessage

otIp6NewMessageFromBuffer

otIp6PrefixFromString

otIp6PrefixMatch

otIp6PrefixToString

otIp6ProtoToString

otIp6RegisterMulticastListeners

otIp6RemoveAllUnsecurePorts

otIp6RemoveUnicastAddress

otIp6RemoveUnsecurePort

otIp6ResetBorderRoutingCounters

otIp6SelectSourceAddress

otIp6Send

otIp6SetAddressCallback

otIp6SetEnabled

otIp6SetMeshLocalIid

otIp6SetReceiveCallback

otIp6SetReceiveFilterEnabled

otIp6SetSlaacEnabled

otIp6SetSlaacPrefixFilter

otIp6SockAddrToString

otIp6SubscribeMulticastAddress

otIp6UnsubscribeMulticastAddress

Macros

OT_IP6_ADDRESS_BITSIZE

OT_IP6_ADDRESS_SIZE

OT_IP6_ADDRESS_STRING_SIZE

OT_IP6_HEADER_PROTO_OFFSET

OT_IP6_HEADER_SIZE

OT_IP6_IID_SIZE

OT_IP6_MAX_MLR_ADDRESSES