DNS

此模块包含控制 DNS 通信的功能。

摘要

此模块中的函数仅在 OPENTHREAD_CONFIG_DNS_CLIENT_ENABLE 功能处于启用状态时可用。

枚举
otDnsNat64Mode{
  OT_DNS_NAT64_UNSPECIFIED = 0,
  OT_DNS_NAT64_ALLOW = 1,
  OT_DNS_NAT64_DISALLOW = 2
} 		枚举
type 表示 otDnsQueryConfig 中的 NAT64 模式。
otDnsRecursionFlag{
  OT_DNS_FLAG_UNSPECIFIED = 0,
  OT_DNS_FLAG_RECURSION_DESIRED = 1,
  OT_DNS_FLAG_NO_RECURSION = 2
} 		枚举
type 表示 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
} 		枚举
type 表示 otDnsQueryConfig 中的 DNS 传输协议。

类型定义符
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

type 表示 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

type 表示 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

type 表示 otDnsQueryConfig 中的 DNS 传输协议。

仅当启用 OPENTHREAD_CONFIG_DNS_CLIENT_OVER_TCP_ENABLE 时，才支持此 OT_DNS_TRANSPORT_TCP。

属性
OT_DNS_TRANSPORT_TCP

DNS 查询应通过 UDP 发送。
OT_DNS_TRANSPORT_UDP

未指定 DNS 传输。

类型定义符

otDnsAddressCallback

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_TARGET_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) 因政策/安全原因遭拒 -> 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
指向应用特定上下文的指针。

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 地址的指针（不得为 NULL）。
[out] aTtl
指向用于输出地址 TTL 的 uint32_t 的指针。如果调用方不想获取 TTL，它可以为 NULL。
返回值
OT_ERROR_NONE
已成功读取该地址。
OT_ERROR_NOT_FOUND
在aResponse的aIndex没有地址记录。
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 可用于遍历地址列表。索引 0 表示获取第一个地址，以此类推。当我们到达列表末尾时，将返回 OT_ERROR_NOT_FOUND。

具体说明
参数
[in] aResponse
指向响应的指针。
[in] aHostName
要获取地址的主机名（不得为 NULL）。
[in] aIndex
要检索的地址记录索引。
[out] aAddress
指向用于输出地址的 IPv6 地址的指针（不得为 NULL）。
[out] aTtl
指向用于输出地址 TTL 的 uint32_t 的指针。如果调用方不想获取 TTL，它可以为 NULL。
返回值
OT_ERROR_NONE
已成功读取该地址。
OT_ERROR_NOT_FOUND
没有位于aResponse的aHostname的地址记录（位于aIndex）。
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
服务实例标签（不得为 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 可用于遍历列表。索引 0 表示第一条记录。当我们到达列表末尾时，将返回 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 中不足。

otDnsClientBrowse

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 中，某些字段可以保留为未指定（值零）。然后，未指定的字段会替换为默认配置中的值。

具体说明
参数
[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 中，某些字段可以保留为未指定（值零）。然后，未指定的字段会替换为默认配置中的值。

具体说明
参数
[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
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 返回，作为查询响应中 IPv4 地址的 NAT64 IPv6 转换版本。

aConfig 可以为 NULL。在本例中，默认配置（来自 otDnsClientGetDefaultConfig()）将用作此查询的配置。在非 NULL aConfig 中，某些字段可以保留为未指定（值零）。然后，未指定的字段会替换为默认配置中的值。

具体说明
参数
[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
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 可以为 NULL。在本例中，默认配置（来自 otDnsClientGetDefaultConfig()）将用作此查询的配置。在非 NULL aConfig 中，某些字段可以保留为未指定（值零）。然后，未指定的字段会替换为默认配置中的值。

该函数会查询指定服务实例的 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 为 NULL。

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 可以为 NULL。在本例中，默认配置（来自 otDnsClientGetDefaultConfig()）将用作此查询的配置。在非 NULL aConfig 中，某些字段可以保留为未指定（值零）。然后，未指定的字段会替换为默认配置中的值。此函数不能与设置为 OT_DNS_SERVICE_MODE_TXT 的 DNS 配置中的 mServiceMode 一起使用（即仅查询 TXT 记录），并返回 OT_ERROR_INVALID_ARGS。

行为类似于为 SRV 和 TXT 记录发送查询的 otDnsClientResolveService()。但是，如果服务器/解析器未在 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 是 NULL 或 aConfig 无效。

otDnsClientSetDefaultConfig

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

在 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 服务条目的 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
无法将编码数据放入 aTxtData 缓冲区及其 aTxtDataLength。

otDnsGetNextTxtEntry

otError otDnsGetNextTxtEntry(
  otDnsTxtEntryIterator *aIterator,
  otDnsTxtEntry *aEntry
)

解析来自迭代器的 TXT 数据，并获取下一个 TXT 记录条目（键值对）。

在调用此函数之前，必须使用 otDnsInitTxtEntryIterator() 初始化 aIterator，并且用于初始化迭代器的 TXT 数据缓冲区必须保持不变。否则，此函数的行为将处于未定义状态。

如果解析后的键字符串长度小于或等于 OT_DNS_TXT_KEY_ITER_MAX_LENGTH，则系统会在 aEntry 的 mKey 中返回键字符串。但如果键更长，那么 mKey 会设置为 NULL，整个编码的 TXT 条目字符串会在 mValue 和 mValueLength 中返回。

具体说明
参数
[in] aIterator
指向迭代器的指针（不得为 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 可用于遍历地址列表。索引 0 表示获取第一个地址，以此类推。当我们到达列表末尾时，将返回 OT_ERROR_NOT_FOUND。

具体说明
参数
[in] aResponse
指向响应的指针。
[in] aHostName
要获取地址的主机名（不得为 NULL）。
[in] aIndex
要检索的地址记录索引。
[out] aAddress
指向用于输出地址的 IPv6 地址的指针（不得为 NULL）。
[out] aTtl
指向用于输出地址 TTL 的 uint32_t 的指针。如果调用方不想获取 TTL，它可以为 NULL。
返回值
OT_ERROR_NONE
已成功读取该地址。
OT_ERROR_NOT_FOUND
没有位于aResponse的aHostname的地址记录（位于aIndex）。
OT_ERROR_PARSE
无法解析 aResponse 中的记录。

otDnsServiceResponseGetServiceInfo

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

从 DNS 服务实例解析响应中获取服务实例的信息。

只能在通过 otDnsClientResolveService() 或 otDnsClientResolveServiceAndHostAddress() 触发的 otDnsServiceCallback 中使用。

在 otDnsClientResolveService() 回调中使用此属性时，来自服务器/解析器的 DNS 响应可能会在其“其他数据”部分中，针对与所解析的服务实例关联的主机名添加 AAAA 记录。这是“应”满足但不是“必须”的要求，因此无需服务器/解析器才能提供此项。如果响应中包含 AAAA 记录，此函数会尝试解析 AAAA 记录。如果未添加，mHostAddress 会设为全零（未指定的地址）。如果想同时解析主机地址，用户可以使用 DNS 客户端 API 函数 otDnsClientResolveServiceAndHostAddress()，该函数将执行服务解析，随后执行主机名地理编码查询（当 SRV 查询响应中的服务器/解析器未提供 AAAA 记录时）。

  • 如果在 aResponse 中找到了匹配的 SRV 记录，系统会更新 aServiceInfo。
  • 如果未找到匹配的 SRV 记录，则系统会返回 OT_ERROR_NOT_FOUND，除非此查询的查询配置将 OT_DNS_SERVICE_MODE_TXT 用于 mServiceMode（这意味着该请求仅适用于 TXT 记录）。在这种情况下，我们仍会尝试从响应的“其他数据”部分解析 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（不得为 NULL）。
返回值
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
一个缓冲区到字符数组，用于输出服务实例标签（不得为 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

标签字符串大小上限（在字符串末尾包括 null 字符）。

OT_DNS_MAX_NAME_SIZE

 OT_DNS_MAX_NAME_SIZE 255

名称字符串大小上限（包括字符串末尾的 null 字符）。

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 上提供的源代码。如需了解详情，或者为我们的文档做贡献，请参阅资源。