DNS
此模块包含用于控制 DNS 通信的函数。
总结
只有在启用了 OPENTHREAD_CONFIG_DNS_CLIENT_ENABLE
功能后,此模块中的函数才可用。
枚举 |
|
---|---|
otDnsNat64Mode{
|
枚举 此枚举类型表示 otDnsQueryConfig 中的 NAT64 模式。 |
otDnsRecursionFlag{
|
枚举 此枚举类型表示 otDnsQueryConfig 中的“递归期望”(RD) 标志。 |
otDnsServiceMode{
|
枚举 此枚举类型表示 otDnsQueryConfig 中的服务解析模式。 |
otDnsTransportProto{
|
枚举 此枚举类型表示 otDnsQueryConfig 中的 DNS 传输协议。 |
类型定义符 |
|
---|---|
otDnsAddressCallback)(otError aError, const otDnsAddressResponse *aResponse, void *aContext)
|
typedefvoid(*
收到解析地址的 DNS 响应时,系统会调用此函数指针。 |
otDnsAddressResponse
|
typedefstruct otDnsAddressResponse
此类型是对地址解析 DNS 查询的响应的不透明表示。 |
otDnsBrowseCallback)(otError aError, const otDnsBrowseResponse *aResponse, void *aContext)
|
typedefvoid(*
当收到浏览(服务实例枚举)查询的 DNS 响应时,系统会调用此函数指针。 |
otDnsBrowseResponse
|
typedefstruct otDnsBrowseResponse
此类型是对浏览(服务实例枚举)DNS 查询的响应的不透明表示。 |
otDnsQueryConfig
|
typedefstruct otDnsQueryConfig
此结构表示 DNS 查询配置。 |
otDnsServiceCallback)(otError aError, const otDnsServiceResponse *aResponse, void *aContext)
|
typedefvoid(*
收到服务实例解析查询的 DNS 响应时,系统会调用此函数指针。 |
otDnsServiceInfo
|
typedefstruct otDnsServiceInfo
此结构为 DNS 服务实例提供信息。 |
otDnsServiceResponse
|
typedefstruct otDnsServiceResponse
此类型是对服务实例解析 DNS 查询的响应的不透明表示。 |
otDnsTxtEntry
|
typedefstruct otDnsTxtEntry
此结构表示代表键值对的 TXT 记录条目(RFC 6763 - 第 6.3 节)。 |
otDnsTxtEntryIterator
|
typedefstruct otDnsTxtEntryIterator
此结构表示 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)
|
const otDnsQueryConfig *
此函数会获取 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
可以具有以下各项:
详细说明 | |||||||
---|---|---|---|---|---|---|---|
参数 |
|
- 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()
。
详细说明 | |||||||
---|---|---|---|---|---|---|---|
参数 |
|
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()
。
详细说明 | |||||||
---|---|---|---|---|---|---|---|
参数 |
|
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
可用于迭代地址列表。索引零会获取第一个地址,以此类推。当我们到达列表末尾时,会返回 OT_ERROR_NOT_FOUND
。
详细说明 | |||||||||
---|---|---|---|---|---|---|---|---|---|
参数 |
|
||||||||
返回值 |
|
otDnsAddressResponseGetHostName
otError otDnsAddressResponseGetHostName( const otDnsAddressResponse *aResponse, char *aNameBuffer, uint16_t aNameBufferSize )
此函数会获取与地址解析 DNS 响应相关联的完整主机名。
此函数必须仅从 otDnsAddressCallback
使用。
详细说明 | |||||||
---|---|---|---|---|---|---|---|
参数 |
|
||||||
返回值 |
|
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
。
详细说明 | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
参数 |
|
||||||||||
返回值 |
|
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 using
otDnsBrowseResponseGetHostAddress()`。
详细说明 | |||||||||
---|---|---|---|---|---|---|---|---|---|
参数 |
|
||||||||
返回值 |
|
otDnsBrowseResponseGetServiceInstance
otError otDnsBrowseResponseGetServiceInstance( const otDnsBrowseResponse *aResponse, uint16_t aIndex, char *aLabelBuffer, uint8_t aLabelBufferSize )
此函数会获取与 DNS 浏览(服务实例枚举)响应相关联的服务实例。
此函数必须仅从 otDnsBrowseCallback
使用。
响应可能包含多条服务实例记录。aIndex
可用于迭代列表。索引 0 表示第一条记录。当我们到达列表末尾时,会返回 OT_ERROR_NOT_FOUND
。
请注意,此函数会获取服务实例标签,而不是
形式的完整服务实例名称。
详细说明 | |||||||||
---|---|---|---|---|---|---|---|---|---|
参数 |
|
||||||||
返回值 |
|
otDnsBrowseResponseGetServiceName
otError otDnsBrowseResponseGetServiceName( const otDnsBrowseResponse *aResponse, char *aNameBuffer, uint16_t aNameBufferSize )
此函数会获取与 DNS 浏览(服务实例枚举)响应关联的服务名称。
此函数必须仅从 otDnsBrowseCallback
使用。
详细说明 | |||||||
---|---|---|---|---|---|---|---|
参数 |
|
||||||
返回值 |
|
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
中,某些字段可以未指定(值为零)。未指定的字段将替换为默认配置中的值。
详细说明 | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
参数 |
|
||||||||||
返回值 |
|
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
)。
详细说明 | |||
---|---|---|---|
参数 |
|
||
返回 |
指向 DNS 客户端正在使用的当前默认配置的指针。
|
otDnsClientResolveAddress
otError otDnsClientResolveAddress( otInstance *aInstance, const char *aHostName, otDnsAddressCallback aCallback, void *aContext, const otDnsQueryConfig *aConfig )
此函数针对给定主机名发送针对 AAAA (IPv6) 记录的地址解析 DNS 查询。
aConfig
可以为 NULL。在这种情况下,默认配置(来自 otDnsClientGetDefaultConfig()
)将用作此查询的配置。在非 NULL aConfig
中,某些字段可以未指定(值为零)。未指定的字段将替换为默认配置中的值。
详细说明 | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
参数 |
|
||||||||||
返回值 |
|
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
中,某些字段可以未指定(值为零)。未指定的字段将替换为默认配置中的值。
详细说明 | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
参数 |
|
||||||||||
返回值 |
|
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()
访问。
详细说明 | |||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|
参数 |
|
||||||||||||
返回值 |
|
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 服务器地址。
详细说明 | |||||
---|---|---|---|---|---|
参数 |
|
otDnsGetNextTxtEntry
otError otDnsGetNextTxtEntry( otDnsTxtEntryIterator *aIterator, otDnsTxtEntry *aEntry )
此函数会从迭代器解析 TXT 数据,并获取下一个 TXT 记录条目(键值对)。
aIterator
必须在调用此函数之前使用 otDnsInitTxtEntryIterator()
进行初始化,而且用于初始化迭代器的 TXT 数据缓冲区必须保持不变。否则,此函数的行为将处于未定义状态。
如果解析的密钥字符串长度小于或等于 OT_DNS_TXT_KEY_MAX_LENGTH
(建议的密钥长度上限),则系统会在 aEntry
的 mKey
中返回密钥字符串。但是,如果键更长,那么 mKey
会设置为 NULL,而整个编码 TXT 条目字符串会在 mValue
和 mValueLength
中返回。
详细说明 | |||||||
---|---|---|---|---|---|---|---|
参数 |
|
||||||
返回值 |
|
otDnsInitTxtEntryIterator
void otDnsInitTxtEntryIterator( otDnsTxtEntryIterator *aIterator, const uint8_t *aTxtData, uint16_t aTxtDataLength )
此函数初始化 TXT 记录迭代器。
使用 aIterator
对象时,缓冲区指针 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
。
详细说明 | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
参数 |
|
||||||||||
返回值 |
|
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 using
otDnsServiceResponseGetHostAddress()`。
详细说明 | |||||||||
---|---|---|---|---|---|---|---|---|---|
参数 |
|
||||||||
返回值 |
|
otDnsServiceResponseGetServiceName
otError otDnsServiceResponseGetServiceName( const otDnsServiceResponse *aResponse, char *aLabelBuffer, uint8_t aLabelBufferSize, char *aNameBuffer, uint16_t aNameBufferSize )
此函数会获取与 DNS 服务实例解析响应相关联的服务实例名称。
此函数必须仅从 otDnsServiceCallback
使用。
详细说明 | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
参数 |
|
||||||||||
返回值 |
|
otDnsSetName 压缩类型已启用
void otDnsSetNameCompressionEnabled( bool aEnabled )
此函数启用/停用“DNS 名称压缩”模式。
默认情况下,DNS 名称压缩处于启用状态。停用后,DNS 名称会附加为完整名称,且永远不会被压缩。这适用于 OpenThread 的 DNS 和 SRP 客户端/服务器模块。
此配置仅用于测试目的,且在启用 OPENTHREAD_CONFIG_REFERENCE_DEVICE_ENABLE
配置后可用。
请注意,在使用 OPENTHREAD_CONFIG_MULTIPLE_INSTANCE_ENABLE
时,此模式适用于所有 OpenThread 实例(即,调用此函数会为所有 OpenThread 实例启用/停用压缩模式)。
详细说明 | |||
---|---|---|---|
参数 |
|
宏
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 上获取。 如需了解详情或为我们的文档贡献内容,请参阅资源。