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 节)。

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 可用于遍历地址列表。索引 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
aResponseaHostname没有地址记录,时间: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 记录aResponsemHostAddress 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(建议的最大密钥长度),则密钥字符串在 aEntrymKey 中返回。但是,如果键较长,则 mKey 设置为 NULL,mValuemValueLength 中会返回整个编码的 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
aResponseaHostname没有地址记录,时间: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 记录aResponsemHostAddress 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 上找到。 如需了解详情或为我们的文档做贡献,请参阅资源