本頁面由 Cloud Translation API 翻譯而成。

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

Functions
`otDnsAddressResponseGetAddress(const otDnsAddressResponse aResponse, uint16_t aIndex, otIp6Address aAddress, uint32_t *aTtl)`	`otError` 這個函式會接收與地址解析 DNS 回應相關聯的 IPv6 位址。
`otDnsAddressResponseGetHostName(const otDnsAddressResponse aResponse, char aNameBuffer, uint16_t aNameBufferSize)`	`otError` 這個函式會取得與地址解析 DNS 回應相關聯的完整主機名稱。
`otDnsBrowseResponseGetHostAddress(const otDnsBrowseResponse aResponse, const char aHostName, uint16_t aIndex, otIp6Address aAddress, uint32_t aTtl)`	`otError` 這個函式會從 DNS 瀏覽 (服務執行個體列舉) 回應取得主機 IPv6 位址。
`otDnsBrowseResponseGetServiceInfo(const otDnsBrowseResponse aResponse, const char aInstanceLabel, otDnsServiceInfo *aServiceInfo)`	`otError` 這個函式會從 DNS 瀏覽 (服務執行個體列舉) 回應取得服務執行個體的資訊。
`otDnsBrowseResponseGetServiceInstance(const otDnsBrowseResponse aResponse, uint16_t aIndex, char aLabelBuffer, uint8_t aLabelBufferSize)`	`otError` 這個函式會接收與 DNS 瀏覽 (服務執行個體列舉) 回應相關聯的服務執行個體。
`otDnsBrowseResponseGetServiceName(const otDnsBrowseResponse aResponse, char aNameBuffer, uint16_t aNameBufferSize)`	`otError` 這個函式會取得與 DNS 瀏覽 (服務執行個體列舉) 回應相關聯的服務名稱。
`otDnsClientBrowse(otInstance aInstance, const char aServiceName, otDnsBrowseCallback aCallback, void aContext, const otDnsQueryConfig aConfig)`	`otError` 這個函式會傳送指定服務名稱的 DNS 瀏覽 (服務執行個體列舉) 查詢。
`otDnsClientGetDefaultConfig(otInstance *aInstance)`	`const otDnsQueryConfig *` 這項函式會取得 DNS 用戶端目前使用的預設查詢設定。
`otDnsClientResolveAddress(otInstance aInstance, const char aHostName, otDnsAddressCallback aCallback, void aContext, const otDnsQueryConfig aConfig)`	`otError` 這個函式會傳送特定主機名稱的 AAAA (IPv6) 記錄地址解析 DNS 查詢。
`otDnsClientResolveIp4Address(otInstance aInstance, const char aHostName, otDnsAddressCallback aCallback, void aContext, const otDnsQueryConfig aConfig)`	`otError` 這個函式會傳送特定主機名稱的 A (IPv4) 記錄位址解析 DNS 查詢。
`otDnsClientResolveService(otInstance aInstance, const char aInstanceLabel, const char aServiceName, otDnsServiceCallback aCallback, void aContext, const otDnsQueryConfig *aConfig)`	`otError` 這個函式會針對特定服務執行個體傳送 DNS 服務執行個體解析查詢。
`otDnsClientSetDefaultConfig(otInstance aInstance, const otDnsQueryConfig aConfig)`	`void` 這個函式會在 DNS 用戶端上設定預設查詢設定。
`otDnsGetNextTxtEntry(otDnsTxtEntryIterator aIterator, otDnsTxtEntry aEntry)`	`otError` 這個函式會從疊代器剖析 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)`	`otError` 這項函式會從 DNS 服務執行個體解析回應取得主機 IPv6 位址。
`otDnsServiceResponseGetServiceInfo(const otDnsServiceResponse aResponse, otDnsServiceInfo aServiceInfo)`	`otError` 這個函式會從 DNS 服務執行個體解析回應取得服務執行個體的相關資訊。
`otDnsServiceResponseGetServiceName(const otDnsServiceResponse aResponse, char aLabelBuffer, uint8_t aLabelBufferSize, char *aNameBuffer, uint16_t aNameBufferSize)`	`otError` 這個函式會取得與 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 不在可用區中 -&gt；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 節)。

mKey 和 mValue 指向的字串緩衝區必須保持不變，並在這類結構的例項傳遞至 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`	`aResponseaIndex`的`aHostname`沒有地址記錄。
`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 會設為零。
如果在 aResponse、mHostAddress 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`	`aResponse` 的 `aIndex` 沒有服務執行個體記錄。
`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 查詢。

詳情

參數

`[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 位址翻譯版本。

詳情

參數

`[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 後，即可使用此功能。

詳情

參數

`[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 (建議的金鑰長度上限)，金鑰字串會在 aEntry 的 mKey 中傳回。不過，如果金鑰較長，mKey 就會設為 NULL，而 mValue 和 mValueLength 會傳回整個編碼的 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 使用。

詳情

參數

`[in] aResponse`	回應指標。
`[in] aHostName`	取得位址的主機名稱 (「不得」為 NULL)。
`[in] aIndex`	要擷取的地址記錄索引。
`[out] aAddress`	指向 IPv6 位址的指標，並「不得」為 NULL。
`[out] aTtl`	指向 `uint32_t` 的指標，以便輸出位址的存留時間。如果呼叫端不想取得存留時間，則可設為 NULL。

傳回值

`OT_ERROR_NONE`	已成功讀取地址。
`OT_ERROR_NOT_FOUND`	`aResponseaIndex`的`aHostname`沒有地址記錄。
`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 會設為零。
如果在 aResponse、mHostAddress 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 取得。如需更多資訊，或想參閱我們的說明文件，請參閱資源。