DNS

這個模組內含控管 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 中的「Recursion Desired」(RD) 標記。
otDnsServiceMode{
  OT_DNS_SERVICE_MODE_UNSPECIFIED = 0,
  OT_DNS_SERVICE_MODE_SRV = 1,
  OT_DNS_SERVICE_MODE_TXT = 2,
  OT_DNS_SERVICE_MODE_SRV_TXT = 3,
  OT_DNS_SERVICE_MODE_SRV_TXT_SEPARATE = 4,
  OT_DNS_SERVICE_MODE_SRV_TXT_OPTIMIZE = 5
} 		列舉
Type 代表 otDnsQueryConfig 中的服務解決模式。
otDnsTransportProto{
  OT_DNS_TRANSPORT_UDP = 1,
  OT_DNS_TRANSPORT_TCP = 2
} 		列舉
類型代表 otDnsQueryConfig 中的 DNS 傳輸通訊協定。

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 記錄項目 (鍵/值組合) 的疊代器。

函式
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 服務執行個體解析作業。
otDnsClientResolveServiceAndHostAddress(otInstance *aInstance, const char *aInstanceLabel, const char *aServiceName, otDnsServiceCallback aCallback, void *aContext, const otDnsQueryConfig *aConfig)
啟動指定服務執行個體的 DNS 服務執行個體解析，並針對服務執行個體的主機名稱進行可能的後續位址解析。
otDnsClientSetDefaultConfig(otInstance *aInstance, const otDnsQueryConfig *aConfig)
void
設定 DNS 用戶端的預設查詢設定。
otDnsEncodeTxtData(const otDnsTxtEntry *aTxtEntries, uint16_t aNumTxtEntries, uint8_t *aTxtData, uint16_t *aTxtDataLength)
這個外掛程式能將指定的 TXT 紀錄項目清單 (鍵/值組合) 編碼為 TXT 資料 (按照 RFC 6763 指定的格式)。
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 記錄項目 (鍵/值組合) 的疊代器。

列舉

otDnsNat64Mode

 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 中的「Recursion Desired」(RD) 標記。

屬性
OT_DNS_FLAG_NO_RECURSION

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

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

表示未指定旗標。

otDnsServiceMode

 otDnsServiceMode

Type 代表 otDnsQueryConfig 中的服務解決模式。

這個參數只會在 DNS 用戶端服務解析 otDnsClientResolveService() 期間使用。用於決定要查詢的記錄類型。

屬性
OT_DNS_SERVICE_MODE_SRV

僅查詢 SRV 記錄。
OT_DNS_SERVICE_MODE_SRV_TXT

在同一封郵件中查詢 SRV 和 TXT 記錄。
OT_DNS_SERVICE_MODE_SRV_TXT_OPTIMIZE

先同時查詢 TXT/SRV，如果失敗，則分別查詢。
OT_DNS_SERVICE_MODE_SRV_TXT_SEPARATE

使用不同訊息同時查詢 SRV 和 TXT。
OT_DNS_SERVICE_MODE_TXT

僅查詢 TXT 記錄。
OT_DNS_SERVICE_MODE_UNSPECIFIED

未指定模式。使用預設服務模式。

otDnsTransportProto

 otDnsTransportProto

類型代表 otDnsQueryConfig 中的 DNS 傳輸通訊協定。

只有在啟用 OPENTHREAD_CONFIG_DNS_CLIENT_OVER_TCP_ENABLE 時，才能使用這個 OT_DNS_TRANSPORT_TCP。

屬性
OT_DNS_TRANSPORT_TCP

DNS 查詢應透過 UDP 傳送。
OT_DNS_TRANSPORT_UDP

未指定 DNS 傳輸。

Typedefs

otDnsAddressCallback

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

收到位址解析查詢的 DNS 回應時，就會呼叫指標。

在這個回呼中，使用者可以搭配使用 otDnsAddressResponseGet{Item}() 函式與 aResponse 指標，取得關於回應的更多資訊。

aResponse 指標只能在這個回呼中使用，而從這個函式傳回後會失效，因此使用者「不得」保留 aResponse 指標供日後使用。

aError 可以包含下列內容：

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

  • OT_ERROR_NONE 已收到回應。
  • OT_ERROR_ABORT 1 個 DNS 交易已由堆疊取消。
  • OT_ERROR_RESPONSE_TIMEOUT 未在逾時內收到任何 DNS 回應。

如果伺服器拒絕位址解析要求，伺服器提供的錯誤代碼會對應如下：

  • (0) 無錯誤 (沒有錯誤狀況) -> 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 名稱不在可用區 -> 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
回應的指標 (一律為非空值)。
[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
回應的指標 (一律為非空值)。
[in] aContext
指向應用程式特定背景資訊的指標。

otDnsServiceInfo

struct otDnsServiceInfo otDnsServiceInfo

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

otDnsServiceResponse

struct otDnsServiceResponse otDnsServiceResponse

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

這個類型的例項指標是由回呼 otDnsAddressCallback 提供。

otDnsTxtEntry

struct otDnsTxtEntry otDnsTxtEntry

代表代表鍵/值組合的 TXT 記錄項目 (RFC 6763 - 6.3 節)。

mKey 和 mValue 指向的字串緩衝區在傳送至 OpenThread 的執行個體後 (做為 otSrpClientService 執行個體的一部分) 必須保留並保持不變。

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

otDnsTxtEntryIterator

struct otDnsTxtEntryIterator otDnsTxtEntryIterator

代表 TXT 記錄項目 (鍵/值組合) 的疊代器。

這個結構中的資料欄位供 OpenThread 核心使用，呼叫端不應讀取或變更這些欄位。

函式

otDnsAddressResponseGetAddress

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

取得與位址解析 DNS 回應相關聯的 IPv6 位址。

只能在 otDnsAddressCallback內使用。

回應可能會含有多個 IPv6 位址記錄。aIndex 可用於疊代地址清單。索引 0 會取得第一個地址，依此類推。清單上結尾時，系統會傳回 OT_ERROR_NOT_FOUND。

詳細說明
參數
[in] aResponse
回應的指標。
[in] aIndex
要擷取的地址記錄索引。
[out] aAddress
指向用來輸出位址的 IPv6 位址指標 (不得為空值)。
[out] aTtl
指向 uint32_t 的指標，以便輸出位址的存留時間。如果呼叫端不想取得存留時間，可以是空值。
傳回值
OT_ERROR_NONE
已成功讀取地址。
OT_ERROR_NOT_FOUND
aIndex 的 aResponse 中沒有地址記錄。
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
做為輸出完整主機名稱的緩衝區 (不得為空值)。
[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 可用於疊代地址清單。索引 0 會取得第一個地址，依此類推。清單上結尾時，系統會傳回 OT_ERROR_NOT_FOUND。

詳細說明
參數
[in] aResponse
回應的指標。
[in] aHostName
要取得位址的主機名稱 (不得為空值)。
[in] aIndex
要擷取的地址記錄索引。
[out] aAddress
指向用來輸出位址的 IPv6 位址指標 (不得為空值)。
[out] aTtl
指向 uint32_t 的指標，以便輸出位址的存留時間。如果呼叫端不想取得存留時間，可以是空值。
傳回值
OT_ERROR_NONE
已成功讀取地址。
OT_ERROR_NOT_FOUND
aIndex 的 aResponse 中沒有 aHostname 的地址記錄。
OT_ERROR_PARSE
無法剖析 aResponse 中的記錄。

otDnsBrowseResponseGetServiceInfo

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

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

只能在 otDnsBrowseCallback內使用。

瀏覽 DNS 回應可能包含列舉服務執行個體的 SRV、TXT 和 AAAA 記錄。這「不應」要求，且伺服器/解析器不需要提供這項資訊。這個函式會嘗試針對特定服務執行個體 (如果有的話) 擷取這項資訊。

  • 如果在 aResponse 中找不到相符的 SRV 記錄，則會傳回 OT_ERROR_NOT_FOUND。在此情況下，系統不會讀取其他記錄 (沒有 TXT 和/或 AAAA)。
  • 如果在 aResponse 中找到相符的 SRV 記錄，系統會更新 aServiceInfo 並傳回 OT_ERROR_NONE。
  • 如果在 aResponse 中找不到相符的 TXT 記錄，系統會將 aServiceInfo 中的 mTxtDataSize 設為零。
  • 如果 TXT 資料長度大於 mTxtDataSize，系統會讀取部分資料，並將 mTxtDataTruncated 設為 true。
  • 如果 aResponse 中找不到相符的 AAAA 記錄，mHostAddress is set to all zero or unspecified address.
  • 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
服務執行個體標籤 (不得為空值)。
[out] aServiceInfo
用於輸出服務執行個體資訊的 ServiceInfo (不得為空值)。
傳回值
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 可用來疊代整個清單。索引 0 表示第一筆記錄。清單上結尾時，系統會傳回 OT_ERROR_NOT_FOUND。

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

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

otDnsBrowseResponseGetServiceName

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

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

只能在 otDnsBrowseCallback內使用。

詳細說明
參數
[in] aResponse
回應的指標。
[out] aNameBuffer
用來輸出服務名稱的緩衝區 (不得為空值)。
[in] aNameBufferSize
aNameBuffer 的大小。
傳回值
OT_ERROR_NONE
已成功讀取服務名稱。
OT_ERROR_NO_BUFS
名稱不符合 aNameBuffer 格式。

otDnsClientBrowse

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

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

OPENTHREAD_CONFIG_DNS_CLIENT_SERVICE_DISCOVERY_ENABLE啟用後即可使用。

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

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

otDnsClientGetDefaultConfig

const otDnsQueryConfig * otDnsClientGetDefaultConfig(
  otInstance *aInstance
)

取得 DNS 用戶端目前使用的預設查詢設定。

OpenThread 堆疊啟動後，預設的 DNS 查詢設定則取決於 OPENTHREAD_CONFIG_DNS_CLIENT_DEFAULT_SERVER_IP6_ADDRESS、_DEFAULT_SERVER_PORT、_DEFAULT_RESPONSE_TIMEOUT 等 OT 設定選項 (所有相關設定選項請參閱 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 可以是空值。在此情況下，系統會使用「otDnsClientGetDefaultConfig()」的預設設定做為這項查詢的設定。在非 NULL aConfig 中，部分欄位可以保持未指定 (值 0)。接著，未指定的欄位將替換為預設設定的值。

詳細說明
參數
[in] aInstance
指向 OpenThread 執行個體的指標。
[in] aHostName
用來查詢位址的主機名稱 (不得為空值)。
[in] aCallback
要在回應接收或逾時時呼叫的函式指標。
[in] aContext
指向任意背景資訊的指標。
[in] aConfig
要用於這項查詢的設定指標。
傳回值
OT_ERROR_NONE
已成功傳送查詢。系統會叫用 aCallback 來回報狀態。
OT_ERROR_NO_BUFS
緩衝區不足，無法準備及傳送查詢。
OT_ERROR_INVALID_ARGS
主機名稱格式無效。
OT_ERROR_INVALID_STATE
Thread 介面未上線，因此無法傳送查詢。

otDnsClientResolveIp4Address

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

這個外掛程式能傳送指定主機名稱的 A (IPv4) 記錄位址解析 DNS 查詢。

啟用 OPENTHREAD_CONFIG_DNS_CLIENT_NAT64_ENABLE 後即可使用此版本。

系統收到成功回應後，從 aCallback 傳回的位址就會做為 NAT64 IPv6 翻譯版本的查詢回應中的 IPv4 位址。

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

詳細說明
參數
[in] aInstance
指向 OpenThread 執行個體的指標。
[in] aHostName
用來查詢位址的主機名稱 (不得為空值)。
[in] aCallback
要在回應接收或逾時時呼叫的函式指標。
[in] aContext
指向任意背景資訊的指標。
[in] aConfig
要用於這項查詢的設定指標。
傳回值
OT_ERROR_NONE
已成功傳送查詢。系統會叫用 aCallback 來回報狀態。
OT_ERROR_NO_BUFS
緩衝區不足，無法準備及傳送查詢。
OT_ERROR_INVALID_ARGS
主機名稱格式無效，或是設定中未啟用 NAT64。
OT_ERROR_INVALID_STATE
Thread 介面未上線，因此無法傳送查詢。

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 可以是空值。在此情況下，系統會使用「otDnsClientGetDefaultConfig()」的預設設定做為這項查詢的設定。在非 NULL aConfig 中，部分欄位可以保持未指定 (值 0)。接著，未指定的欄位將替換為預設設定的值。

這個函式會傳送指定服務執行個體的 SRV 和/或 TXT 記錄查詢。otDnsQueryConfig 中的 mServiceMode 欄位會決定要查詢的記錄 (僅限 SRV、僅限 TXT，或同時包含 SRV 和 TXT)，以及如何執行查詢 (一起在同一訊息中、同時加入。如果使用最佳化模式，則用戶端會先嘗試在同一訊息中嘗試，並在無法取得回應時單獨嘗試)。

SRV 記錄提供關於服務通訊埠、優先順序和權重的資訊，以及與服務執行個體相關聯的主機名稱。這個函式「不會」為 SRV 記錄找到的主機名稱執行位址解析。伺服器/解析器可能會在 SRV/TXT 查詢回應的「其他資料」部分，為主機名稱提供 AAAA/A 記錄，您可以使用 otDnsServiceCallback 中的 otDnsServiceResponseGetServiceInfo() 擷取這項資訊。這個 API 的使用者「不得」假設 otDnsServiceResponseGetServiceInfo() 將一律提供主機位址。

詳細說明
參數
[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 為空值。

otDnsClientResolveServiceAndHostAddress

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

啟動指定服務執行個體的 DNS 服務執行個體解析，並針對服務執行個體的主機名稱進行可能的後續位址解析。

OPENTHREAD_CONFIG_DNS_CLIENT_SERVICE_DISCOVERY_ENABLE啟用後即可使用。

aConfig 可以是空值。在此情況下，系統會使用「otDnsClientGetDefaultConfig()」的預設設定做為這項查詢的設定。在非 NULL aConfig 中，部分欄位可以保持未指定 (值 0)。接著，未指定的欄位將替換為預設設定的值。在 DNS 設定設為 OT_DNS_SERVICE_MODE_TXT 的情況下，不能搭配 mServiceMode 使用這個函式 (也就是僅查詢 TXT 記錄)，並且會傳回 OT_ERROR_INVALID_ARGS。

作用與 otDnsClientResolveService() 傳送 SRV 和 TXT 記錄查詢的方法類似。不過，如果伺服器/解析器並未在 SRV 查詢 (在「其他資料」部分) 的回應中提供主機名稱的 AAAA/A 記錄，則會針對 SRV 記錄中找到的主機名稱執行主機名稱解析 (傳送 AAAA 查詢)。收到所有查詢的回應 (即完成服務和主機位址解析) 時，系統會叫用 aCallback 回呼。

詳細說明
參數
[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 為空值或 aConfig 無效。

otDnsClientSetDefaultConfig

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

設定 DNS 用戶端的預設查詢設定。

aConfig 可以是空值。在這種情況下，預設設定選項將設為 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 服務項目的 Thread 網路資料，以便選取 SRP 伺服器。所選 SRP 伺服器位址也會在預設設定中設為 DNS 伺服器位址。

詳細說明
參數
[in] aInstance
指向 OpenThread 執行個體的指標。
[in] aConfig
新查詢設定的指標，用來當做預設值。

otDnsEncodeTxtData

otError otDnsEncodeTxtData(
  const otDnsTxtEntry *aTxtEntries,
  uint16_t aNumTxtEntries,
  uint8_t *aTxtData,
  uint16_t *aTxtDataLength
)

這個外掛程式能將指定的 TXT 紀錄項目清單 (鍵/值組合) 編碼為 TXT 資料 (按照 RFC 6763 指定的格式)。

詳細說明
參數
[in] aTxtEntries
指向 otDnsTxtEntry 陣列的指標。
[in] aNumTxtEntries
aTxtEntries 陣列中的項目數量。
[out] aTxtData
指向用來輸出已編碼 TXT 資料的緩衝區指標。
[in,out] aTxtDataLength
在輸入內容時，緩衝區 aTxtData 的大小。輸出時，已編碼的 TXT 資料長度。
傳回值
OT_ERROR_NONE
已成功更新已編碼的 TXT 資料，並更新 aTxtData 和 aTxtDataLength。
OT_ERROR_INVALID_ARGS
aTxtEntries 無效。
OT_ERROR_NO_BUS
無法將編碼的資料與其 aTxtDataLength 放在 aTxtData 緩衝區中。

otDnsGetNextTxtEntry

otError otDnsGetNextTxtEntry(
  otDnsTxtEntryIterator *aIterator,
  otDnsTxtEntry *aEntry
)

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

aIterator 必須先使用 otDnsInitTxtEntryIterator() 初始化，才能呼叫這個函式，用於初始化疊代器的 TXT 資料緩衝區「必須」保存且維持不變。否則此函式的行為未定義。

如果剖析的金鑰字串長度小於或等於 OT_DNS_TXT_KEY_ITER_MAX_LENGTH，金鑰字串會在 aEntry 中的 mKey 中傳回。不過，如果索引鍵較長，則 mKey 會設為 NULL，且經過編碼的完整 TXT 項目字串會在 mValue 和 mValueLength 中傳回。

詳細說明
參數
[in] aIterator
指向疊代器的指標 (不得為空值)。
[out] aEntry
指向 otDnsTxtEntry 結構的指標，用於輸出剖析/讀取的項目 (不得為空值)。
傳回值
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
要初始化的疊代器指標 (不得為空值)。
[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 可用於疊代地址清單。索引 0 會取得第一個地址，依此類推。清單上結尾時，系統會傳回 OT_ERROR_NOT_FOUND。

詳細說明
參數
[in] aResponse
回應的指標。
[in] aHostName
要取得位址的主機名稱 (不得為空值)。
[in] aIndex
要擷取的地址記錄索引。
[out] aAddress
指向用來輸出位址的 IPv6 位址指標 (不得為空值)。
[out] aTtl
指向 uint32_t 的指標，以便輸出位址的存留時間。如果呼叫端不想取得存留時間，可以是空值。
傳回值
OT_ERROR_NONE
已成功讀取地址。
OT_ERROR_NOT_FOUND
aIndex 的 aResponse 中沒有 aHostname 的地址記錄。
OT_ERROR_PARSE
無法剖析 aResponse 中的記錄。

otDnsServiceResponseGetServiceInfo

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

從 DNS 服務執行個體解析回應取得服務執行個體的資訊。

只能使用從 otDnsClientResolveService() 或 otDnsClientResolveServiceAndHostAddress() 觸發的 otDnsServiceCallback。

如果透過 otDnsClientResolveService() 回呼使用這個欄位，伺服器/解析器的 DNS 回應可能會在「其他資料」部分，針對已解析的服務執行個體主機名稱在「其他資料」部分中納入 AAAA 記錄。這並非「強制」規定，且並非「必須」要求，因此伺服器/解析器不必提供這項資訊。如果回應中包含 AAAA 記錄，這個函式會嘗試剖析記錄。如果未包含 mHostAddress，則設為全部零 (未指定地址)。如要一併解析主機位址，使用者也可以使用 DNS 用戶端 API 函式 otDnsClientResolveServiceAndHostAddress()，該函式會在查詢主機名稱位址解析查詢後執行服務解析作業 (當 SRV 查詢回應中沒有伺服器/解析器提供 AAAA 記錄時)。

  • 如果在 aResponse 中找到相符的 SRV 記錄，aServiceInfo 就會更新。
  • 找不到相符的 SRV 記錄，除非這項查詢的查詢設定使用 OT_DNS_SERVICE_MODE_TXT 的 mServiceMode (意即此要求僅用於 TXT 記錄)，否則會傳回 OT_ERROR_NOT_FOUND。在此情況下，我們仍會嘗試從回應的「其他資料」部分剖析 SRV 記錄 (如果伺服器已提供資訊)。
  • 如果在 aResponse 中找不到相符的 TXT 記錄，系統會將 aServiceInfo 中的 mTxtDataSize 設為零。
  • 如果 TXT 資料長度大於 mTxtDataSize，系統會讀取部分資料，並將 mTxtDataTruncated 設為 true。
  • 如果 aResponse 中找不到相符的 AAAA 記錄，mHostAddress is set to all zero or unspecified address.
  • 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 (不得為空值)。
傳回值
OT_ERROR_NONE
服務執行個體資訊已讀取。「aServiceInfo」已更新。
OT_ERROR_NOT_FOUND
在 aResponse 中找不到所需記錄。
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
用來輸出服務執行個體標籤的緩衝區 (不得為空值)。
[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_ITER_MAX_LENGTH

 OT_DNS_TXT_KEY_ITER_MAX_LENGTH 64

otDnsTxtEntryIterator 支援的 TXT 金鑰字串長度上限。

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 取得。如要瞭解詳情或對說明文件做出貢獻，請參閱資源。