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

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 中的“递归期望”(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
}
枚举
此枚举类型表示 otDnsQueryConfig 中的服务解析模式。
otDnsTransportProto{
  OT_DNS_TRANSPORT_UDP = 1,
  OT_DNS_TRANSPORT_TCP = 2
}
枚举
此枚举类型表示 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 服务实例解析查询。
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 中的“递归期望”(RD) 标志。

属性
OT_DNS_FLAG_NO_RECURSION

表示 DNS 域名服务器无法以递归方式解析查询。

OT_DNS_FLAG_RECURSION_DESIRED

表示 DNS 域名服务器可以递归解析查询。

OT_DNS_FLAG_UNSPECIFIED

表示未指定该标志。

otDnsServiceMode

 otDnsServiceMode

此枚举类型表示 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 传输。

类型定义符

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_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 名称不在可用区 -> 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 节)。

mKeymValue 所指向的字符串缓冲区在此类结构的实例被传递到 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 可用于迭代地址列表。索引零会获取第一个地址,以此类推。当我们到达列表末尾时,会返回 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
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 可用于迭代地址列表。索引零会获取第一个地址,以此类推。当我们到达列表末尾时,会返回 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
aResponseaIndex 没有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
服务实例标签(不得为 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
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 地址的 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 中,某些字段可以未指定(值为零)。未指定的字段将替换为默认配置中的值。

此函数为给定服务实例发送对 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。

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,而整个编码 TXT 条目字符串会在 mValuemValueLength 中返回。

详细说明
参数
[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 的长度(字节数)。

otDnsIsName 压缩状态已启用

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 的指针,用于输出地址的 TTL。如果调用方不希望获取 TTL,该参数可以为 NULL。
返回值
OT_ERROR_NONE
地址读取成功。
OT_ERROR_NOT_FOUND
aResponseaIndex 没有aHostname 的地址记录。
OT_ERROR_PARSE
无法解析 aResponse 中的记录。

otDnsServiceResponseGetServiceInfo

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

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

此函数必须仅从 otDnsServiceCallback 使用。

对于与所解析的服务实例关联的主机名,服务解析 DNS 响应可能会在其“附加数据”部分包含 AAAA 记录。这是一个“应”而非“必须”要求,因此不需要服务器/解析器来提供此信息。如果响应中包含 AAAA 记录,此函数会尝试检索该记录。如果不包含,mHostAddress 会设为全零(未指定地址)。如果调用方想要解析主机地址,它可以使用主机名调用 otDnsClientResolveAddress() 以启动解析查询。

  • 如果在 aResponse 中找到匹配的 SRV 记录,则更新 aServiceInfo
  • 如果未找到匹配的 SRV 记录,除非该查询的查询配置针对 mServiceMode 使用 OT_DNS_SERVICE_MODE_TXT(这意味着该请求仅针对 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,用于输出服务实例信息(不得为 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
标签或名称不适合给定的缓冲区。

otDnsSetName 压缩类型已启用

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 上获取。 如需了解详情或为我们的文档贡献内容,请参阅资源