This module includes functions and structs for the NAT64 function on the border router.

Classes
struct	otIp4Address
	This structure represents an IPv4 address.

struct	otIp4Cidr
	This structure represents an IPv4 CIDR block.

struct	otNat64Counters
	Represents the counters for NAT64.

struct	otNat64ProtocolCounters
	Represents the counters for the protocols supported by NAT64.

struct	otNat64ErrorCounters
	Represents the counters of dropped packets due to errors when handling NAT64 packets.

struct	otNat64AddressMapping
	Represents an address mapping record for NAT64.

struct	otNat64AddressMappingIterator
	Used to iterate through NAT64 address mappings.

Macros
#define	OT_IP4_ADDRESS_SIZE 4
	Size of an IPv4 address (bytes)

#define	OT_IP4_ADDRESS_STRING_SIZE 17
	Length of 000.000.000.000 plus a suffix NUL.

#define	OT_IP4_CIDR_STRING_SIZE 20
	Length of 000.000.000.000/00 plus a suffix NUL.

Typedefs
typedef struct otIp4Address	otIp4Address
	This structure represents an IPv4 address.

typedef struct otIp4Cidr	otIp4Cidr

typedef struct otNat64Counters	otNat64Counters
	Represents the counters for NAT64.

typedef struct otNat64ProtocolCounters	otNat64ProtocolCounters
	Represents the counters for the protocols supported by NAT64.

typedef enum otNat64DropReason	otNat64DropReason
	Packet drop reasons.

typedef struct otNat64ErrorCounters	otNat64ErrorCounters
	Represents the counters of dropped packets due to errors when handling NAT64 packets.

typedef struct otNat64AddressMapping	otNat64AddressMapping
	Represents an address mapping record for NAT64.

typedef struct otNat64AddressMappingIterator	otNat64AddressMappingIterator
	Used to iterate through NAT64 address mappings.

typedef void(*	otNat64ReceiveIp4Callback ) ( otMessage aMessage, void aContext)
	This function pointer is called when an IPv4 datagram (translated by NAT64 translator) is received.

Enumerations
enum	otNat64DropReason { OT_NAT64_DROP_REASON_UNKNOWN = 0, OT_NAT64_DROP_REASON_ILLEGAL_PACKET , OT_NAT64_DROP_REASON_UNSUPPORTED_PROTO , OT_NAT64_DROP_REASON_NO_MAPPING , OT_NAT64_DROP_REASON_COUNT }
	Packet drop reasons.

enum	otNat64State { OT_NAT64_STATE_DISABLED = 0, OT_NAT64_STATE_NOT_RUNNING , OT_NAT64_STATE_IDLE , OT_NAT64_STATE_ACTIVE }
	States of NAT64.

Functions
void	otNat64GetCounters ( otInstance aInstance, otNat64ProtocolCounters aCounters)
	Gets NAT64 translator counters.

void	otNat64GetErrorCounters ( otInstance aInstance, otNat64ErrorCounters aCounters)
	Gets the NAT64 translator error counters.

void	otNat64InitAddressMappingIterator ( otInstance aInstance, otNat64AddressMappingIterator aIterator)
	Initializes an `otNat64AddressMappingIterator` .

otError	otNat64GetNextAddressMapping ( otInstance aInstance, otNat64AddressMappingIterator aIterator, otNat64AddressMapping *aMapping)
	Gets the next AddressMapping info (using an iterator).

otNat64State	otNat64GetTranslatorState ( otInstance *aInstance)
	Gets the state of NAT64 translator.

otNat64State	otNat64GetPrefixManagerState ( otInstance *aInstance)
	Gets the state of NAT64 prefix manager.

void	otNat64SetEnabled ( otInstance *aInstance, bool aEnable)
	Enable or disable NAT64 functions.

otMessage *	otIp4NewMessage ( otInstance aInstance, const otMessageSettings aSettings)
	Allocate a new message buffer for sending an IPv4 message to the NAT64 translator.

otError	otNat64SetIp4Cidr ( otInstance aInstance, const otIp4Cidr aCidr)
	Sets the CIDR used when setting the source address of the outgoing translated IPv4 packets.

otError	otNat64Send ( otInstance aInstance, otMessage aMessage)
	Translates an IPv4 datagram to an IPv6 datagram and sends via the Thread interface.

void	otNat64SetReceiveIp4Callback ( otInstance aInstance, otNat64ReceiveIp4Callback aCallback, void aContext)
	Registers a callback to provide received IPv4 datagrams.

otError	otNat64GetCidr ( otInstance aInstance, otIp4Cidr aCidr)
	Gets the IPv4 CIDR configured in the NAT64 translator.

bool	otIp4IsAddressEqual (const otIp4Address aFirst, const otIp4Address aSecond)
	Test if two IPv4 addresses are the same.

void	otIp4ExtractFromIp6Address (uint8_t aPrefixLength, const otIp6Address aIp6Address, otIp4Address aIp4Address)
	Set `aIp4Address` by performing NAT64 address translation from `aIp6Address` as specified in RFC 6052.

void	otIp4AddressToString (const otIp4Address aAddress, char aBuffer, uint16_t aSize)
	Converts the address to a string.

void	otIp4CidrToString (const otIp4Cidr aCidr, char aBuffer, uint16_t aSize)
	Converts the IPv4 CIDR to a string.

otError	otIp4AddressFromString (const char aString, otIp4Address aAddress)
	Converts a human-readable IPv4 address string into a binary representation.

otError	otNat64SynthesizeIp6Address ( otInstance aInstance, const otIp4Address aIp4Address, otIp6Address *aIp6Address)
	Sets the IPv6 address by performing NAT64 address translation from the preferred NAT64 prefix and the given IPv4 address as specified in RFC 6052.

Variables
OT_TOOL_PACKED_BEGIN struct otIp4Address	OT_TOOL_PACKED_END

Detailed Description

This module includes functions and structs for the NAT64 function on the border router.

These functions are only available when OPENTHREAD_CONFIG_NAT64_BORDER_ROUTING_ENABLE is enabled.

Typedef Documentation

◆ otNat64AddressMapping

typedef struct otNat64AddressMapping otNat64AddressMapping

Represents an address mapping record for NAT64.

Note: The counters will be reset for each mapping session even for the same address pair. Applications can use mId to identify different sessions to calculate the packets correctly.

◆ otNat64AddressMappingIterator

typedef struct otNat64AddressMappingIterator otNat64AddressMappingIterator

Used to iterate through NAT64 address mappings.

The fields in this type are opaque (intended for use by OpenThread core only) and therefore should not be accessed or used by caller.

Before using an iterator, it MUST be initialized using otNat64AddressMappingIteratorInit() .

◆ otNat64ReceiveIp4Callback

typedef void(* otNat64ReceiveIp4Callback) ( otMessage *aMessage, void *aContext)

This function pointer is called when an IPv4 datagram (translated by NAT64 translator) is received.

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

Enumeration Type Documentation

◆ otNat64DropReason

enum otNat64DropReason

Packet drop reasons.

Enumerator
OT_NAT64_DROP_REASON_UNKNOWN	Packet drop for unknown reasons.
OT_NAT64_DROP_REASON_ILLEGAL_PACKET	Packet drop due to failed to parse the datagram.
OT_NAT64_DROP_REASON_UNSUPPORTED_PROTO	Packet drop due to unsupported IP protocol.
OT_NAT64_DROP_REASON_NO_MAPPING	Packet drop due to no mappings found or mapping pool exhausted.

◆ otNat64State

enum otNat64State

States of NAT64.

Enumerator
OT_NAT64_STATE_DISABLED	NAT64 is disabled.
OT_NAT64_STATE_NOT_RUNNING	NAT64 is enabled, but one or more dependencies of NAT64 are not running.
OT_NAT64_STATE_IDLE	NAT64 is enabled, but this BR is not an active NAT64 BR.
OT_NAT64_STATE_ACTIVE	The BR is publishing a NAT64 prefix and/or translating packets.

Function Documentation

◆ otIp4AddressFromString()

otError otIp4AddressFromString	(	const char *	`aString,`
		otIp4Address *	`aAddress`
	)

Converts a human-readable IPv4 address string into a binary representation.

Parameters

[in]	`aString`	A pointer to a NULL-terminated string.
[out]	`aAddress`	A pointer to an IPv4 address.

Return values

`OT_ERROR_NONE`	Successfully parsed the string.
`OT_ERROR_INVALID_ARGS`	Failed to parse the string.

◆ otIp4AddressToString()

void otIp4AddressToString	(	const otIp4Address *	`aAddress,`
		char *	`aBuffer,`
		uint16_t	`aSize`
	)

Converts the address to a string.

The string format uses quad-dotted notation of four bytes in the address (e.g., "127.0.0.1").

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.

Parameters

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

◆ otIp4CidrToString()

void otIp4CidrToString	(	const otIp4Cidr *	`aCidr,`
		char *	`aBuffer,`
		uint16_t	`aSize`
	)

Converts the IPv4 CIDR to a string.

The string format uses quad-dotted notation of four bytes in the address with the length of prefix (e.g., "127.0.0.1/32").

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.

Parameters

[in]	`aCidr`	A pointer to an IPv4 CIDR (MUST NOT be NULL).
[out]	`aBuffer`	A pointer to a char array to output the string (MUST NOT be `nullptr` ).
[in]	`aSize`	The size of `aBuffer` (in bytes).

◆ otIp4ExtractFromIp6Address()

void otIp4ExtractFromIp6Address	(	uint8_t	`aPrefixLength,`
		const otIp6Address *	`aIp6Address,`
		otIp4Address *	`aIp4Address`
	)

Set aIp4Address by performing NAT64 address translation from aIp6Address as specified in RFC 6052.

The NAT64 aPrefixLength MUST be one of the following values: 32, 40, 48, 56, 64, or 96, otherwise the behavior of this method is undefined.

Parameters

[in]	`aPrefixLength`	The prefix length to use for IPv4/IPv6 translation.
[in]	`aIp6Address`	A pointer to an IPv6 address.
[out]	`aIp4Address`	A pointer to output the IPv4 address.

◆ otIp4IsAddressEqual()

bool otIp4IsAddressEqual	(	const otIp4Address *	`aFirst,`
		const otIp4Address *	`aSecond`
	)

Test if two IPv4 addresses are the same.

Parameters

[in]	`aFirst`	A pointer to the first IPv4 address to compare.
[in]	`aSecond`	A pointer to the second IPv4 address to compare.

Return values

`TRUE`	The two IPv4 addresses are the same.
`FALSE`	The two IPv4 addresses are not the same.

◆ otIp4NewMessage()

otMessage * otIp4NewMessage	(	otInstance *	`aInstance,`
		const otMessageSettings *	`aSettings`
	)

Allocate a new message buffer for sending an IPv4 message to the NAT64 translator.

Message buffers allocated by this function will have 20 bytes (difference between the size of IPv6 headers and IPv4 header sizes) reserved.

Available when OPENTHREAD_CONFIG_NAT64_TRANSLATOR_ENABLE is enabled.

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

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

◆ otNat64GetCidr()

otError otNat64GetCidr	(	otInstance *	`aInstance,`
		otIp4Cidr *	`aCidr`
	)

Gets the IPv4 CIDR configured in the NAT64 translator.

Available when OPENTHREAD_CONFIG_NAT64_TRANSLATOR_ENABLE is enabled.

Parameters

[in]	`aInstance`	A pointer to an OpenThread instance.
[out]	`aCidr`	A pointer to an otIp4Cidr . Where the CIDR will be filled.

◆ otNat64GetCounters()

void otNat64GetCounters	(	otInstance *	`aInstance,`
		otNat64ProtocolCounters *	`aCounters`
	)

Gets NAT64 translator counters.

The counter is counted since the instance initialized.

Available when OPENTHREAD_CONFIG_NAT64_TRANSLATOR_ENABLE is enabled.

Parameters

[in]	`aInstance`	A pointer to an OpenThread instance.
[out]	`aCounters`	A pointer to an `otNat64Counters` where the counters of NAT64 translator will be placed.

◆ otNat64GetErrorCounters()

void otNat64GetErrorCounters	(	otInstance *	`aInstance,`
		otNat64ErrorCounters *	`aCounters`
	)

Gets the NAT64 translator error counters.

The counters are initialized to zero when the OpenThread instance is initialized.

Parameters

[in]	`aInstance`	A pointer to an OpenThread instance.
[out]	`aCounters`	A pointer to an `otNat64Counters` where the counters of NAT64 translator will be placed.

◆ otNat64GetNextAddressMapping()

otError otNat64GetNextAddressMapping	(	otInstance *	`aInstance,`
		otNat64AddressMappingIterator *	`aIterator,`
		otNat64AddressMapping *	`aMapping`
	)

Gets the next AddressMapping info (using an iterator).

Available when OPENTHREAD_CONFIG_NAT64_TRANSLATOR_ENABLE is enabled.

Parameters

[in]	`aInstance`	A pointer to an OpenThread instance.
[in,out]	`aIterator`	A pointer to the iterator. On success the iterator will be updated to point to next NAT64 address mapping record. To get the first entry the iterator should be set to OT_NAT64_ADDRESS_MAPPING_ITERATOR_INIT.
[out]	`aMapping`	A pointer to an `otNat64AddressMapping` where information of next NAT64 address mapping record is placed (on success).

Return values

`OT_ERROR_NONE`	Successfully found the next NAT64 address mapping info ( `aMapping` was successfully updated).
`OT_ERROR_NOT_FOUND`	No subsequent NAT64 address mapping info was found.

◆ otNat64GetPrefixManagerState()

otNat64State otNat64GetPrefixManagerState ( otInstance * aInstance )

Gets the state of NAT64 prefix manager.

Available when OPENTHREAD_CONFIG_NAT64_BORDER_ROUTING_ENABLE is enabled.

Parameters

[in] aInstance A pointer to an OpenThread instance.

Return values

`OT_NAT64_STATE_DISABLED`	NAT64 prefix manager is disabled.
`OT_NAT64_STATE_NOT_RUNNING`	NAT64 prefix manager is enabled, but is not running (because the routing manager is not running).
`OT_NAT64_STATE_IDLE`	NAT64 prefix manager is enabled, but is not publishing a NAT64 prefix. Usually when there is another border router publishing a NAT64 prefix with higher priority.
`OT_NAT64_STATE_ACTIVE`	NAT64 prefix manager is enabled, and is publishing NAT64 prefix to the Thread network.

◆ otNat64GetTranslatorState()

otNat64State otNat64GetTranslatorState ( otInstance * aInstance )

Gets the state of NAT64 translator.

Available when OPENTHREAD_CONFIG_NAT64_TRANSLATOR_ENABLE is enabled.

Parameters

[in] aInstance A pointer to an OpenThread instance.

Return values

`OT_NAT64_STATE_DISABLED`	NAT64 translator is disabled.
`OT_NAT64_STATE_NOT_RUNNING`	NAT64 translator is enabled, but the translator is not configured with a valid NAT64 prefix and a CIDR.
`OT_NAT64_STATE_ACTIVE`	NAT64 translator is enabled, and is translating packets.

◆ otNat64InitAddressMappingIterator()

void otNat64InitAddressMappingIterator	(	otInstance *	`aInstance,`
		otNat64AddressMappingIterator *	`aIterator`
	)

Initializes an otNat64AddressMappingIterator .

An iterator MUST be initialized before it is used.

An iterator can be initialized again to restart from the beginning of the mapping info.

Parameters

[in]	`aInstance`	The OpenThread instance.
[out]	`aIterator`	A pointer to the iterator to initialize.

◆ otNat64Send()

otError otNat64Send	(	otInstance *	`aInstance,`
		otMessage *	`aMessage`
	)

Translates an IPv4 datagram to an IPv6 datagram and sends 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.

Parameters

[in]	`aInstance`	A pointer to an OpenThread instance.
[in]	`aMessage`	A pointer to the message buffer containing the IPv4 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.

◆ otNat64SetEnabled()

void otNat64SetEnabled	(	otInstance *	`aInstance,`
		bool	`aEnable`
	)

Enable or disable NAT64 functions.

Note: This includes the NAT64 Translator (when OPENTHREAD_CONFIG_NAT64_TRANSLATOR_ENABLE is enabled) and the NAT64 Prefix Manager (when OPENTHREAD_CONFIG_NAT64_BORDER_ROUTING_ENABLE is enabled).

When OPENTHREAD_CONFIG_NAT64_TRANSLATOR_ENABLE is enabled, setting disabled to true resets the mapping table in the translator.

Available when OPENTHREAD_CONFIG_NAT64_TRANSLATOR_ENABLE or OPENTHREAD_CONFIG_NAT64_BORDER_ROUTING_ENABLE is enabled.

Parameters

[in]	`aInstance`	A pointer to an OpenThread instance.
[in]	`aEnabled`	A boolean to enable/disable the NAT64 functions

See also: otNat64GetTranslatorState; otNat64GetPrefixManagerState

◆ otNat64SetIp4Cidr()

otError otNat64SetIp4Cidr	(	otInstance *	`aInstance,`
		const otIp4Cidr *	`aCidr`
	)

Sets the CIDR used when setting the source address of the outgoing translated IPv4 packets.

This function is available only when OPENTHREAD_CONFIG_NAT64_TRANSLATOR_ENABLE is enabled.

Note: A valid CIDR must have a non-zero prefix length. The actual addresses pool is limited by the size of the mapping pool and the number of addresses available in the CIDR block.; This function can be called at any time, but the NAT64 translator will be reset and all existing sessions will be expired when updating the configured CIDR.

Parameters

[in]	`aInstance`	A pointer to an OpenThread instance.
[in]	`aCidr`	A pointer to an otIp4Cidr for the IPv4 CIDR block for NAT64.

Return values

`OT_ERROR_INVALID_ARGS`	The given CIDR is not a valid IPv4 CIDR for NAT64.
`OT_ERROR_NONE`	Successfully set the CIDR for NAT64.

See also: otBorderRouterSend; otBorderRouterSetReceiveCallback

◆ otNat64SetReceiveIp4Callback()

void otNat64SetReceiveIp4Callback	(	otInstance *	`aInstance,`
		otNat64ReceiveIp4Callback	`aCallback,`
		void *	`aContext`
	)

Registers a callback to provide received IPv4 datagrams.

Parameters

[in]	`aInstance`	A pointer to an OpenThread instance.
[in]	`aCallback`	A pointer to a function that is called when an IPv4 datagram is received or NULL to disable the callback.
[in]	`aCallbackContext`	A pointer to application-specific context.

◆ otNat64SynthesizeIp6Address()

otError otNat64SynthesizeIp6Address	(	otInstance *	`aInstance,`
		const otIp4Address *	`aIp4Address,`
		otIp6Address *	`aIp6Address`
	)

Sets the IPv6 address by performing NAT64 address translation from the preferred NAT64 prefix and the given IPv4 address as specified in RFC 6052.

Parameters

[in]	`aInstance`	A pointer to an OpenThread instance.
[in]	`aIp4Address`	A pointer to the IPv4 address to translate to IPv6.
[out]	`aIp6Address`	A pointer to the synthesized IPv6 address.

Returns: OT_ERROR_NONE Successfully synthesized the IPv6 address from NAT64 prefix and IPv4 address.; OT_ERROR_INVALID_STATE No valid NAT64 prefix in the network data.

NAT64 API > IPv6 Networking

Classes

Macros

Typedefs

Enumerations

Functions

Variables

Detailed Description

Typedef Documentation

◆ otNat64AddressMapping

◆ otNat64AddressMappingIterator

◆ otNat64ReceiveIp4Callback

Enumeration Type Documentation

◆ otNat64DropReason

◆ otNat64State

Function Documentation

◆ otIp4AddressFromString()

◆ otIp4AddressToString()

◆ otIp4CidrToString()

◆ otIp4ExtractFromIp6Address()

◆ otIp4IsAddressEqual()

◆ otIp4NewMessage()

◆ otNat64GetCidr()

◆ otNat64GetCounters()

◆ otNat64GetErrorCounters()

◆ otNat64GetNextAddressMapping()

◆ otNat64GetPrefixManagerState()

◆ otNat64GetTranslatorState()

◆ otNat64InitAddressMappingIterator()

◆ otNat64Send()

◆ otNat64SetEnabled()

◆ otNat64SetIp4Cidr()

◆ otNat64SetReceiveIp4Callback()

◆ otNat64SynthesizeIp6Address()

NAT64
API > IPv6 Networking