# 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 ||
|---|---|
| `https://openthread.io/reference/group/api-nat64#group__api-nat64_1gaaf5dccc497d3e35d87e644e5ff4a00de{ https://openthread.io/reference/group/api-nat64#group__api-nat64_1ggaaf5dccc497d3e35d87e644e5ff4a00deac7c049f2c74ad43bc9d223397faea2d2 = 0, https://openthread.io/reference/group/api-nat64#group__api-nat64_1ggaaf5dccc497d3e35d87e644e5ff4a00dea6144b968cfa2c9fcb404438bfe09e409, https://openthread.io/reference/group/api-nat64#group__api-nat64_1ggaaf5dccc497d3e35d87e644e5ff4a00dea37d9cbfcc59664c0bde79ec8e994d254, https://openthread.io/reference/group/api-nat64#group__api-nat64_1ggaaf5dccc497d3e35d87e644e5ff4a00dea1f88aa30726c9a6dc0b3315fde3e00e6 }` | enumPacket drop reasons. |
| `https://openthread.io/reference/group/api-nat64#group__api-nat64_1ga5cc2b8323e1efdfdfb8dab1a15ae165a{ https://openthread.io/reference/group/api-nat64#group__api-nat64_1gga5cc2b8323e1efdfdfb8dab1a15ae165aa2d03c8e4bf0bd74a29023aa54e6e0068 = 0, https://openthread.io/reference/group/api-nat64#group__api-nat64_1gga5cc2b8323e1efdfdfb8dab1a15ae165aa27c824937ddb24e903e1a8e1198ae09f, https://openthread.io/reference/group/api-nat64#group__api-nat64_1gga5cc2b8323e1efdfdfb8dab1a15ae165aa6b3747602302cd1a5aba9874b62f5eaf, https://openthread.io/reference/group/api-nat64#group__api-nat64_1gga5cc2b8323e1efdfdfb8dab1a15ae165aa2e3c2ea0f0e41104a06a20dd722e1c64 }` | enumStates of NAT64. |
| ### Typedefs ||
|---|---|
| `https://openthread.io/reference/group/api-nat64#group__api-nat64_1gac75eed539c0f1de9b09958728ee36e29` | typedef `struct https://openthread.io/reference/struct/ot-ip4-address` Represents an IPv4 address. |
| `https://openthread.io/reference/group/api-nat64#group__api-nat64_1ga0abd6aadb4c2611bcff39e2f77113b42` | typedef `struct https://openthread.io/reference/struct/ot-ip4-cidr` |
| `https://openthread.io/reference/group/api-nat64#group__api-nat64_1gaf69c326c511fda4eccb0d2f14a0d868b` | typedef `struct https://openthread.io/reference/struct/ot-nat64-address-mapping` Represents an address mapping record for NAT64. |
| `https://openthread.io/reference/group/api-nat64#group__api-nat64_1ga13c060c97fab82e9bbb13ac8deecf82e` | typedef `struct https://openthread.io/reference/struct/ot-nat64-address-mapping-iterator` Used to iterate through NAT64 address mappings. |
| `https://openthread.io/reference/group/api-nat64#group__api-nat64_1ga09eea2c3f9f0ca1f2737ab667c4bf24b` | typedef `struct https://openthread.io/reference/struct/ot-nat64-counters` Represents the counters for NAT64. |
| `https://openthread.io/reference/group/api-nat64#group__api-nat64_1gaed32c48714cade445bafddf040611bd2` | typedef `enum https://openthread.io/reference/group/api-nat64#group__api-nat64_1gaaf5dccc497d3e35d87e644e5ff4a00de` Packet drop reasons. |
| `https://openthread.io/reference/group/api-nat64#group__api-nat64_1gaffcfa8f183db82d2b01736bb507c4318` | typedef `struct https://openthread.io/reference/struct/ot-nat64-error-counters` Represents the counters of dropped packets due to errors when handling NAT64 packets. |
| `https://openthread.io/reference/group/api-nat64#group__api-nat64_1gaa57c2633602c2b8f9892053c95db0407` | typedef `struct https://openthread.io/reference/struct/ot-nat64-protocol-counters` Represents the counters for the protocols supported by NAT64. |
| `https://openthread.io/reference/group/api-nat64#group__api-nat64_1gae2eb6986309b8ed949a2471685d7039f)(otMessage *aMessage, void *aContext)` | typedef `void(*` Pointer is called when an IPv4 datagram (translated by NAT64 translator) is received. |
| ### Variables ||
|---|---|
| `https://openthread.io/reference/group/api-nat64#group__api-nat64_1ga09053736c540a77b46f90ae98676d354` | `https://openthread.io/reference/group/plat-toolchain#group__plat-toolchain_1gaba6ad63129c3a790957a9b149a65891b struct https://openthread.io/reference/struct/ot-ip4-address` |
| ### Functions ||
|---|---|
| `https://openthread.io/reference/group/api-nat64#group__api-nat64_1ga4162b2702e8a1e66557ce6fc28cc8279(const char *aString, https://openthread.io/reference/struct/ot-ip4-address *aAddress)` | `https://openthread.io/reference/group/api-error#group__api-error_1gabaaa90aaa35da8f9d394a227a23a6a49` Converts a human-readable IPv4 address string into a binary representation. |
| `https://openthread.io/reference/group/api-nat64#group__api-nat64_1ga906a998bbe3def7b54fccfec3d6df3db(const https://openthread.io/reference/struct/ot-ip4-address *aAddress, char *aBuffer, uint16_t aSize)` | `void` Converts the address to a string. |
| `https://openthread.io/reference/group/api-nat64#group__api-nat64_1ga4df12851a9c7a7af87f9ebee52017473(const char *aString, https://openthread.io/reference/struct/ot-ip4-cidr *aCidr)` | `https://openthread.io/reference/group/api-error#group__api-error_1gabaaa90aaa35da8f9d394a227a23a6a49` Converts a human-readable IPv4 CIDR string into a binary representation. |
| `https://openthread.io/reference/group/api-nat64#group__api-nat64_1gac603ab61facd4cc4434023c3ca2da93a(const https://openthread.io/reference/struct/ot-ip4-cidr *aCidr, char *aBuffer, uint16_t aSize)` | `void` Converts the IPv4 CIDR to a string. |
| `https://openthread.io/reference/group/api-nat64#group__api-nat64_1ga8295069319ab30e59e49ce085c6b575c(uint8_t aPrefixLength, const https://openthread.io/reference/struct/ot-ip6-address *aIp6Address, https://openthread.io/reference/struct/ot-ip4-address *aIp4Address)` | `void` Set `aIp4Address` by performing NAT64 address translation from `aIp6Address` as specified in RFC 6052. |
| `https://openthread.io/reference/group/api-nat64#group__api-nat64_1ga0bd3b88a623d43431d527e8f20570c88(const https://openthread.io/reference/struct/ot-ip6-address *aIp6Address, https://openthread.io/reference/struct/ot-ip4-address *aIp4Address)` | `https://openthread.io/reference/group/api-error#group__api-error_1gabaaa90aaa35da8f9d394a227a23a6a49` Extracts the IPv4 address from a given IPv4-mapped IPv6 address. |
| `https://openthread.io/reference/group/api-nat64#group__api-nat64_1ga6fa4f22d9a61869dcd5fc45442d84a79(const https://openthread.io/reference/struct/ot-ip4-address *aFirst, const https://openthread.io/reference/struct/ot-ip4-address *aSecond)` | `bool` Test if two IPv4 addresses are the same. |
| `https://openthread.io/reference/group/api-nat64#group__api-nat64_1ga5a27bbc466e570815136c754295e147c(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, const https://openthread.io/reference/struct/ot-message-settings *aSettings)` | `https://openthread.io/reference/group/api-message#group__api-message_1ga42d128a0a9ad58de0eb79673843c2955 *` Allocate a new message buffer for sending an IPv4 message to the NAT64 translator. |
| `https://openthread.io/reference/group/api-nat64#group__api-nat64_1ga4c8913b05d43858bd99538e152525e5c(const https://openthread.io/reference/struct/ot-ip4-address *aIp4Address, https://openthread.io/reference/struct/ot-ip6-address *aIp6Address)` | `void` Converts a given IP4 address to an IPv6 address following the IPv4-mapped IPv6 address format. |
| `https://openthread.io/reference/group/api-nat64#group__api-nat64_1gab1a06e7af8082b7b3b4e8c0895f3c6ae(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance)` | `void` Clears the CIDR used when setting the source address of the outgoing translated IPv4 packets. |
| `https://openthread.io/reference/group/api-nat64#group__api-nat64_1gaa9e2fecc83a9eda09ee29ce44c19b14a(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, https://openthread.io/reference/struct/ot-ip4-cidr *aCidr)` | `https://openthread.io/reference/group/api-error#group__api-error_1gabaaa90aaa35da8f9d394a227a23a6a49` Gets the IPv4 CIDR configured in the NAT64 translator. |
| `https://openthread.io/reference/group/api-nat64#group__api-nat64_1ga51f65def7773ec6c21c9faf43c56b3d1(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, https://openthread.io/reference/struct/ot-nat64-protocol-counters *aCounters)` | `void` Gets NAT64 translator counters. |
| `https://openthread.io/reference/group/api-nat64#group__api-nat64_1ga6316a9b9cb570390a6af5cbd053da430(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, https://openthread.io/reference/struct/ot-nat64-error-counters *aCounters)` | `void` Gets the NAT64 translator error counters. |
| `https://openthread.io/reference/group/api-nat64#group__api-nat64_1gade0ffbf9542d5971301457d9a25e6adf(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, https://openthread.io/reference/struct/ot-ip6-prefix *aPrefix)` | `https://openthread.io/reference/group/api-error#group__api-error_1gabaaa90aaa35da8f9d394a227a23a6a49` Gets the IPv6 prefix configured in the NAT64 translator. |
| `https://openthread.io/reference/group/api-nat64#group__api-nat64_1ga241b4a01fdb1b32a142e1457aff69ea1(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, https://openthread.io/reference/struct/ot-nat64-address-mapping-iterator *aIterator, https://openthread.io/reference/struct/ot-nat64-address-mapping *aMapping)` | `https://openthread.io/reference/group/api-error#group__api-error_1gabaaa90aaa35da8f9d394a227a23a6a49` Gets the next AddressMapping info (using an iterator). |
| `https://openthread.io/reference/group/api-nat64#group__api-nat64_1ga0c0591588154cc0b1b3dee877430f679(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance)` | `https://openthread.io/reference/group/api-nat64#group__api-nat64_1ga5cc2b8323e1efdfdfb8dab1a15ae165a` Gets the state of NAT64 prefix manager. |
| `https://openthread.io/reference/group/api-nat64#group__api-nat64_1ga0a53caf10c5d8dd85b26711c35f5db90(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance)` | `https://openthread.io/reference/group/api-nat64#group__api-nat64_1ga5cc2b8323e1efdfdfb8dab1a15ae165a` Gets the state of NAT64 translator. |
| `https://openthread.io/reference/group/api-nat64#group__api-nat64_1ga6ccdefe59eb89f72755b52df94c27e9a(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, https://openthread.io/reference/struct/ot-nat64-address-mapping-iterator *aIterator)` | `void` Initializes an `https://openthread.io/reference/struct/ot-nat64-address-mapping-iterator`. |
| `https://openthread.io/reference/group/api-nat64#group__api-nat64_1ga0e3a447f85951ab2941bb895fa883936(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, https://openthread.io/reference/group/api-message#group__api-message_1ga42d128a0a9ad58de0eb79673843c2955 *aMessage)` | `https://openthread.io/reference/group/api-error#group__api-error_1gabaaa90aaa35da8f9d394a227a23a6a49` Translates an IPv4 datagram to an IPv6 datagram and sends via the Thread interface. |
| `https://openthread.io/reference/group/api-nat64#group__api-nat64_1ga090b96c16818082842bec7514977efea(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, bool aEnabled)` | `void` Enable or disable NAT64 functions. |
| `https://openthread.io/reference/group/api-nat64#group__api-nat64_1gaa7ddbd33ed8d672668252dea66b2f9be(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, const https://openthread.io/reference/struct/ot-ip4-cidr *aCidr)` | `https://openthread.io/reference/group/api-error#group__api-error_1gabaaa90aaa35da8f9d394a227a23a6a49` Sets the CIDR used when setting the source address of the outgoing translated IPv4 packets. |
| `https://openthread.io/reference/group/api-nat64#group__api-nat64_1ga81d2eba5969fa37a93e6898747224f2d(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, https://openthread.io/reference/group/api-nat64#group__api-nat64_1gae2eb6986309b8ed949a2471685d7039f aCallback, void *aContext)` | `void` Registers a callback to provide received IPv4 datagrams. |
| `https://openthread.io/reference/group/api-nat64#group__api-nat64_1ga0e45514d52fa29a8a3082516a1d0c289(https://openthread.io/reference/group/api-nat64#group__api-nat64_1ga5cc2b8323e1efdfdfb8dab1a15ae165a aState)` | `const char *` Converts a given `otNat64State` to a human-readable string. |
| `https://openthread.io/reference/group/api-nat64#group__api-nat64_1ga4951d0a9e6c9442414ba21612e1a87a4(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, const https://openthread.io/reference/struct/ot-ip4-address *aIp4Address, https://openthread.io/reference/struct/ot-ip6-address *aIp6Address)` | `https://openthread.io/reference/group/api-error#group__api-error_1gabaaa90aaa35da8f9d394a227a23a6a49` 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 ||
|---|---|
| `https://openthread.io/reference/group/api-nat64#group__api-nat64_1ga85ab8918bdb4d8a9a7d1696213885832 4` | Size of an IPv4 address (bytes) |
| `https://openthread.io/reference/group/api-nat64#group__api-nat64_1gacae501db1b563c86c8c98422223c644f 17` | Length of 000.000.000.000 plus a suffix NUL. |
| `https://openthread.io/reference/group/api-nat64#group__api-nat64_1ga930852e9bf1b929347d7787720c515e7 20` | Length of 000.000.000.000/00 plus a suffix NUL. |
| ### Structs ||
|---|---|
| [otIp4Address](https://openthread.io/reference/struct/ot-ip4-address) | Represents an IPv4 address. |
| [otIp4Cidr](https://openthread.io/reference/struct/ot-ip4-cidr) | Represents an IPv4 CIDR block. |
| [otNat64AddressMapping](https://openthread.io/reference/struct/ot-nat64-address-mapping) | Represents an address mapping record for NAT64. |
| [otNat64AddressMappingIterator](https://openthread.io/reference/struct/ot-nat64-address-mapping-iterator) | Used to iterate through NAT64 address mappings. |
| [otNat64Counters](https://openthread.io/reference/struct/ot-nat64-counters) | Represents the counters for NAT64. |
| [otNat64ErrorCounters](https://openthread.io/reference/struct/ot-nat64-error-counters) | Represents the counters of dropped packets due to errors when handling NAT64 packets. |
| [otNat64ProtocolCounters](https://openthread.io/reference/struct/ot-nat64-protocol-counters) | Represents the counters for the protocols supported by NAT64. |
| ### Unions ||
|---|---|
| [otIp4Address::OT_TOOL_PACKED_FIELD](https://openthread.io/reference/union/ot-ip4-address/o-t-t-o-o-l-p-a-c-k-e-d-f-i-e-l-d) | |
## 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
### otIp4Address
```
struct otIp4Address otIp4Address
```
Represents an IPv4 address.
### otIp4Cidr
```
struct otIp4Cidr otIp4Cidr
```
### otNat64AddressMapping
```
struct otNat64AddressMapping otNat64AddressMapping
```
Represents an address mapping record for NAT64.
> [!NOTE]
> **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
```
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 `https://openthread.io/reference/group/api-nat64#group__api-nat64_1ga6ccdefe59eb89f72755b52df94c27e9a`.
The member fields in this struct are for internal OpenThread stack use and should not be accessed directly.
### otNat64Counters
```
struct otNat64Counters otNat64Counters
```
Represents the counters for NAT64.
### otNat64DropReason
```
enum otNat64DropReason otNat64DropReason
```
Packet drop reasons.
### 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 `[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.
## 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 `[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.
Details 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 NULL). `[in] aSize` The size of `aBuffer` (in bytes).
### otIp4CidrFromString
```
otError otIp4CidrFromString(
const char *aString,
otIp4Cidr *aCidr
)
```
Converts a human-readable IPv4 CIDR string into a binary representation.
Details Parameters `[in] aString` A pointer to a NULL-terminated string. `[out] aCidr` A pointer to an IPv4 CIDR. Return Values `OT_ERROR_NONE` Successfully parsed the string. `OT_ERROR_INVALID_ARGS` Failed to parse the string.
### 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 `[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 NULL). `[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.
Details 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.
### 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 `[in] aIp6Address` An IPv6 address to extract IPv4 from. `[out] aIp4Address` An IPv4 address to output the extracted address. Return Values `OT_ERROR_NONE` Extracted the IPv4 address successfully. `aIp4Address` is updated. `OT_ERROR_PARSE` The `aIp6Address` does not follow the IPv4-mapped IPv6 address format.
### otIp4IsAddressEqual
```
bool otIp4IsAddressEqual(
const otIp4Address *aFirst,
const otIp4Address *aSecond
)
```
Test if two IPv4 addresses are the same.
Details 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]
> **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:**
[otNat64Send](https://openthread.io/reference/group/api-nat64#group__api-nat64_1ga0e3a447f85951ab2941bb895fa883936)
### 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 `[in] aIp4Address` An IPv4 address to convert. `[out] aIp6Address` An IPv6 address to set.
### 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.
> [!NOTE]
> **Note:** This function can be called at any time, but the NAT64 translator will be reset and all existing sessions will be expired when clearing the configured CIDR.
Details Parameters `[in] aInstance` A pointer to an OpenThread instance. **See also:**
[otNat64SetIp4Cidr](https://openthread.io/reference/group/api-nat64#group__api-nat64_1gaa7ddbd33ed8d672668252dea66b2f9be)
### 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 `[in] aInstance` A pointer to an OpenThread instance. `[out] aCidr` A pointer to an [otIp4Cidr](https://openthread.io/reference/struct/ot-ip4-cidr). 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.
Details Parameters `[in] aInstance` A pointer to an OpenThread instance. `[out] aCounters` A pointer to an `https://openthread.io/reference/struct/ot-nat64-counters` 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.
Details Parameters `[in] aInstance` A pointer to an OpenThread instance. `[out] aCounters` A pointer to an `https://openthread.io/reference/struct/ot-nat64-counters` where the counters of NAT64 translator will be placed.
### otNat64GetIp6Prefix
```
otError otNat64GetIp6Prefix(
otInstance *aInstance,
otIp6Prefix *aPrefix
)
```
Gets the IPv6 prefix configured in the NAT64 translator.
Available when `OPENTHREAD_CONFIG_NAT64_TRANSLATOR_ENABLE` is enabled.
Details Parameters `[in] aInstance` A pointer to an OpenThread instance. `[out] aPrefix` A pointer to an `https://openthread.io/reference/struct/ot-ip6-prefix` to output the prefix. Return Values `OT_ERROR_NONE` The prefix was successfully filled. `OT_ERROR_NOT_FOUND` The translator is not configured with an IPv6 prefix.
### 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 `[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. `[out] aMapping` A pointer to an `https://openthread.io/reference/struct/ot-nat64-address-mapping` 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.
Details 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.
Details 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 `https://openthread.io/reference/struct/ot-nat64-address-mapping-iterator`.
Available when `OPENTHREAD_CONFIG_NAT64_TRANSLATOR_ENABLE` is enabled.
An iterator MUST be initialized before it is used. An iterator can be initialized again to restart from the beginning of the mapping info list.
The iterator initialization time is used to report the `mRemainingTimeMs` in the `https://openthread.io/reference/struct/ot-nat64-address-mapping` retrieved when calling `https://openthread.io/reference/group/api-nat64#group__api-nat64_1ga241b4a01fdb1b32a142e1457aff69ea1` to iterate over the list. This ensures that all entry `mRemainingTimeMs` values are consistent and are from the same time origin, regardless of how or when `https://openthread.io/reference/group/api-nat64#group__api-nat64_1ga241b4a01fdb1b32a142e1457aff69ea1` is called.
Details Parameters `[in] aInstance` A pointer to 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.
Details 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 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 `[in] aInstance` A pointer to an OpenThread instance. `[in] aEnabled` A boolean to enable/disable the NAT64 functions **See also:**
[otNat64GetTranslatorState](https://openthread.io/reference/group/api-nat64#group__api-nat64_1ga0a53caf10c5d8dd85b26711c35f5db90)
[otNat64GetPrefixManagerState](https://openthread.io/reference/group/api-nat64#group__api-nat64_1ga0c0591588154cc0b1b3dee877430f679)
### 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.
> [!NOTE]
> **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.
> [!NOTE]
> **Note:** 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.
Details Parameters `[in] aInstance` A pointer to an OpenThread instance. `[in] aCidr` A pointer to an [otIp4Cidr](https://openthread.io/reference/struct/ot-ip4-cidr) 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:**
[otNat64Send](https://openthread.io/reference/group/api-nat64#group__api-nat64_1ga0e3a447f85951ab2941bb895fa883936)
[otNat64SetReceiveIp4Callback](https://openthread.io/reference/group/api-nat64#group__api-nat64_1ga81d2eba5969fa37a93e6898747224f2d)
### otNat64SetReceiveIp4Callback
```
void otNat64SetReceiveIp4Callback(
otInstance *aInstance,
otNat64ReceiveIp4Callback aCallback,
void *aContext
)
```
Registers a callback to provide received IPv4 datagrams.
Details 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] aContext` A pointer to application-specific context.
### otNat64StateToString
```
const char * otNat64StateToString(
otNat64State aState
)
```
Converts a given `otNat64State` to a human-readable string.
Details Parameters `[in] aState` The NAT64 state. **Returns** The string representation of `aState`.
### 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 `[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. **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](https://github.com/openthread/openthread/tree/main/include/openthread).
For more information, or to contribute to our documentation, refer to
[Resources](https://openthread.io/resources).