NAT64

這個模組包含邊界路由器上的 NAT64 函式函式和結構。

摘要

啟用 OPENTHREAD_CONFIG_NAT64_BORDER_ROUTING_ENABLE 後才能使用這些函式。

列舉
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
} 		列舉
封包遺失原因。
otNat64State{
  OT_NAT64_STATE_DISABLED = 0,
  OT_NAT64_STATE_NOT_RUNNING,
  OT_NAT64_STATE_IDLE,
  OT_NAT64_STATE_ACTIVE
} 		列舉
NAT64 的狀態。

Typedefs
otIp4Address typedef
struct otIp4Address
代表 IPv4 位址。
otIp4Cidr typedef
struct otIp4Cidr
otNat64AddressMapping typedef
代表 NAT64 的地址對應記錄。
otNat64AddressMappingIterator typedef
用於疊代進行 NAT64 位址對應。
otNat64Counters typedef
代表 NAT64 的計數器。
otNat64DropReason typedef
封包遺失原因。
otNat64ErrorCounters typedef
代表在處理 NAT64 封包時發生錯誤而遭捨棄封包的計數器。
otNat64ProtocolCounters typedef
代表 NAT64 支援的通訊協定計數器。
otNat64ReceiveIp4Callback)(otMessage *aMessage, void *aContext) typedef
void(*
接收到 IPv4 資料元 (由 NAT64 轉譯器翻譯) 時，就會呼叫指標。

Variables
OT_TOOL_PACKED_END

函式
otIp4AddressFromString(const char *aString, otIp4Address *aAddress)
將使用者可理解的 IPv4 位址字串轉換成二進位表示法。
otIp4AddressToString(const otIp4Address *aAddress, char *aBuffer, uint16_t aSize)
void
將地址轉換成字串。
otIp4CidrFromString(const char *aString, otIp4Cidr *aCidr)
將使用者可理解的 IPv4 CIDR 字串轉換為二進位表示法。
otIp4CidrToString(const otIp4Cidr *aCidr, char *aBuffer, uint16_t aSize)
void
將 IPv4 CIDR 轉換為字串。
otIp4ExtractFromIp6Address(uint8_t aPrefixLength, const otIp6Address *aIp6Address, otIp4Address *aIp4Address)
void
按照 RFC 6052 指定，從 aIp6Address 執行 NAT64 位址轉譯以設定 aIp4Address。
otIp4IsAddressEqual(const otIp4Address *aFirst, const otIp4Address *aSecond)
bool
測試兩個 IPv4 位址是否相同。
otIp4NewMessage(otInstance *aInstance, const otMessageSettings *aSettings)
分配新的訊息緩衝區，以便傳送 IPv4 訊息給 NAT64 翻譯器。
otNat64GetCidr(otInstance *aInstance, otIp4Cidr *aCidr)
取得在 NAT64 轉譯器中設定的 IPv4 CIDR。
otNat64GetCounters(otInstance *aInstance, otNat64ProtocolCounters *aCounters)
void
取得 NAT64 翻譯計數器。
otNat64GetErrorCounters(otInstance *aInstance, otNat64ErrorCounters *aCounters)
void
取得 NAT64 翻譯器錯誤計數器。
otNat64GetNextAddressMapping(otInstance *aInstance, otNat64AddressMappingIterator *aIterator, otNat64AddressMapping *aMapping)
取得下一個 AddressMapping 資訊 (使用疊代器)。
otNat64GetPrefixManagerState(otInstance *aInstance)
取得 NAT64 前置字串管理員的狀態。
otNat64GetTranslatorState(otInstance *aInstance)
取得 NAT64 翻譯工具的狀態。
otNat64InitAddressMappingIterator(otInstance *aInstance, otNat64AddressMappingIterator *aIterator)
void
otNat64Send(otInstance *aInstance, otMessage *aMessage)
將 IPv4 資料元轉譯為 IPv6 資料元，並透過 Thread 介面傳送。
otNat64SetEnabled(otInstance *aInstance, bool aEnabled)
void
啟用或停用 NAT64 函式。
otNat64SetIp4Cidr(otInstance *aInstance, const otIp4Cidr *aCidr)
設定傳出已翻譯 IPv4 封包的來源位址時，使用的 CIDR。
otNat64SetReceiveIp4Callback(otInstance *aInstance, otNat64ReceiveIp4Callback aCallback, void *aContext)
void
註冊回呼以提供接收的 IPv4 資料元。
otNat64SynthesizeIp6Address(otInstance *aInstance, const otIp4Address *aIp4Address, otIp6Address *aIp6Address)
設定 IPv6 位址，方法是根據偏好的 NAT64 前置字串和 RFC 6052 中指定的 IPv4 位址執行 NAT64 位址轉譯。

結構
otIp4Address

代表 IPv4 位址。
otIp4Cidr

代表 IPv4 CIDR 區塊。
otNat64AddressMapping

代表 NAT64 的地址對應記錄。
otNat64AddressMappingIterator

用於疊代進行 NAT64 位址對應。
otNat64Counters

代表 NAT64 的計數器。
otNat64ErrorCounters

代表在處理 NAT64 封包時發生錯誤而遭捨棄封包的計數器。
otNat64ProtocolCounters

代表 NAT64 支援的通訊協定計數器。

工會
otIp4Address::OT_TOOL_PACKED_FIELD

列舉

otNat64DropReason

 otNat64DropReason

封包遺失原因。

屬性
OT_NAT64_DROP_REASON_ILLEGAL_PACKET

封包因無法剖析資料元而遺失。
OT_NAT64_DROP_REASON_NO_MAPPING

找不到對應或對應集區用盡，因此封包遺失。
OT_NAT64_DROP_REASON_UNKNOWN

封包遺失原因不明。
OT_NAT64_DROP_REASON_UNSUPPORTED_PROTO

封包因不支援的 IP 通訊協定而遺失。

otNat64State

 otNat64State

NAT64 的狀態。

屬性
OT_NAT64_STATE_ACTIVE

BR 正發布 NAT64 前置字串和/或翻譯封包。
OT_NAT64_STATE_DISABLED

NAT64 已停用。
OT_NAT64_STATE_IDLE

已啟用 NAT64，但這個 BR 並非有效的 NAT64 BR。
OT_NAT64_STATE_NOT_RUNNING

已啟用 NAT64，但一或多個 NAT64 依附元件並未執行。

Typedefs

otIp4Address

struct otIp4Address otIp4Address

代表 IPv4 位址。

otIp4Cidr

struct otIp4Cidr otIp4Cidr

otNat64AddressMapping

struct otNat64AddressMapping otNat64AddressMapping

代表 NAT64 的地址對應記錄。

otNat64AddressMappingIterator

struct otNat64AddressMappingIterator otNat64AddressMappingIterator

用於疊代進行 NAT64 位址對應。

這個類型的欄位不透明 (僅供 OpenThread 核心使用)，因此呼叫端不應存取或使用。

使用疊代器之前，必須先使用 otNat64AddressMappingIteratorInit() 進行初始化。

otNat64Counters

struct otNat64Counters otNat64Counters

代表 NAT64 的計數器。

otNat64DropReason

enum otNat64DropReason otNat64DropReason

封包遺失原因。

otNat64ErrorCounters

struct otNat64ErrorCounters otNat64ErrorCounters

代表在處理 NAT64 封包時發生錯誤而遭捨棄封包的計數器。

otNat64ProtocolCounters

struct otNat64ProtocolCounters otNat64ProtocolCounters

代表 NAT64 支援的通訊協定計數器。

otNat64ReceiveIp4Callback

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

接收到 IPv4 資料元 (由 NAT64 轉譯器翻譯) 時，就會呼叫指標。

詳細說明
參數
[in] aMessage
指向包含已收到 IPv6 資料元的訊息緩衝區指標。這個函式會將 aMessage 的擁有權轉移給回呼的接收端。處理回呼後，訊息的接收端應會釋放訊息。
[in] aContext
指向應用程式特定背景資訊的指標。

Variables

OT_TOOL_PACKED_END

OT_TOOL_PACKED_BEGIN struct otIp4Address OT_TOOL_PACKED_END

函式

otIp4AddressFromString

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

將使用者可理解的 IPv4 位址字串轉換成二進位表示法。

詳細說明
參數
[in] aString
指向以 NULL 結尾字串的指標。
[out] aAddress
指向 IPv4 位址的指標。
傳回值
OT_ERROR_NONE
已成功剖析字串。
OT_ERROR_INVALID_ARGS
無法剖析字串。

otIp4AddressToString

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

將地址轉換成字串。

字串格式使用地址中的四位元組 (4 個位元組) 標記法 (例如「127.0.0.1」)。

如果產生的字串不符合 aBuffer (在其 aSize 字元之內) 的大小，系統將截斷字串，但輸出的字串一律會是空值。

詳細說明
參數
[in] aAddress
指向 IPv4 位址的指標 (不得為空值)。
[out] aBuffer
用來輸出字串的字元陣列指標 (不得為 nullptr)。
[in] aSize
aBuffer 的大小 (以位元組為單位)。

otIp4CidrFromString

otError otIp4CidrFromString(
  const char *aString,
  otIp4Cidr *aCidr
)

將使用者可理解的 IPv4 CIDR 字串轉換為二進位表示法。

詳細說明
參數
[in] aString
指向以 NULL 結尾字串的指標。
[out] aCidr
指向 IPv4 CIDR 的指標。
傳回值
OT_ERROR_NONE
已成功剖析字串。
OT_ERROR_INVALID_ARGS
無法剖析字串。

otIp4CidrToString

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

將 IPv4 CIDR 轉換為字串。

字串格式使用地址中的四位元組標記法，再加上前置字元長度 (例如「127.0.0.1/32」)。

如果產生的字串不符合 aBuffer (在其 aSize 字元之內) 的大小，系統將截斷字串，但輸出的字串一律會是空值。

詳細說明
參數
[in] aCidr
指向 IPv4 CIDR 的指標 (不得為空值)。
[out] aBuffer
用來輸出字串的字元陣列指標 (不得為 nullptr)。
[in] aSize
aBuffer 的大小 (以位元組為單位)。

otIp4ExtractFromIp6Address

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

按照 RFC 6052 指定，從 aIp6Address 執行 NAT64 位址轉譯以設定 aIp4Address。

NAT64 aPrefixLength 必須是下列其中一個值：32、40、48、56、64 或 96，否則這個方法的行為並未定義。

詳細說明
參數
[in] aPrefixLength
用於 IPv4/IPv6 翻譯的前置字串長度。
[in] aIp6Address
指向 IPv6 位址的指標。
[out] aIp4Address
輸出 IPv4 位址的指標。

otIp4IsAddressEqual

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

測試兩個 IPv4 位址是否相同。

詳細說明
參數
[in] aFirst
指向要比較的第一個 IPv4 位址的指標。
[in] aSecond
指標，指向要比較的第二個 IPv4 位址。
傳回值
TRUE
這兩個 IPv4 位址相同。
FALSE
這兩個 IPv4 位址不同。

otIp4NewMessage

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

分配新的訊息緩衝區，以便傳送 IPv4 訊息給 NAT64 翻譯器。

這個函式配置的訊息緩衝區將保留 20 個位元組 (IPv6 標頭大小與 IPv4 標頭大小不同)。

啟用 OPENTHREAD_CONFIG_NAT64_TRANSLATOR_ENABLE 後即可使用，

詳細說明
參數
[in] aInstance
指向 OpenThread 執行個體的指標。
[in] aSettings
指向訊息設定或 NULL 用來設置預設設定的指標。
傳回
如果沒有可用訊息緩衝區或參數無效，這個指標指向訊息緩衝區或 NULL。
另請參閱：
otNat64Send

otNat64GetCidr

otError otNat64GetCidr(
  otInstance *aInstance,
  otIp4Cidr *aCidr
)

取得在 NAT64 轉譯器中設定的 IPv4 CIDR。

啟用 OPENTHREAD_CONFIG_NAT64_TRANSLATOR_ENABLE 後即可使用，

詳細說明
參數
[in] aInstance
指向 OpenThread 執行個體的指標。
[out] aCidr
指向 otIp4Cidr 的指標。將填入 CIDR 的位置。

otNat64GetCounters

void otNat64GetCounters(
  otInstance *aInstance,
  otNat64ProtocolCounters *aCounters
)

取得 NAT64 翻譯計數器。

計數器是從執行個體初始化開始計算。

啟用 OPENTHREAD_CONFIG_NAT64_TRANSLATOR_ENABLE 後即可使用，

詳細說明
參數
[in] aInstance
指向 OpenThread 執行個體的指標。
[out] aCounters
指向 otNat64Counters 的指標，其中會放置 NAT64 翻譯器的計數器。

otNat64GetErrorCounters

void otNat64GetErrorCounters(
  otInstance *aInstance,
  otNat64ErrorCounters *aCounters
)

取得 NAT64 翻譯器錯誤計數器。

當 OpenThread 執行個體初始化時，計數器會初始化為零。

詳細說明
參數
[in] aInstance
指向 OpenThread 執行個體的指標。
[out] aCounters
指向 otNat64Counters 的指標，其中會放置 NAT64 翻譯器的計數器。

otNat64GetNextAddressMapping

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

取得下一個 AddressMapping 資訊 (使用疊代器)。

啟用 OPENTHREAD_CONFIG_NAT64_TRANSLATOR_ENABLE 後即可使用，

詳細說明
參數
[in] aInstance
指向 OpenThread 執行個體的指標。
[in,out] aIterator
指向疊代器的指標。成功後，疊代器將更新為指向下一個 NAT64 位址對應記錄。如要取得第一個項目，疊代器應設為 OT_NAT64_ADDRESS_MAPPING_ITERATOR_INIT。
[out] aMapping
指向 otNat64AddressMapping 的指標，其中會放置下一個 NAT64 位址對應記錄的資訊 (成功時)。
傳回值
OT_ERROR_NONE
已成功找到下一個 NAT64 位址對應資訊 (已成功更新「aMapping」)。
OT_ERROR_NOT_FOUND
找不到後續的 NAT64 位址對應資訊。

otNat64GetPrefixManagerState

otNat64State otNat64GetPrefixManagerState(
  otInstance *aInstance
)

取得 NAT64 前置字串管理員的狀態。

啟用 OPENTHREAD_CONFIG_NAT64_BORDER_ROUTING_ENABLE 後即可使用，

詳細說明
參數
[in] aInstance
指向 OpenThread 執行個體的指標。
傳回值
OT_NAT64_STATE_DISABLED
NAT64 前置字串管理員已停用。
OT_NAT64_STATE_NOT_RUNNING
NAT64 前置字串管理員已啟用，但目前並未執行 (因為轉送管理員並未執行)。
OT_NAT64_STATE_IDLE
NAT64 前置字串管理員已啟用，但尚未發布 NAT64 前置字串。通常發生在另一個邊界路由器發布了優先順序較高的 NAT64 前置字串時。
OT_NAT64_STATE_ACTIVE
已啟用 NAT64 前置字串管理員，並會將 NAT64 前置字串發布至 Thread 網路。

otNat64GetTranslatorState

otNat64State otNat64GetTranslatorState(
  otInstance *aInstance
)

取得 NAT64 翻譯工具的狀態。

啟用 OPENTHREAD_CONFIG_NAT64_TRANSLATOR_ENABLE 後即可使用，

詳細說明
參數
[in] aInstance
指向 OpenThread 執行個體的指標。
傳回值
OT_NAT64_STATE_DISABLED
NAT64 翻譯器已停用。
OT_NAT64_STATE_NOT_RUNNING
已啟用 NAT64 翻譯器，但翻譯器並未設定有效的 NAT64 前置字串和 CIDR。
OT_NAT64_STATE_ACTIVE
已啟用 NAT64 翻譯工具，並正在翻譯封包。

otNat64InitAddressMappingIterator

void otNat64InitAddressMappingIterator(
  otInstance *aInstance,
  otNat64AddressMappingIterator *aIterator
)

初始化 otNat64AddressMappingIterator。

疊代器「必須」初始化才能使用。

可以再次初始化疊代器，以便從對應資訊的開頭處重新啟動。

詳細說明
參數
[in] aInstance
OpenThread 執行個體。
[out] aIterator
指向要初始化的疊代器指標。

otNat64Send

otError otNat64Send(
  otInstance *aInstance,
  otMessage *aMessage
)

將 IPv4 資料元轉譯為 IPv6 資料元，並透過 Thread 介面傳送。

來電者會在撥打這通電話時轉移「aMessage」的擁有權。處理完成時，OpenThread 會釋放 aMessage，包括傳回 OT_ERROR_NONE 以外的值時。

詳細說明
參數
[in] aInstance
指向 OpenThread 執行個體的指標。
[in] aMessage
指向包含 IPv4 資料元的訊息緩衝區指標。
傳回值
OT_ERROR_NONE
已成功處理訊息。
OT_ERROR_DROP
郵件格式正確，但因封包處理規則而無法完整處理。
OT_ERROR_NO_BUFS
處理資料元時無法分配必要的訊息緩衝區。
OT_ERROR_NO_ROUTE
沒有通往主機的路由。
OT_ERROR_INVALID_SOURCE_ADDRESS
來源位址無效，例如任意傳播位址或多點傳播位址。
OT_ERROR_PARSE
處理訊息時，標頭格式有誤。

otNat64SetEnabled

void otNat64SetEnabled(
  otInstance *aInstance,
  bool aEnabled
)

啟用或停用 NAT64 函式。

注意：這包括 NAT64 翻譯器 (如果啟用 OPENTHREAD_CONFIG_NAT64_TRANSLATOR_ENABLE) 和 NAT64 前置字串管理員 (如果 OPENTHREAD_CONFIG_NAT64_BORDER_ROUTING_ENABLE 已啟用)。

啟用 OPENTHREAD_CONFIG_NAT64_TRANSLATOR_ENABLE 時，如果將設定設為 True，系統就會重設翻譯器中的對應資料表。

啟用 OPENTHREAD_CONFIG_NAT64_TRANSLATOR_ENABLE 或 OPENTHREAD_CONFIG_NAT64_BORDER_ROUTING_ENABLE 後即可使用。

詳細說明
參數
[in] aInstance
指向 OpenThread 執行個體的指標。
[in] aEnabled
用於啟用/停用 NAT64 函式的布林值
另請參閱：
otNat64GetTranslatorState
otNat64GetPrefixManagerState

otNat64SetIp4Cidr

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

設定傳出已翻譯 IPv4 封包的來源位址時，使用的 CIDR。

只有在啟用 OPENTHREAD_CONFIG_NAT64_TRANSLATOR_ENABLE 時才能使用。

詳細說明
參數
[in] aInstance
指向 OpenThread 執行個體的指標。
[in] aCidr
指向 NAT64 IPv4 CIDR 區塊的 otIp4Cidr 指標。
傳回值
OT_ERROR_INVALID_ARGS
指定的 CIDR 不是 NAT64 的有效 IPv4 CIDR。
OT_ERROR_NONE
已成功為 NAT64 設定 CIDR。
另請參閱：
otBorderRouterSend
otBorderRouterSetReceiveCallback

otNat64SetReceiveIp4Callback

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

註冊回呼以提供接收的 IPv4 資料元。

詳細說明
參數
[in] aInstance
指向 OpenThread 執行個體的指標。
[in] aCallback
指向接收 IPv4 資料元時呼叫的函式，或以 NULL 停用回呼時呼叫的函式。
[in] aContext
指向應用程式特定背景資訊的指標。

otNat64SynthesizeIp6Address

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

設定 IPv6 位址，方法是根據偏好的 NAT64 前置字串和 RFC 6052 中指定的 IPv4 位址執行 NAT64 位址轉譯。

詳細說明
參數
[in] aInstance
指向 OpenThread 執行個體的指標。
[in] aIp4Address
指標，指向要轉譯為 IPv6 的 IPv4 位址。
[out] aIp6Address
指向合成 IPv6 位址的指標。
傳回
OT_ERROR_NONE 成功根據 NAT64 前置字串和 IPv4 位址合成 IPv6 位址。
傳回
OT_ERROR_INVALID_STATE 網路資料中沒有有效的 NAT64 前置字串。

巨集

OT_IP4_ADDRESS_SIZE

 OT_IP4_ADDRESS_SIZE 4

IPv4 位址的大小 (位元組)

OT_IP4_ADDRESS_STRING_SIZE

 OT_IP4_ADDRESS_STRING_SIZE 17

長度為 000.000.000.000，加上後置字串 NUL。

OT_IP4_CIDR_STRING_SIZE

 OT_IP4_CIDR_STRING_SIZE 20

長度為 000.000.000.000/00，加上後置字串 NUL。

資源

OpenThread API 參考資料主題源自原始碼，請前往 GitHub 取得。如要瞭解詳情或對說明文件做出貢獻，請參閱資源。