透過集合功能整理內容 你可以依據偏好儲存及分類內容。

DNSv6

這個模組包含控制 DNS 通訊的函式。

摘要

您必須啟用 OPENTHREAD_CONFIG_DNS_CLIENT_ENABLE 功能,才能使用這個模組中的函式。

列舉

otDnsNat64Mode{
  OT_DNS_NAT64_UNSPECIFIED = 0,
  OT_DNS_NAT64_ALLOW = 1,
  OT_DNS_NAT64_DISALLOW = 2
}
列舉
這個列舉類型代表 otDnsQueryConfig 中的 NAT64 模式,
otDnsRecursionFlag{
  OT_DNS_FLAG_UNSPECIFIED = 0,
  OT_DNS_FLAG_RECURSION_DESIRED = 1,
  OT_DNS_FLAG_NO_RECURSION = 2
}
列舉
這個列舉類型代表 otDnsQueryConfig 中的「週期性」 (RD) 旗標,

Typedefs

otDnsAddressCallback)(otError aError, const otDnsAddressResponse *aResponse, void *aContext) typedef
void(*
當收到地址解析查詢的 DNS 回應時,會呼叫此函式指標。
otDnsAddressResponse typedef
這種類型是以不透明的表示法表示地址解析 DNS 查詢。
otDnsBrowseCallback)(otError aError, const otDnsBrowseResponse *aResponse, void *aContext) typedef
void(*
收到瀏覽 (服務執行個體列舉) 查詢的 DNS 回應時,系統會呼叫這個函式指標。
otDnsBrowseResponse typedef
此類型代表對瀏覽 (服務執行個體列舉) DNS 查詢的不透明表示法。
otDnsQueryConfig typedef
這個結構代表 DNS 查詢設定。
otDnsServiceCallback)(otError aError, const otDnsServiceResponse *aResponse, void *aContext) typedef
void(*
當收到服務執行個體解析查詢的 DNS 回應時,系統會呼叫此函式指標。
otDnsServiceInfo typedef
這個結構提供 DNS 服務執行個體的資訊。
otDnsServiceResponse typedef
這個類型是對服務執行個體解析 DNS 查詢的回應不透明表示法。
otDnsTxtEntry typedef
struct otDnsTxtEntry
這個結構代表一個代表鍵/值組合的 TXT 記錄項目 (RFC 6763 - 第 6.3 節)。
otDnsTxtEntryIterator typedef
這個結構代表 TXT 記錄完整 (鍵/值組合) 的疊代器。

Functions

otDnsAddressResponseGetAddress(const otDnsAddressResponse *aResponse, uint16_t aIndex, otIp6Address *aAddress, uint32_t *aTtl)
這個函式會接收與地址解析 DNS 回應相關聯的 IPv6 位址。
otDnsAddressResponseGetHostName(const otDnsAddressResponse *aResponse, char *aNameBuffer, uint16_t aNameBufferSize)
這個函式會取得與地址解析 DNS 回應相關聯的完整主機名稱。
otDnsBrowseResponseGetHostAddress(const otDnsBrowseResponse *aResponse, const char *aHostName, uint16_t aIndex, otIp6Address *aAddress, uint32_t *aTtl)
這個函式會從 DNS 瀏覽 (服務執行個體列舉) 回應取得主機 IPv6 位址。
otDnsBrowseResponseGetServiceInfo(const otDnsBrowseResponse *aResponse, const char *aInstanceLabel, otDnsServiceInfo *aServiceInfo)
這個函式會從 DNS 瀏覽 (服務執行個體列舉) 回應取得服務執行個體的資訊。
otDnsBrowseResponseGetServiceInstance(const otDnsBrowseResponse *aResponse, uint16_t aIndex, char *aLabelBuffer, uint8_t aLabelBufferSize)
這個函式會接收與 DNS 瀏覽 (服務執行個體列舉) 回應相關聯的服務執行個體。
otDnsBrowseResponseGetServiceName(const otDnsBrowseResponse *aResponse, char *aNameBuffer, uint16_t aNameBufferSize)
這個函式會取得與 DNS 瀏覽 (服務執行個體列舉) 回應相關聯的服務名稱。
otDnsClientBrowse(otInstance *aInstance, const char *aServiceName, otDnsBrowseCallback aCallback, void *aContext, const otDnsQueryConfig *aConfig)
這個函式會傳送指定服務名稱的 DNS 瀏覽 (服務執行個體列舉) 查詢。
otDnsClientGetDefaultConfig(otInstance *aInstance)
這項函式會取得 DNS 用戶端目前使用的預設查詢設定。
otDnsClientResolveAddress(otInstance *aInstance, const char *aHostName, otDnsAddressCallback aCallback, void *aContext, const otDnsQueryConfig *aConfig)
這個函式會傳送特定主機名稱的 AAAA (IPv6) 記錄地址解析 DNS 查詢。
otDnsClientResolveIp4Address(otInstance *aInstance, const char *aHostName, otDnsAddressCallback aCallback, void *aContext, const otDnsQueryConfig *aConfig)
這個函式會傳送特定主機名稱的 A (IPv4) 記錄位址解析 DNS 查詢。
otDnsClientResolveService(otInstance *aInstance, const char *aInstanceLabel, const char *aServiceName, otDnsServiceCallback aCallback, void *aContext, const otDnsQueryConfig *aConfig)
這個函式會針對特定服務執行個體傳送 DNS 服務執行個體解析查詢。
otDnsClientSetDefaultConfig(otInstance *aInstance, const otDnsQueryConfig *aConfig)
void
這個函式會在 DNS 用戶端上設定預設查詢設定。
otDnsGetNextTxtEntry(otDnsTxtEntryIterator *aIterator, otDnsTxtEntry *aEntry)
這個函式會從疊代器剖析 TXT 資料,並取得下一個 TXT 記錄項目 (鍵/值組合)。
otDnsInitTxtEntryIterator(otDnsTxtEntryIterator *aIterator, const uint8_t *aTxtData, uint16_t aTxtDataLength)
void
這個函式會初始化 TXT 記錄疊代器。
otDnsIsNameCompressionEnabled(void)
bool
這個函式可指出「DNS 名稱壓縮」模式是否已啟用。
otDnsServiceResponseGetHostAddress(const otDnsServiceResponse *aResponse, const char *aHostName, uint16_t aIndex, otIp6Address *aAddress, uint32_t *aTtl)
這項函式會從 DNS 服務執行個體解析回應取得主機 IPv6 位址。
otDnsServiceResponseGetServiceInfo(const otDnsServiceResponse *aResponse, otDnsServiceInfo *aServiceInfo)
這個函式會從 DNS 服務執行個體解析回應取得服務執行個體的相關資訊。
otDnsServiceResponseGetServiceName(const otDnsServiceResponse *aResponse, char *aLabelBuffer, uint8_t aLabelBufferSize, char *aNameBuffer, uint16_t aNameBufferSize)
這個函式會取得與 DNS 服務執行個體解析回應相關聯的服務執行個體名稱。
otDnsSetNameCompressionEnabled(bool aEnabled)
void
這項函式可啟用/停用「DNS 名稱壓縮」模式。

結構

otDnsQueryConfig

這個結構代表 DNS 查詢設定。

otDnsServiceInfo

這個結構提供 DNS 服務執行個體的資訊。

otDnsTxtEntry

這個結構代表一個代表鍵/值組合的 TXT 記錄項目 (RFC 6763 - 第 6.3 節)。

otDnsTxtEntryIterator

這個結構代表 TXT 記錄完整 (鍵/值組合) 的疊代器。

列舉

OTDNN66 模式

 otDnsNat64Mode

這個列舉類型代表 otDnsQueryConfig 中的 NAT64 模式,

NAT64 模式指示是否要在 DNS 用戶端位址解析期間允許或禁止 NAT64 位址轉譯。只有在 OPENTHREAD_CONFIG_DNS_CLIENT_NAT64_ENABLE 已啟用時,才能使用此模式。

屬性
OT_DNS_NAT64_ALLOW

允許在 DNS 用戶端位址解析期間進行 NAT64 位址翻譯。

OT_DNS_NAT64_DISALLOW

不允許在 DNS 用戶端位址解析期間翻譯 NAT64 位址。

OT_DNS_NAT64_UNSPECIFIED

未指定 NAT64 模式。使用預設的 NAT64 模式。

otDnsRecursionFlag

 otDnsRecursionFlag

這個列舉類型代表 otDnsQueryConfig 中的「週期性」 (RD) 旗標,

屬性
OT_DNS_FLAG_NO_RECURSION

表示 DNS 名稱伺服器無法以週期性方式解析查詢,

OT_DNS_FLAG_RECURSION_DESIRED

表示 DNS 名稱伺服器能以遞迴方式解析查詢。

OT_DNS_FLAG_UNSPECIFIED

表示未指定旗標。

Typedefs

otDnsAddress 回呼

void(* otDnsAddressCallback)(otError aError, const otDnsAddressResponse *aResponse, void *aContext)

當收到地址解析查詢的 DNS 回應時,會呼叫此函式指標。

在這個回呼中,使用者可以使用 otDnsAddressResponseGet{Item}() 函式和 aResponse 指標,進一步瞭解回應。

aResponse 指標只能在這個回呼中使用,而且從這個函式傳回後,將保持有效,因此使用者「不得」保留 aResponse 指標以供日後使用。

aError 可能包含下列項目:

詳情
參數
[in] aError
DNS 交易的結果。
[in] aResponse
回應指標 (一律為非 NULL)。
[in] aContext
指向應用程式特定背景資訊的指標。

  • OT_ERROR_NONE 已成功收到回應。
  • OT_ERROR_ABORT 堆疊已取消 DNS 交易。
  • OT_ERROR_QUESTION_TIMEOUT 未在時限內收到 DNS 回應。

如果伺服器拒絕位址解析要求,伺服器中的錯誤代碼對應如下:

  • (0) NOERROR 成功 (沒有錯誤條件) -> OT_ERROR_NONE
  • (1) FORMERR 伺服器因格式錯誤而無法解讀 -> OT_ERROR_PARSE
  • (2) SERVFAIL 伺服器發生內部錯誤,- OT_ERROR_FAILED
  • (3) 應該有的 NXDOMAIN 名稱不存在 -> OT_ERROR_NOT_FOUND
  • (4) NOTIMP 伺服器不支援查詢類型 (OpCode) -> OT_ERROR_NOT_IMPLEMENTED
  • (5) REFused 伺服器因政策/安全性原因而遭拒 -> OT_ERROR_SECURITY
  • (6) YXDOMAIN 部分名稱不應存在,確實存在 -> OT_ERROR_DUPLICATED
  • (7) YXRRSET 部分不應有的 RRset 確實存在 ->> OT_ERROR_DUPLICATED
  • (8) NXRRSET 一些應有存在的 RRset,不存在 ->> OT_ERROR_NOT_FOUND
  • (9) NOTAUTH 服務並未取得可用區 -> 授權,OT_ERROR_SECURITY
  • (10) NOTZONE A 不在可用區中 ->OT_ERROR_PARSE
  • (20) BADNAME 名稱無效 -> OT_ERROR_PARSE
  • (21) BADALG 演算法不佳 -> OT_ERROR_SECURITY
  • (22) BADTRUN 無效截斷 -> OT_ERROR_PARSE
  • 其他回應代碼 -> OT_ERROR_FAILED

otDnsAddressResponse

struct otDnsAddressResponse otDnsAddressResponse

這種類型是以不透明的表示法表示地址解析 DNS 查詢。

這種類型的指標是由回呼 otDnsAddressCallback 提供。

otDnsBrowseCallback

void(* otDnsBrowseCallback)(otError aError, const otDnsBrowseResponse *aResponse, void *aContext)

收到瀏覽 (服務執行個體列舉) 查詢的 DNS 回應時,系統會呼叫這個函式指標。

在這個回呼中,使用者可以使用 otDnsBrowseResponseGet{Item}() 函式和 aResponse 指標,進一步瞭解回應。

aResponse 指標只能在這個回呼中使用,而且從這個函式傳回後,將保持有效,因此使用者「不得」保留 aResponse 指標以供日後使用。

如需 aError 可能的值的完整清單,請參閱 otDnsAddressCallback()

詳情
參數
[in] aError
DNS 交易的結果。
[in] aResponse
回應指標 (一律為非 NULL)。
[in] aContext
指向應用程式特定背景資訊的指標。

otDnsBrowseResponse

struct otDnsBrowseResponse otDnsBrowseResponse

此類型代表對瀏覽 (服務執行個體列舉) DNS 查詢的不透明表示法。

這種類型的指標是由回呼 otDnsBrowseCallback 提供。

otDnsQueryConfig

struct otDnsQueryConfig otDnsQueryConfig

這個結構代表 DNS 查詢設定。

這個結構中的任何欄位都可以設為零,表示未指定。未指定欄位的處理方式取決於使用 otDnsQueryConfig 執行個體的函式。

otDnsServiceCallback

void(* otDnsServiceCallback)(otError aError, const otDnsServiceResponse *aResponse, void *aContext)

當收到服務執行個體解析查詢的 DNS 回應時,系統會呼叫此函式指標。

在這個回呼中,使用者可以使用 otDnsServiceResponseGet{Item}() 函式和 aResponse 指標,進一步瞭解回應。

aResponse 指標只能在這個回呼中使用,而且從這個函式傳回後,將保持有效,因此使用者「不得」保留 aResponse 指標以供日後使用。

如需 aError 可能的值的完整清單,請參閱 otDnsAddressCallback()

詳情
參數
[in] aError
DNS 交易的結果。
[in] aResponse
回應指標 (一律為非 NULL)。
[in] aContext
指向應用程式特定背景資訊的指標。

OTDServiceService

struct otDnsServiceInfo otDnsServiceInfo

這個結構提供 DNS 服務執行個體的資訊。

OTDServiceServiceResponse

struct otDnsServiceResponse otDnsServiceResponse

這個類型是對服務執行個體解析 DNS 查詢的回應不透明表示法。

這種類型的指標是由回呼 otDnsAddressCallback 提供。

OTDTTT 項目

struct otDnsTxtEntry otDnsTxtEntry

這個結構代表一個代表鍵/值組合的 TXT 記錄項目 (RFC 6763 - 第 6.3 節)。

mKeymValue 指向的字串緩衝區必須保持不變,並在這類結構的例項傳遞至 OpenThread 後保持不變 (屬於 otSrpClientService 執行個體的一部分)。

otSrpClientService 中使用 otDnsTxtEntry 項目的陣列來指定完整的 TXT 記錄 (項目清單)。

otDnsTxtEntryIterator

struct otDnsTxtEntryIterator otDnsTxtEntryIterator

這個結構代表 TXT 記錄完整 (鍵/值組合) 的疊代器。

這個結構中的資料欄位適用於 OpenThread 核心,因此呼叫者不應讀取或變更這些欄位。

Functions

otDnsAddressResponseGetAddress

otError otDnsAddressResponseGetAddress(
  const otDnsAddressResponse *aResponse,
  uint16_t aIndex,
  otIp6Address *aAddress,
  uint32_t *aTtl
)

這個函式會接收與地址解析 DNS 回應相關聯的 IPv6 位址。

這個函式「僅」可從 otDnsAddressCallback 使用。

回應可能包含多個 IPv6 位址記錄。aIndex 可用來疊代地址清單。索引零值將取得第一個地址,依此類推。抵達清單末端時,系統會傳回 OT_ERROR_NOT_FOUND

詳情
參數
[in] aResponse
回應指標。
[in] aIndex
要擷取的地址記錄索引。
[out] aAddress
指向 IPv6 位址的指標,並「不得」為 NULL。
[out] aTtl
指向 uint32_t 的指標,以便輸出位址的存留時間。如果呼叫端不想取得存留時間,則可設為 NULL。
傳回值
OT_ERROR_NONE
已成功讀取地址。
OT_ERROR_NOT_FOUND
aResponseaIndex 沒有任何地址記錄。
OT_ERROR_PARSE
無法剖析 aResponse 中的記錄。
OT_ERROR_INVALID_STATE
無 NAT64 前置字串 (僅適用於允許 NAT64 的情況)。

otDnsAddressResponseGetHostName

otError otDnsAddressResponseGetHostName(
  const otDnsAddressResponse *aResponse,
  char *aNameBuffer,
  uint16_t aNameBufferSize
)

這個函式會取得與地址解析 DNS 回應相關聯的完整主機名稱。

這個函式「僅」可從 otDnsAddressCallback 使用。

詳情
參數
[in] aResponse
回應指標。
[out] aNameBuffer
用於輸出完整主機名稱的緩衝區字元 (不得為 NULL)。
[in] aNameBufferSize
aNameBuffer 的大小。
傳回值
OT_ERROR_NONE
已讀取完整的主機名稱。
OT_ERROR_NO_BUFS
名稱不適用於aNameBuffer

otDnsBrowseResponseGetHostAddress

otError otDnsBrowseResponseGetHostAddress(
  const otDnsBrowseResponse *aResponse,
  const char *aHostName,
  uint16_t aIndex,
  otIp6Address *aAddress,
  uint32_t *aTtl
)

這個函式會從 DNS 瀏覽 (服務執行個體列舉) 回應取得主機 IPv6 位址。

這個函式「僅」可從 otDnsBrowseCallback 使用。

回應可以包含零或多個 IPv6 位址記錄。aIndex 可用來疊代地址清單。索引零值將取得第一個地址,依此類推。抵達清單末端時,系統會傳回 OT_ERROR_NOT_FOUND

詳情
參數
[in] aResponse
回應指標。
[in] aHostName
取得位址的主機名稱 (「不得」為 NULL)。
[in] aIndex
要擷取的地址記錄索引。
[out] aAddress
指向 IPv6 位址的指標,並「不得」為 NULL。
[out] aTtl
指向 uint32_t 的指標,以便輸出位址的存留時間。如果呼叫端不想取得存留時間,則可設為 NULL。
傳回值
OT_ERROR_NONE
已成功讀取地址。
OT_ERROR_NOT_FOUND
aResponseaIndexaHostname沒有地址記錄。
OT_ERROR_PARSE
無法剖析 aResponse 中的記錄。

otDnsBrowseResponseGetServiceInfo

otError otDnsBrowseResponseGetServiceInfo(
  const otDnsBrowseResponse *aResponse,
  const char *aInstanceLabel,
  otDnsServiceInfo *aServiceInfo
)

這個函式會從 DNS 瀏覽 (服務執行個體列舉) 回應取得服務執行個體的資訊。

這個函式「僅」可從 otDnsBrowseCallback 使用。

瀏覽 DNS 回應必須包含列舉式服務執行個體的 SRV、TXT 和 AAAA 記錄 (請注意,這應該是 SHOULD 而非 MUST 的要求)。這個函式會試圖針對特定服務執行個體擷取這項資訊 (如果有的話)。

  • 如果在 aResponse 中找不到相符的 SRV 記錄,則會傳回 OT_ERROR_NOT_FOUND
  • 如果在 aResponse 中找到相符的 SRV 記錄,則會更新 aServiceInfo 並傳回 OT_ERROR_NONE
  • 如果在 aResponse 中找不到相符的 TXT 記錄,aServiceInfo 中的 mTxtDataSize 會設為零。
  • 如果在 aResponsemHostAddress is set to all zero or unspecified address. 中找不到相符的 AAAA 記錄
  • If there are multiple AAAA records for the host name in @p aResponse,mHostAddressis set to the first one. The other addresses can be retrieved usingotDnsBrowseResponseGetHostAddress()`。

詳情
參數
[in] aResponse
回應指標。
[in] aInstanceLabel
服務執行個體標籤 (「不得」為 NULL)。
[out] aServiceInfo
用來輸出服務執行個體資訊的 ServiceInfo (「不得」為 NULL)。
傳回值
OT_ERROR_NONE
已讀取服務執行個體資訊。「aServiceInfo」已更新。
OT_ERROR_NOT_FOUND
找不到與「aInstanceLabel」相符的 SRV 記錄。
OT_ERROR_NO_BUFS
主機名稱和/或 TXT 資料超出指定的緩衝區。
OT_ERROR_PARSE
無法剖析 aResponse 中的記錄。

otDnsBrowseResponseGetServiceInstance

otError otDnsBrowseResponseGetServiceInstance(
  const otDnsBrowseResponse *aResponse,
  uint16_t aIndex,
  char *aLabelBuffer,
  uint8_t aLabelBufferSize
)

這個函式會接收與 DNS 瀏覽 (服務執行個體列舉) 回應相關聯的服務執行個體。

這個函式「僅」可從 otDnsBrowseCallback 使用。

回應中可能包含多項服務執行個體記錄。aIndex 可用來疊代整個清單。索引零以提供第一筆記錄。抵達清單末端時,系統會傳回 OT_ERROR_NOT_FOUND

請注意,這個函式會取得服務執行個體標籤,而不是 .. 格式的完整服務執行個體名稱。

詳情
參數
[in] aResponse
回應指標。
[in] aIndex
要擷取的服務執行個體記錄索引。
[out] aLabelBuffer
用於輸出服務執行個體標籤的緩衝區字元緩衝區 (不得為 NULL)。
[in] aLabelBufferSize
aLabelBuffer 的大小。
傳回值
OT_ERROR_NONE
已成功讀取服務執行個體。
OT_ERROR_NO_BUFS
名稱不適用於aNameBuffer
OT_ERROR_NOT_FOUND
aResponseaIndex 沒有服務執行個體記錄。
OT_ERROR_PARSE
無法剖析 aResponse 中的記錄。

otDnsBrowseResponseGetServiceName

otError otDnsBrowseResponseGetServiceName(
  const otDnsBrowseResponse *aResponse,
  char *aNameBuffer,
  uint16_t aNameBufferSize
)

這個函式會取得與 DNS 瀏覽 (服務執行個體列舉) 回應相關聯的服務名稱。

這個函式「僅」可從 otDnsBrowseCallback 使用。

詳情
參數
[in] aResponse
回應指標。
[out] aNameBuffer
用於輸出服務名稱的緩衝區陣列,「不得」為 NULL。
[in] aNameBufferSize
aNameBuffer 的大小。
傳回值
OT_ERROR_NONE
已成功讀取服務名稱。
OT_ERROR_NO_BUFS
名稱不適用於aNameBuffer

OTDClientClientBrowse

otError otDnsClientBrowse(
  otInstance *aInstance,
  const char *aServiceName,
  otDnsBrowseCallback aCallback,
  void *aContext,
  const otDnsQueryConfig *aConfig
)

這個函式會傳送指定服務名稱的 DNS 瀏覽 (服務執行個體列舉) 查詢。

啟用 OPENTHREAD_CONFIG_DNS_CLIENT_SERVICE_DISCOVERY_ENABLE 後,即可使用此功能。

aConfig 可以是 NULL。在這種情況下,系統會使用預設設定 (來自 otDnsClientGetDefaultConfig()) 做為這項查詢的設定。在非 NULL 的 aConfig 中,部分欄位可以保留未指定 (值為 0)。接著,系統會將未指定欄位的欄位替換為預設設定的值。

詳情
參數
[in] aInstance
指向 OpenThread 執行個體的指標。
[in] aServiceName
要查詢的服務名稱 (「不得」為 NULL)。
[in] aCallback
應在收到回應或逾時時呼叫的函式指標。
[in] aContext
指向任意背景資訊的資訊。
[in] aConfig
這項查詢要使用的設定指標。
傳回值
OT_ERROR_NONE
已成功傳送查詢。系統會叫用 aCallback 以回報狀態。
OT_ERROR_NO_BUFS
緩衝區數量不足,無法準備及傳送查詢。

otDnsClientGetDefaultConfig

const otDnsQueryConfig * otDnsClientGetDefaultConfig(
  otInstance *aInstance
)

這項函式會取得 DNS 用戶端目前使用的預設查詢設定。

OpenThread 堆疊啟動時,預設的 DNS 查詢設定取決於一組 OT 設定選項,例如 OPENTHREAD_CONFIG_DNS_CLIENT_DEFAULT_SERVER_IP6_ADDRESS_DEFAULT_SERVER_PORT_DEFAULT_RESPONSE_TIMEOUT 等 (如需所有相關設定選項,請參閱 config/dns_client.h)。

詳情
參數
[in] aInstance
指向 OpenThread 執行個體的指標。
傳回
指向 DNS 用戶端目前使用的預設設定指標。

otDnsClientResolveAddress

otError otDnsClientResolveAddress(
  otInstance *aInstance,
  const char *aHostName,
  otDnsAddressCallback aCallback,
  void *aContext,
  const otDnsQueryConfig *aConfig
)

這個函式會傳送特定主機名稱的 AAAA (IPv6) 記錄地址解析 DNS 查詢。

aConfig 可以是 NULL。在這種情況下,系統會使用預設設定 (來自 otDnsClientGetDefaultConfig()) 做為這項查詢的設定。在非 NULL 的 aConfig 中,部分欄位可以保留未指定 (值為 0)。接著,系統會將未指定欄位的欄位替換為預設設定的值。

詳情
參數
[in] aInstance
指向 OpenThread 執行個體的指標。
[in] aHostName
要查詢位址的主機名稱 (「不得」為 NULL)。
[in] aCallback
應在收到回應或逾時時呼叫的函式指標。
[in] aContext
指向任意背景資訊的資訊。
[in] aConfig
這項查詢要使用的設定指標。
傳回值
OT_ERROR_NONE
已成功傳送查詢。系統會叫用 aCallback 以回報狀態。
OT_ERROR_NO_BUFS
緩衝區數量不足,無法準備及傳送查詢。
OT_ERROR_INVALID_ARGS
主機名稱格式無效。
OT_ERROR_INVALID_STATE
執行緒介面並未開啟,因此無法傳送查詢。

otDnsClientResolveIp4 位址

otError otDnsClientResolveIp4Address(
  otInstance *aInstance,
  const char *aHostName,
  otDnsAddressCallback aCallback,
  void *aContext,
  const otDnsQueryConfig *aConfig
)

這個函式會傳送特定主機名稱的 A (IPv4) 記錄位址解析 DNS 查詢。

您必須啟用 OPENTHREAD_CONFIG_DNS_CLIENT_NAT64_ENABLE,才能使用這個函式。

收到成功的回應時,查詢會從 aCallback 傳回,這是查詢回應中的 IPv6 位址 IPv6 位址翻譯版本。

aConfig 可以是 NULL。在這種情況下,系統會使用預設設定 (來自 otDnsClientGetDefaultConfig()) 做為這項查詢的設定。在非 NULL 的 aConfig 中,部分欄位可以保留未指定 (值為 0)。接著,系統會將未指定欄位的欄位替換為預設設定的值。

詳情
參數
[in] aInstance
指向 OpenThread 執行個體的指標。
[in] aHostName
要查詢位址的主機名稱 (「不得」為 NULL)。
[in] aCallback
應在收到回應或逾時時呼叫的函式指標。
[in] aContext
指向任意背景資訊的資訊。
[in] aConfig
這項查詢要使用的設定指標。
傳回值
OT_ERROR_NONE
已成功傳送查詢。系統會叫用 aCallback 以回報狀態。
OT_ERROR_NO_BUFS
緩衝區數量不足,無法準備及傳送查詢。
OT_ERROR_INVALID_ARGS
主機名稱格式無效,或是未在設定中啟用網路位址轉譯 (NAT64)。
OT_ERROR_INVALID_STATE
執行緒介面並未開啟,因此無法傳送查詢。

otDnsClientResolveService

otError otDnsClientResolveService(
  otInstance *aInstance,
  const char *aInstanceLabel,
  const char *aServiceName,
  otDnsServiceCallback aCallback,
  void *aContext,
  const otDnsQueryConfig *aConfig
)

這個函式會針對特定服務執行個體傳送 DNS 服務執行個體解析查詢。

啟用 OPENTHREAD_CONFIG_DNS_CLIENT_SERVICE_DISCOVERY_ENABLE 後,即可使用此功能。

aConfig 可以是 NULL。在這種情況下,系統會使用預設設定 (來自 otDnsClientGetDefaultConfig()) 做為這項查詢的設定。在非 NULL 的 aConfig 中,部分欄位可以保留未指定 (值為 0)。接著,系統會將未指定欄位的欄位替換為預設設定的值。

詳情
參數
[in] aInstance
指向 OpenThread 執行個體的指標。
[in] aInstanceLabel
服務執行個體標籤。
[in] aServiceName
服務名稱 (必須搭配 aInstanceLabel 組成完整的執行個體名稱)。
[in] aCallback
應在收到回應或逾時時呼叫的函式指標。
[in] aContext
指向任意背景資訊的資訊。
[in] aConfig
這項查詢要使用的設定指標。
傳回值
OT_ERROR_NONE
已成功傳送查詢。系統會叫用 aCallback 以回報狀態。
OT_ERROR_NO_BUFS
緩衝區數量不足,無法準備及傳送查詢。
OT_ERROR_INVALID_ARGS
aInstanceLabel 為 NULL。

otDnsClientSetDefaultConfig

void otDnsClientSetDefaultConfig(
  otInstance *aInstance,
  const otDnsQueryConfig *aConfig
)

這個函式會在 DNS 用戶端上設定預設查詢設定。

注意:所有進行中的查詢都會繼續使用啟動後的設定。新的預設設定將用於日後的 DNS 查詢。 aConfig 可以是 NULL。在這個範例中,預設設定將設為 OT 設定選項 OPENTHREAD_CONFIG_DNS_CLIENT_DEFAULT_{} 的預設設定。如此一來,當 OpenThread 堆疊啟動時,預設查詢設定會重設為設定。

在非 NULL 的 aConfig 中,呼叫端可以選擇不指定 otDnsQueryConfig 執行個體中的部分欄位 (值為零)。未指定的欄位,將替換為對應的 OT 設定選項定義 OPENTHREAD_CONFIG_DNS_CLIENT_DEFAULT_{},以形成預設查詢設定。

啟用 OPENTHREAD_CONFIG_DNS_CLIENT_DEFAULT_SERVER_ADDRESS_AUTO_SET_ENABLE 時,DNS 用戶端會自動設定及更新預設設定中的伺服器 IPv6 位址。只有當使用者未明確設定或指定時,系統才會執行這項作業。您必須啟用 SRP 用戶端及其自動啟動功能,才能使用這項行為。接著 SRP 用戶端會監控 DNS/SRP 服務項目的執行緒網路資料,以選取 SRP 伺服器。在預設設定中,所選的 SRP 伺服器位址也會設為 DNS 伺服器位址。

詳情
參數
[in] aInstance
指向 OpenThread 執行個體的指標。
[in] aConfig
指向新查詢設定的預設指標。

otDnsGetNextTxtEntry

otError otDnsGetNextTxtEntry(
  otDnsTxtEntryIterator *aIterator,
  otDnsTxtEntry *aEntry
)

這個函式會從疊代器剖析 TXT 資料,並取得下一個 TXT 記錄項目 (鍵/值組合)。

aIterator 必須先使用 otDnsInitTxtEntryIterator() 進行初始化,再呼叫這個函式,而且用來初始化疊代器的 TXT 資料緩衝區「必須」保持不變,且保持不變。否則,這個函式的行為未定義。

如果剖析的金鑰字串長度小於或等於 OT_DNS_TXT_KEY_MAX_LENGTH (建議的金鑰長度上限),金鑰字串會在 aEntrymKey 中傳回。不過,如果金鑰較長,mKey 就會設為 NULL,而 mValuemValueLength 會傳回整個編碼的 TXT 項目字串。

詳情
參數
[in] aIterator
指向 iterator 的指標 (「不得」為 NULL)。
[out] aEntry
指向 otDnsTxtEntry 結構的指標,用於輸出剖析/讀取的項目 (「不得」為 NULL)。
傳回值
OT_ERROR_NONE
已成功剖析下一個項目。「aEntry」已更新。
OT_ERROR_NOT_FOUND
TXT 資料中沒有任何項目。
OT_ERROR_PARSE
aIterator 的 TXT 資料格式有誤。

otDnsInitTxtEntryIterator

void otDnsInitTxtEntryIterator(
  otDnsTxtEntryIterator *aIterator,
  const uint8_t *aTxtData,
  uint16_t aTxtDataLength
)

這個函式會初始化 TXT 記錄疊代器。

在使用 aIterator 物件時,緩衝區指標 aTxtData 及其內容「必須」保持不變。

詳情
參數
[in] aIterator
指向疊代器的初始化指標 (不得為 NULL)。
[in] aTxtData
指向已編碼 TXT 資料的緩衝區指標。
[in] aTxtDataLength
aTxtData 的長度 (位元組數)。

otDnsIsNameCompressionEnabled

bool otDnsIsNameCompressionEnabled(
  void
)

這個函式可指出「DNS 名稱壓縮」模式是否已啟用。

這只適用於測試 OPENTHREAD_CONFIG_REFERENCE_DEVICE_ENABLE 設定的情況。

詳情
傳回
如果已啟用「DNS 名稱壓縮」模式,則傳回 TRUE,否則為 FALSE。

otDnsServiceResponseGetHostAddress

otError otDnsServiceResponseGetHostAddress(
  const otDnsServiceResponse *aResponse,
  const char *aHostName,
  uint16_t aIndex,
  otIp6Address *aAddress,
  uint32_t *aTtl
)

這項函式會從 DNS 服務執行個體解析回應取得主機 IPv6 位址。

這個函式「僅」可從 otDnsServiceCallback 使用。

回應可以包含零或多個 IPv6 位址記錄。aIndex 可用來疊代地址清單。索引零值將取得第一個地址,依此類推。抵達清單末端時,系統會傳回 OT_ERROR_NOT_FOUND

詳情
參數
[in] aResponse
回應指標。
[in] aHostName
取得位址的主機名稱 (「不得」為 NULL)。
[in] aIndex
要擷取的地址記錄索引。
[out] aAddress
指向 IPv6 位址的指標,並「不得」為 NULL。
[out] aTtl
指向 uint32_t 的指標,以便輸出位址的存留時間。如果呼叫端不想取得存留時間,則可設為 NULL。
傳回值
OT_ERROR_NONE
已成功讀取地址。
OT_ERROR_NOT_FOUND
aResponseaIndexaHostname沒有地址記錄。
OT_ERROR_PARSE
無法剖析 aResponse 中的記錄。

otDnsServiceResponseGetServiceInfo

otError otDnsServiceResponseGetServiceInfo(
  const otDnsServiceResponse *aResponse,
  otDnsServiceInfo *aServiceInfo
)

這個函式會從 DNS 服務執行個體解析回應取得服務執行個體的相關資訊。

這個函式「僅」可從 otDnsServiceCallback 使用。

  • 如果在 aResponse 中找不到相符的 SRV 記錄,則會傳回 OT_ERROR_NOT_FOUND
  • 如果在 aResponse 中找到相符的 SRV 記錄,則會更新 aServiceInfo 並傳回 OT_ERROR_NONE
  • 如果在 aResponse 中找不到相符的 TXT 記錄,aServiceInfo 中的 mTxtDataSize 會設為零。
  • 如果在 aResponsemHostAddress is set to all zero or unspecified address. 中找不到相符的 AAAA 記錄
  • If there are multiple AAAA records for the host name in @p aResponse,mHostAddressis set to the first one. The other addresses can be retrieved usingotDnsServiceResponseGetHostAddress()`。

詳情
參數
[in] aResponse
回應指標。
[out] aServiceInfo
用來輸出服務執行個體資訊的 ServiceInfo (「不得」為 NULL)。
傳回值
OT_ERROR_NONE
已讀取服務執行個體資訊。「aServiceInfo」已更新。
OT_ERROR_NOT_FOUND
aResponse 中找不到相符的 SRV 記錄。
OT_ERROR_NO_BUFS
主機名稱和/或 TXT 資料超出指定的緩衝區。
OT_ERROR_PARSE
無法剖析 aResponse 中的記錄。

otDnsServiceResponseGetServiceName

otError otDnsServiceResponseGetServiceName(
  const otDnsServiceResponse *aResponse,
  char *aLabelBuffer,
  uint8_t aLabelBufferSize,
  char *aNameBuffer,
  uint16_t aNameBufferSize
)

這個函式會取得與 DNS 服務執行個體解析回應相關聯的服務執行個體名稱。

這個函式「僅」可從 otDnsServiceCallback 使用。

詳情
參數
[in] aResponse
回應指標。
[out] aLabelBuffer
用於輸出服務執行個體標籤的緩衝區字元緩衝區 (不得為 NULL)。
[in] aLabelBufferSize
aLabelBuffer 的大小。
[out] aNameBuffer
用於儲存其餘服務名稱的緩衝區緩衝區 (如果使用者不想取得名稱,可以是 NULL)。
[in] aNameBufferSize
aNameBuffer 的大小。
傳回值
OT_ERROR_NONE
已成功讀取服務名稱。
OT_ERROR_NO_BUFS
標籤或名稱不符合指定的緩衝區。

otDnsSetNameCompressionEnabled

void otDnsSetNameCompressionEnabled(
  bool aEnabled
)

這項函式可啟用/停用「DNS 名稱壓縮」模式。

系統預設會啟用 DNS 名稱壓縮功能。停用後,DNS 名稱會附加為完整且永不壓縮。這適用於 OpenThread' 的 DNS 和 SRP 用戶端/伺服器模組。

這只適用於測試 OPENTHREAD_CONFIG_REFERENCE_DEVICE_ENABLE 設定的情況。

請注意,在使用 OPENTHREAD_CONFIG_MULTIPLE_INSTANCE_ENABLE 的情況下,此模式適用於所有 OpenThread 執行個體 (即呼叫此函式可啟用/停用所有 OpenThread 執行個體的壓縮模式)。

詳情
參數
[in] aEnabled
TRUE 可啟用「DNS 名稱壓縮」模式,設為 FALSE 可停用。

巨集

OT_DNS_MAX_LABEL_SIZE

 OT_DNS_MAX_LABEL_SIZE 64

標籤字串大小上限 (在字串結尾加上空值字元)。

OT_DNS_MAX_NAME_SIZE

 OT_DNS_MAX_NAME_SIZE 255

名稱字串大小上限 (在字串結尾使用空值字元)。

OT_DNS_TXT_KEY_MAX_LENGTH

 OT_DNS_TXT_KEY_MAX_LENGTH 9

建議的 TXT 記錄金鑰字串長度上限 (RFC 6763 - 第 6.4 節)。

OT_DNS_TXT_KEY_MIN_LENGTH

 OT_DNS_TXT_KEY_MIN_LENGTH 1

TXT 記錄金鑰字串的長度下限 (RFC 6763 - 第 6.4 節)。

資源

OpenThread API 參考資料主題出自原始碼,可於 GitHub 取得。如需更多資訊,或想參閱我們的說明文件,請參閱資源