Google 致力于为黑人社区推动种族平等。查看具体行动。

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 中的“Recursion Desired”(RD) 标记。

类型定义符
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 服务实例解析查询。
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 记录整数（键值对）的迭代器。

枚举

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

表示未指定标志。

类型定义符

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_RESPONSE_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_IMPLMENTED
  • (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
指向响应的指针（始终为非 NULL）。
[in] aContext
指向应用特定上下文的指针。

otDnsBrowseResponse

struct otDnsBrowseResponse otDnsBrowseResponse

此类型是浏览（服务实例枚举）DNS 查询的响应的不透明表示形式。

指向此类实例的指针由回调 otDnsBrowseCallback 提供。

otDnsQueryConfig

struct otDnsQueryConfig otDnsQueryConfig

此结构表示 DNS 查询配置。

此结构中的任何字段均可设为 0，以表示未指定。未指定字段的处理方式由使用 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
指向 uint32_t 的指针，用于输出地址 TTL。如果调用方不希望获取 TTL，可以为 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 可用于遍历地址列表。索引 0 获取第一个地址，以此类推。到达列表末尾时，系统会返回 OT_ERROR_NOT_FOUND。

详情
参数
[in] aResponse
指向响应的指针。
[in] aHostName
用于获取地址的主机名（不得为 NULL）。
[in] aIndex
要检索的地址记录索引。
[out] aAddress
指向输出地址的 IPv6 地址的指针（不得为 NULL）。
[out] aTtl
指向 uint32_t 的指针，用于输出地址 TTL。如果调用方不希望获取 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。
  • 如果在 aResponse 中找到匹配的 SRV 记录，则系统会更新 aServiceInfo 并返回 OT_ERROR_NONE。
  • 如果在 aResponse 中找不到匹配的 TXT 记录，则 aServiceInfo 中的 mTxtDataSize 会设为零。
  • 如果在 中找不到匹配的 AAAA 记录aResponse、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
用于输出服务实例标签的 char 数组的缓冲区（不得为 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，

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
无法发送查询，因为线程界面尚未启动。

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 返回，作为查询响应中的 IPv6 地址的 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
无法发送查询，因为线程界面尚未启动。

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

详情
参数
[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
指向迭代器的指针（不得为 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 记录迭代器。

缓冲区指针 aTxtData 及其内容必须在使用 aIterator 对象期间保留并保持不变。

详情
参数
[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
指向 uint32_t 的指针，用于输出地址 TTL。如果调用方不希望获取 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 服务实例解析响应中获取服务实例的信息。

只能从 otDnsServiceCallback 使用此函数。

  • 如果在 aResponse 中找不到匹配的 SRV 记录，则返回 OT_ERROR_NOT_FOUND。
  • 如果在 aResponse 中找到匹配的 SRV 记录，则系统会更新 aServiceInfo 并返回 OT_ERROR_NONE。
  • 如果在 aResponse 中找不到匹配的 TXT 记录，则 aServiceInfo 中的 mTxtDataSize 会设为零。
  • 如果在 中找不到匹配的 AAAA 记录aResponse、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 中找不到匹配的 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
用于输出服务实例标签的 char 数组的缓冲区（不得为 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_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 上找到。 如需了解详情或为我们的文档做贡献，请参阅资源。