NAT64
This module includes functions and structs for the NAT64 function on the border router.
Summary
These functions are only available when OPENTHREAD_CONFIG_NAT64_BORDER_ROUTING_ENABLE
is enabled.
Enumerations |
|
---|---|
otNat64DropReason{
|
enum Packet drop reasons. |
otNat64State{
|
enum States of NAT64. |
Typedefs |
|
---|---|
otIp4Address
|
typedefstruct otIp4Address
Represents an IPv4 address. |
otIp4Cidr
|
typedefstruct otIp4Cidr
|
otNat64AddressMapping
|
typedefstruct otNat64AddressMapping
Represents an address mapping record for NAT64. |
otNat64AddressMappingIterator
|
typedef Used to iterate through NAT64 address mappings. |
otNat64Counters
|
typedefstruct otNat64Counters
Represents the counters for NAT64. |
otNat64DropReason
|
typedefenum otNat64DropReason
Packet drop reasons. |
otNat64ErrorCounters
|
typedefstruct otNat64ErrorCounters
Represents the counters of dropped packets due to errors when handling NAT64 packets. |
otNat64ProtocolCounters
|
typedefstruct otNat64ProtocolCounters
Represents the counters for the protocols supported by NAT64. |
otNat64ReceiveIp4Callback)(otMessage *aMessage, void *aContext)
|
typedefvoid(*
Pointer is called when an IPv4 datagram (translated by NAT64 translator) is received. |
Variables |
|
---|---|
OT_TOOL_PACKED_END
|
OT_TOOL_PACKED_BEGIN struct otIp4Address
|
Functions |
|
---|---|
otIp4AddressFromString(const char *aString, otIp4Address *aAddress)
|
Converts a human-readable IPv4 address string into a binary representation.
|
otIp4AddressToString(const otIp4Address *aAddress, char *aBuffer, uint16_t aSize)
|
void
Converts the address to a string.
|
otIp4CidrFromString(const char *aString, otIp4Cidr *aCidr)
|
Converts a human-readable IPv4 CIDR string into a binary representation.
|
otIp4CidrToString(const otIp4Cidr *aCidr, char *aBuffer, uint16_t aSize)
|
void
Converts the IPv4 CIDR to a string.
|
otIp4ExtractFromIp6Address(uint8_t aPrefixLength, const otIp6Address *aIp6Address, otIp4Address *aIp4Address)
|
void
Set
aIp4Address by performing NAT64 address translation from aIp6Address as specified in RFC 6052. |
otIp4FromIp4MappedIp6Address(const otIp6Address *aIp6Address, otIp4Address *aIp4Address)
|
Extracts the IPv4 address from a given IPv4-mapped IPv6 address.
|
otIp4IsAddressEqual(const otIp4Address *aFirst, const otIp4Address *aSecond)
|
bool
Test if two IPv4 addresses are the same.
|
otIp4NewMessage(otInstance *aInstance, const otMessageSettings *aSettings)
|
Allocate a new message buffer for sending an IPv4 message to the NAT64 translator.
|
otIp4ToIp4MappedIp6Address(const otIp4Address *aIp4Address, otIp6Address *aIp6Address)
|
void
Converts a given IP4 address to an IPv6 address following the IPv4-mapped IPv6 address format.
|
otNat64ClearIp4Cidr(otInstance *aInstance)
|
void
Clears the CIDR used when setting the source address of the outgoing translated IPv4 packets.
|
otNat64GetCidr(otInstance *aInstance, otIp4Cidr *aCidr)
|
Gets the IPv4 CIDR configured in the NAT64 translator.
|
otNat64GetCounters(otInstance *aInstance, otNat64ProtocolCounters *aCounters)
|
void
Gets NAT64 translator counters.
|
otNat64GetErrorCounters(otInstance *aInstance, otNat64ErrorCounters *aCounters)
|
void
Gets the NAT64 translator error counters.
|
otNat64GetNextAddressMapping(otInstance *aInstance, otNat64AddressMappingIterator *aIterator, otNat64AddressMapping *aMapping)
|
Gets the next AddressMapping info (using an iterator).
|
otNat64GetPrefixManagerState(otInstance *aInstance)
|
Gets the state of NAT64 prefix manager.
|
otNat64GetTranslatorState(otInstance *aInstance)
|
Gets the state of NAT64 translator.
|
otNat64InitAddressMappingIterator(otInstance *aInstance, otNat64AddressMappingIterator *aIterator)
|
void
Initializes an
otNat64AddressMappingIterator . |
otNat64Send(otInstance *aInstance, otMessage *aMessage)
|
Translates an IPv4 datagram to an IPv6 datagram and sends via the Thread interface.
|
otNat64SetEnabled(otInstance *aInstance, bool aEnabled)
|
void
Enable or disable NAT64 functions.
|
otNat64SetIp4Cidr(otInstance *aInstance, const otIp4Cidr *aCidr)
|
Sets the CIDR used when setting the source address of the outgoing translated IPv4 packets.
|
otNat64SetReceiveIp4Callback(otInstance *aInstance, otNat64ReceiveIp4Callback aCallback, void *aContext)
|
void
Registers a callback to provide received IPv4 datagrams.
|
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.
|
Macros |
|
---|---|
OT_IP4_ADDRESS_SIZE 4
|
Size of an IPv4 address (bytes)
|
OT_IP4_ADDRESS_STRING_SIZE 17
|
Length of 000.000.000.000 plus a suffix NUL.
|
OT_IP4_CIDR_STRING_SIZE 20
|
Length of 000.000.000.000/00 plus a suffix NUL.
|
Structs |
|
---|---|
otIp4Address |
Represents an IPv4 address. |
otIp4Cidr |
Represents an IPv4 CIDR block. |
otNat64AddressMapping |
Represents an address mapping record for NAT64. |
otNat64AddressMappingIterator |
Used to iterate through NAT64 address mappings. |
otNat64Counters |
Represents the counters for NAT64. |
otNat64ErrorCounters |
Represents the counters of dropped packets due to errors when handling NAT64 packets. |
otNat64ProtocolCounters |
Represents the counters for the protocols supported by NAT64. |
Unions |
|
---|---|
otIp4Address:: |
Enumerations
otNat64DropReason
otNat64DropReason
Packet drop reasons.
Properties | |
---|---|
OT_NAT64_DROP_REASON_ILLEGAL_PACKET
|
Packet drop due to failed to parse the datagram. |
OT_NAT64_DROP_REASON_NO_MAPPING
|
Packet drop due to no mappings found or mapping pool exhausted. |
OT_NAT64_DROP_REASON_UNKNOWN
|
Packet drop for unknown reasons. |
OT_NAT64_DROP_REASON_UNSUPPORTED_PROTO
|
Packet drop due to unsupported IP protocol. |
otNat64State
otNat64State
States of NAT64.
Properties | |
---|---|
OT_NAT64_STATE_ACTIVE
|
The BR is publishing a NAT64 prefix and/or translating packets. |
OT_NAT64_STATE_DISABLED
|
NAT64 is disabled. |
OT_NAT64_STATE_IDLE
|
NAT64 is enabled, but this BR is not an active NAT64 BR. |
OT_NAT64_STATE_NOT_RUNNING
|
NAT64 is enabled, but one or more dependencies of NAT64 are not running. |
Typedefs
otIp4Cidr
struct otIp4Cidr otIp4Cidr
otNat64AddressMapping
struct otNat64AddressMapping otNat64AddressMapping
Represents an address mapping record for NAT64.
otNat64AddressMappingIterator
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()
.
otNat64ErrorCounters
struct otNat64ErrorCounters otNat64ErrorCounters
Represents the counters of dropped packets due to errors when handling NAT64 packets.
otNat64ProtocolCounters
struct otNat64ProtocolCounters otNat64ProtocolCounters
Represents the counters for the protocols supported by NAT64.
otNat64ReceiveIp4Callback
void(* otNat64ReceiveIp4Callback)(otMessage *aMessage, void *aContext)
Pointer is called when an IPv4 datagram (translated by NAT64 translator) is received.
Details | |||||
---|---|---|---|---|---|
Parameters |
|
Variables
OT_TOOL_PACKED_END
OT_TOOL_PACKED_BEGIN struct otIp4Address OT_TOOL_PACKED_END
Functions
otIp4AddressFromString
otError otIp4AddressFromString( const char *aString, otIp4Address *aAddress )
Converts a human-readable IPv4 address string into a binary representation.
Details | |||||
---|---|---|---|---|---|
Parameters |
|
||||
Return Values |
|
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.
Details | |||||||
---|---|---|---|---|---|---|---|
Parameters |
|
otIp4CidrFromString
otError otIp4CidrFromString( const char *aString, otIp4Cidr *aCidr )
Converts a human-readable IPv4 CIDR string into a binary representation.
Details | |||||
---|---|---|---|---|---|
Parameters |
|
||||
Return Values |
|
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.
Details | |||||||
---|---|---|---|---|---|---|---|
Parameters |
|
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.
Details | |||||||
---|---|---|---|---|---|---|---|
Parameters |
|
otIp4FromIp4MappedIp6Address
otError otIp4FromIp4MappedIp6Address( const otIp6Address *aIp6Address, otIp4Address *aIp4Address )
Extracts the IPv4 address from a given IPv4-mapped IPv6 address.
An IPv4-mapped IPv6 address consists of an 80-bit prefix of zeros, the next 16 bits set to ones, and the remaining, least-significant 32 bits contain the IPv4 address, e.g., ::ffff:192.0.2.128
representing 192.0.2.128
.
Details | |||||
---|---|---|---|---|---|
Parameters |
|
||||
Return Values |
|
otIp4IsAddressEqual
bool otIp4IsAddressEqual( const otIp4Address *aFirst, const otIp4Address *aSecond )
Test if two IPv4 addresses are the same.
Details | |||||
---|---|---|---|---|---|
Parameters |
|
||||
Return Values |
|
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.
Details | |||||
---|---|---|---|---|---|
Parameters |
|
||||
Returns |
A pointer to the message buffer or NULL if no message buffers are available or parameters are invalid.
|
otNat64Send
otIp4ToIp4MappedIp6Address
void otIp4ToIp4MappedIp6Address( const otIp4Address *aIp4Address, otIp6Address *aIp6Address )
Converts a given IP4 address to an IPv6 address following the IPv4-mapped IPv6 address format.
Details | |||||
---|---|---|---|---|---|
Parameters |
|
otNat64ClearIp4Cidr
void otNat64ClearIp4Cidr( otInstance *aInstance )
Clears the CIDR used when setting the source address of the outgoing translated IPv4 packets.
Is available only when OPENTHREAD_CONFIG_NAT64_TRANSLATOR_ENABLE is enabled.
Details | |||
---|---|---|---|
Parameters |
|
otNat64SetIp4Cidr
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.
Details | |||||
---|---|---|---|---|---|
Parameters |
|
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.
Details | |||||
---|---|---|---|---|---|
Parameters |
|
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.
Details | |||||
---|---|---|---|---|---|
Parameters |
|
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.
Details | |||||||
---|---|---|---|---|---|---|---|
Parameters |
|
||||||
Return Values |
|
otNat64GetPrefixManagerState
otNat64State otNat64GetPrefixManagerState( otInstance *aInstance )
Gets the state of NAT64 prefix manager.
Available when OPENTHREAD_CONFIG_NAT64_BORDER_ROUTING_ENABLE
is enabled.
Details | |||||||||
---|---|---|---|---|---|---|---|---|---|
Parameters |
|
||||||||
Return Values |
|
otNat64GetTranslatorState
otNat64State otNat64GetTranslatorState( otInstance *aInstance )
Gets the state of NAT64 translator.
Available when OPENTHREAD_CONFIG_NAT64_TRANSLATOR_ENABLE
is enabled.
Details | |||||||
---|---|---|---|---|---|---|---|
Parameters |
|
||||||
Return Values |
|
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.
Details | |||||
---|---|---|---|---|---|
Parameters |
|
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.
Details | |||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Parameters |
|
||||||||||||
Return Values |
|
otNat64SetEnabled
void otNat64SetEnabled( otInstance *aInstance, bool aEnabled )
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.
Details | |||||
---|---|---|---|---|---|
Parameters |
|
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.
Is available only when OPENTHREAD_CONFIG_NAT64_TRANSLATOR_ENABLE is enabled.
Details | |||||
---|---|---|---|---|---|
Parameters |
|
||||
Return Values |
|
otNat64Send
otNat64SetReceiveIp4Callback
otNat64SetReceiveIp4Callback
void otNat64SetReceiveIp4Callback( otInstance *aInstance, otNat64ReceiveIp4Callback aCallback, void *aContext )
Registers a callback to provide received IPv4 datagrams.
Details | |||||||
---|---|---|---|---|---|---|---|
Parameters |
|
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.
Details | |||||||
---|---|---|---|---|---|---|---|
Parameters |
|
||||||
Returns |
OT_ERROR_NONE Successfully synthesized the IPv6 address from NAT64 prefix and IPv4 address.
|
||||||
Returns |
OT_ERROR_INVALID_STATE No valid NAT64 prefix in the network data.
|
Macros
OT_IP4_ADDRESS_SIZE
OT_IP4_ADDRESS_SIZE 4
Size of an IPv4 address (bytes)
OT_IP4_ADDRESS_STRING_SIZE
OT_IP4_ADDRESS_STRING_SIZE 17
Length of 000.000.000.000 plus a suffix NUL.
OT_IP4_CIDR_STRING_SIZE
OT_IP4_CIDR_STRING_SIZE 20
Length of 000.000.000.000/00 plus a suffix NUL.
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.