第 3 章 - Azure RTOS NetX Duo DNS 客户端服务说明

本章按字母顺序介绍了所有 Azure RTOS NetX DNS 服务(如下所列)。

在以下 API 说明的“返回值”部分中,以粗体显示的值不受定义用于禁用 API 错误检查的 NX_DISABLE_ERROR_CHECKING 影响,而不以粗体显示的值会被完全禁用。

nx_dns_authority_zone_start_get

查找输入主机授权的区域开头

原型

UINT nx_dns_authority_zone_start_get (
    NX_DNS *dns_ptr, UCHAR *host_name, 
    VOID *record_buffer,                                        
    UINT buffer_size, 
    UINT *record_count, 
    ULONG wait_option);

说明

如果定义了 NX_DNS_ENABLE_EXTENDED_RR_TYPES,则此服务发送带有指定域名的 SOA 类型查询,以获取输入域名的授权区域的起始部分。 DNS 客户端会将 DNS 服务器响应中返回的 SOA 记录复制到 record_buffer 内存位置。

注意

record_buffer 必须是 4 字节对齐的,才能接收数据。

在 NetX Duo DNS 客户端中,SOA 记录类型 NX_DNS_SOA_ENTRY 被保存为 7 个 4 字节参数(总共 28 字节):

  • nx_dns_soa_host_mname_ptr:指向此区域的主要数据源的指针。
  • nx_dns_soa_host_rname_ptr:指向此区域专用邮箱的指针
  • nx_dns_soa_serial:区域版本号
  • nx_dns_soa_refresh:刷新间隔
  • nx_dns_soa_retry:SOA 查询重试间隔
  • nx_dns_soa_expire:SOA 过期时的持续时间
  • nx_dns_soa_minmum:SOA 主机名 DNS 回复消息中的最小 TTL 字段

下面显示了两个 SOA 记录的存储方式。 从缓冲区的顶部开始输入包含固定长度数据的 SOA 记录。 指针 MNAME 和 RNAME 指向可变长度数据(主机名),这类数据存储在缓冲区底部。 额外 SOA 记录(“额外 SOA 记录”)在第一条记录之后输入,它们的可变长度数据(“额外 SOA 可变长度数据”)存储在最后一条记录的可变长度数据之上:

The storage of a two SOA records

如果输入 record_buffer 无法保留服务器答复中的所有 SOA 数据,那么 record_buffer 会保留尽可能多的记录,并返回缓冲区中的记录数。

使用 *record_count 中返回的 SOA 记录数,应用程序可分析 record_buffer 中的数据,并提取授权主机名字符串的区域开头。

输入参数

  • dns_ptr:指向 DNS 客户端的指针。
  • host_name:指向主机名以获取其 SOA 数据的指针
  • record_buffer:指向相应位置以从中提取 SOA 数据的指针
  • buffer_size:保存 SOA 数据所用缓冲区的大小
  • record_count:指向所检索 SOA 记录数的指针
  • wait_option:用于接收 DNS 服务器响应的等待选项

返回值

  • NX_SUCCESS (0x00):已成功获取 SOA 数据
  • NX_DNS_NO_SERVER (0xA1):客户端服务器列表是空的
  • NX_DNS_QUERY_FAILED (0xA3):没有收到有效的 DNS 响应
  • NX_PTR_ERROR (0x07):IP 或 DNS 指针无效
  • NX_CALLER_ERROR (0x11):此服务的调用方无效
  • NX_DNS_PARAM_ERROR (0xA8):非指针输入无效

允许调用自

线程数

示例

UCHAR  record_buffer[50];
UINT   record_count;   
NX_DNS_SOA_ENTRY *nx_dns_soa_entry_ptr;

/* Request the start of authority zone(s) for the specified host. */
status =  nx_dns_authority_zone_start_get(&client_dns, (UCHAR *)"www.my_example.com",  
										  record _buffer, sizeof(record_buffer), 
										  &record_count, 500);

/* Check for DNS query error. */
if (status != NX_SUCCESS)
{
         error_counter++;
}
else 
{
	/* If status is NX_SUCCESS a DNS query was successfully completed and SOA data 
	   is returned in soa_buffer. */

	/* Set a local pointer to the SOA buffer. */
	nx_dns_soa_entry_ptr = (NX_DNS_SOA_ENTRY *) record_buffer;

	printf("------------------------------------------------------\n");
	printf("Test SOA: \n");
	printf("serial = %d\n", nx_dns_soa_entry_ptr -> nx_dns_soa_serial );
	printf("refresh = %d\n", nx_dns_soa_entry_ptr -> nx_dns_soa_refresh );
	printf("retry = %d\n", nx_dns_soa_entry_ptr -> nx_dns_soa_retry );
	printf("expire = %d\n", nx_dns_soa_entry_ptr -> nx_dns_soa_expire );
	printf("minmum = %d\n", nx_dns_soa_entry_ptr -> nx_dns_soa_minmum );

	if(nx_dns_soa_entry_ptr -> nx_dns_soa_host_mname_ptr)
	{
		printf("host mname = %s\n", 
			   nx_dns_soa_entry_ptr -> nx_dns_soa_host_mname_ptr);
	}
	else
	{
		printf("host mame is not set\n");
	}

	if(nx_dns_soa_entry_ptr -> nx_dns_soa_host_rname_ptr)
	{
		printf("host rname = %s\n", 
			   nx_dns_soa_entry_ptr -> nx_dns_soa_host_rname_ptr);
	}
	else
	{
	 
		printf("host rname is not set\n");
	}
}

[Output]
----------------------------------------------------
Test SOA: 
serial = 2012111212
refresh = 7200
retry = 1800
expire = 1209600
minmum = 300
host mname = ns1.www.my_example.com
host rname = dns-admin.www.my_example.com

nx_dns_cache_initialize

初始化 DNS 缓存

原型

UINT nx_dns_cache_initialize(
    NX_DNS *dns_ptr,
    VOID *cache_ptr,
    UINT cache_size);

说明

此服务可创建并初始化 DNS 缓存。

输入参数

  • dns_ptr:指向 DNS 控制块的指针。
  • cache_ptr:指向 DNS 缓存的指针。
  • cache_size:DNS 缓存大小(以字节为单位)。

返回值

  • NX_SUCCESS (0x00):已成功初始化 DNS 缓存
  • NX_DNS_PARAM_ERROR (0xA8):非指针输入无效
  • NX_DNS_CACHE_ERROR (0xB7):缓存指针无效。
  • NX_PTR_ERROR (0x07):DNS 指针无效。
  • NX_DNS_ERROR (0xA0):缓存不是 4 字节对齐的。

允许调用自

线程数

示例

/* Initialize the DNS Cache.  */
status =  nx_dns_cache_initialize(&my_dns, &dns_cache, 2048);

/* If status is NX_SUCCESS DNS Cache was successfully initialized.  */

nx_dns_cache_notify_clear

清除“DNS 缓存已满”通知函数

原型

UINT nx_dns_cache_notify_clear(NX_DNS *dns_ptr);

说明

此服务可清除“缓存已满”通知函数。

输入参数

  • dns_ptr:指向 DNS 控制块的指针。

返回值

  • NX_SUCCESS (0x00):已成功设置 DNS 缓存通知
  • NX_DNS_PARAM_ERROR (0xA8):非指针输入无效
  • NX_PTR_ERROR (0x07):DNS 指针无效。

允许调用自

线程数

示例

/* Clear the DNS Cache full notify function. */
status =  nx_dns_cache_notify_clear(&my_dns);

/* If status is NX_SUCCESS DNS Cache full notify function was successfully cleared. */

nx_dns_cache_notify_set

设置“DNS 缓存已满”通知函数

原型

UINT nx_dns_cache_notify_set(
    NX_DNS *dns_ptr,
    VOID (*cache_full_notify_cb)(NX_DNS *dns_ptr));

说明

此服务可设置“缓存已满”通知函数。

输入参数

  • dns_ptr:指向 DNS 控制块的指针。
  • cache_full_notify_cb:在缓存已满时要调用的回调函数。

返回值

  • NX_SUCCESS (0x00):已成功设置 DNS 缓存通知
  • NX_DNS_PARAM_ERROR (0xA8):非指针输入无效
  • NX_PTR_ERROR (0x07):DNS 指针无效。

允许调用自

线程数

示例

/* Set the DNS Cache full notify function. */
status =  nx_dns_cache_notify_set(&my_dns, cache_full_notify_cb);

/* If status is NX_SUCCESS DNS Cache full notify function was successfully set. */

nx_dns_cname_get

查找输入主机名的规范名称

原型

UINT nx_dns_cname_get(
    NX_DNS *dns_ptr,
    UCHAR *host_name, 
    UCHAR *record_buffer,
    UINT buffer_size, 
    ULONG wait_option);

说明

如果在 nxd_dns.h 中定义了 NX_DNS_ENABLE_EXTENDED_RR_TYPES,则此服务发送带有指定域名的 CNAME 类型查询,以获取规范域名。 DNS 客户端会将 DNS 服务器响应中返回的 CNAME 字符串复制到 record_buffer 内存位置。

输入参数

  • dns_ptr:指向 DNS 客户端的指针。
  • host_name:指向主机名以获取其 CNAME 数据的指针
  • record_buffer:指向相应位置以从中提取 CNAME 数据的指针
  • buffer_size:保存 CNAME 数据所用缓冲区的大小
  • wait_option:用于接收 DNS 服务器响应的等待选项

返回值

  • NX_SUCCESS (0x00):已成功获取 CNAME 数据
  • NX_DNS_NO_SERVER (0xA1):客户端服务器列表是空的
  • NX_DNS_QUERY_FAILED (0xA3):没有收到有效的 DNS 响应
  • NX_PTR_ERROR (0x07):IP 或 DNS 指针无效
  • NX_CALLER_ERROR (0x11):此服务的调用方无效
  • NX_DNS_PARAM_ERROR (0xA8):非指针输入无效

允许调用自

线程数

示例

CHAR            record _buffer[50];

/* Request the canonical name for the specified host. */
status =  nx_dns_cname_get(&client_dns, (UCHAR *)"www.my_example.com ", 
                                   record_buffer, sizeof(record_buffer), 500);

/* Check for DNS query error. */
if (status != NX_SUCCESS)
{
    error_counter++;
}
else     
{
/* If status is NX_SUCCESS a DNS query was successfully completed and 
   the canonical host name is returned in record_buffer. */

    printf("------------------------------------------------------\n");
    printf("Test CNAME: %s\n", record_buffer);
} 

[Output]
----------------------------------------------------
Test CNAME: my_example.com

nx_dns_create

创建 DNS 客户端实例

原型

UINT nx_dns_create(
    NX_DNS *dns_ptr,
    NX_IP *ip_ptr,
    CHAR *domain_name);

说明

此服务可为以前创建的 IP 实例创建 DNS 客户端实例。

重要

应用程序必须确保 DNS 客户端使用的数据包池的数据包有效负载足够大,能够容纳最大 512 字节的 DNS 消息,以及 UDP 头、IP 头和以太网头。 如果 DNS 客户端创建它自己的数据包池,则由 NX_DNS_PACKET_PAYLOAD 和 NX_DNS_PACKET_POOL_SIZE 来定义。

如果 DNS 客户端应用程序更愿意提供之前创建的数据包池,则 IPv4 DNS 客户端的有效负载应能够容纳最大 512 字节的 DNS 消息,以及 20 字节的 IP 头、8 字节的 UDP 头和 14 字节的以太网头。 对于 IPv6,唯一不同的是 IP 头是 40 字节,因此数据包需要容纳 40 字节的 IPv6 头。

输入参数

  • dns_ptr:指向 DNS 客户端的指针。
  • ip_ptr:指向以前所创建 IP 实例的指针。
  • domain_name:指向 DNS 实例域名的指针。

返回值

  • NX_SUCCESS (0x00):已成功创建 DNS 客户端实例
  • NX_DNS_ERROR (0xA0):DNS 创建错误
  • NX_PTR_ERROR (0x07):IP 或 DNS 指针无效
  • NX_CALLER_ERROR (0x11):此服务的调用方无效

允许来自

线程数

示例

/* Create a DNS Client instance. */
status =  nx_dns_create(&my_dns, &my_ip, "My DNS");

/* If status is NX_SUCCESS a DNS Client instance was successfully
   created. */

nx_dns_delete

删除 DNS 客户端实例

原型

UINT nx_dns_delete(NX_DNS *dns_ptr);

说明

此服务用于删除之前创建的 DNS 客户端实例,并释放其资源。

注意

如果定义了 NX_DNS_CLIENT_USER_CREATE_PACKET_POOL,并为 DNS 客户端分配了用户定义的数据包池,则由应用程序删除不再需要的 DNS 客户端数据包池。

输入参数

  • dns_ptr:指向之前创建的 DNS 客户端实例的指针。

返回值

  • NX_SUCCESS (0x00):已成功删除 DNS 客户端。
  • NX_PTR_ERROR (0x07):IP 或 DNS 客户端指针无效。
  • NX_CALLER_ERROR (0x11):此服务的调用方无效。

允许来自

线程数

示例

/* Delete a DNS Client instance. */
status =  nx_dns_delete(&my_dns);

/* If status is NX_SUCCESS the DNS Client instance was successfully
   deleted. */

nx_dns_domain_name_server_get

查找输入域区域的授权名称服务器

原型

UINT nx_dns_domain_name_server_get(
    NX_DNS *dns_ptr,
    UCHAR *host_name, 
    VOID *record_buffer,
    UINT buffer_size, 
    UINT *record_count,
    ULONG wait_option);

说明

如果已定义 NX_DNS_ENABLE_EXTENDED_RR_TYPES,此服务可使用指定域名发送类型为 NS 的查询,以便获取输入域名的名称服务器。 DNS 客户端会将 DNS 服务器响应中返回的 NS 记录复制到 record_buffer 内存位置。

注意

record_buffer 必须是 4 字节对齐的,才能接收数据。

在 NetX Duo DNS 客户端中,NS 数据类型 NX_DNS_NS_ENTRY 保存为 2 个 4 字节参数:

  • nx_dns_ns_ipv4_address:名称服务器的 IPv4 地址
  • nx_dns_ns_hostname_ptr:指向名称服务器主机名的指针

下面显示的缓冲区包含四个 NX_DNS_NS_ENTRY 记录。 每个条目中指向主机名字符串的指针都指向缓冲区下半部分中相应的主机名字符串:

Contains four NX_DNS_NS_ENTRY records

如果输入 record_buffer 无法保留服务器答复中的所有 NS 数据,那么 record_buffer 会保留尽可能多的记录,并返回缓冲区中的记录数。

使用 *record_count 中返回的 NS 记录数,应用程序可分析 record_buffer 中每个记录的 IP 地址和主机名。

输入参数

  • dns_ptr:指向 DNS 客户端的指针。
  • host_name:指向主机名以获取其 NS 数据的指针
  • record_buffer:指向相应位置以从中提取 NS 数据的指针
  • buffer_size:保存 NS 数据所用缓冲区的大小
  • record_count:指向所检索 NS 记录数的指针
  • wait_option:用于接收 DNS 服务器响应的等待选项

返回值

  • NX_SUCCESS (0x00):已成功获取 NS 数据
  • NX_DNS_NO_SERVER (0xA1):客户端服务器列表是空的
  • NX_DNS_QUERY_FAILED (0xA3):没有收到有效的 DNS 响应
  • NX_DNS_PARAM_ERROR (0xA8):非指针输入无效
  • NX_PTR_ERROR (0x07):IP 或 DNS 指针无效
  • NX_CALLER_ERROR (0x11):此服务的调用方无效

允许来自

线程数

示例

#define RECORD_COUNT    10

ULONG  record_buffer[50];
UINT   record_count;          
NX_DNS_NS_ENTRY  *nx_dns_ns_entry_ptr[RECORD_COUNT];

/* Request the name server(s) for the specified host. */
status =  nx_dns_domain_name_server_get(&client_dns, (UCHAR *)" www.my_example.com ",  
									    record_buffer, sizeof(record_buffer),  
									    &record_count, 500);

/* Check for DNS query error. */
if (status != NX_SUCCESS)
{
    error_counter++;
}

else     
{
/* If status is NX_SUCCESS a DNS query was successfully completed and NS data
   is returned in record_buffer. */

    printf("------------------------------------------------------\n");
    printf("Test NS: ");
    printf("record_count = %d \n", record_count);      

    /* Get the name server. */
    for(i =0; i< record_count; i++)
    {
        nx_dns_ns_entry_ptr[i] = (NX_DNS_NS_ENTRY *)
							   (record_buffer + i * sizeof(NX_DNS_NS_ENTRY)); 

        printf("record %d: IP address: %d.%d.%d.%d\n", i, 
                      nx_dns_ns_entry_ptr[i] -> nx_dns_ns_ipv4_address  >> 24,
                      nx_dns_ns_entry_ptr[i] -> nx_dns_ns_ipv4_address >> 16 & 0xFF,                   
                      nx_dns_ns_entry_ptr[i] -> nx_dns_ns_ipv4_address >> 8 & 0xFF,
                     nx_dns_ns_entry_ptr[i] -> nx_dns_ns_ipv4_address & 0xFF);
        if(nx_dns_ns_entry_ptr[i] -> nx_dns_ns_hostname_ptr)
        {
            printf("hostname = %s\n", 
                    nx_dns_ns_entry_ptr[i] -> nx_dns_ns_hostname_ptr);
                }
        else
            printf("hostname is not set\n");
    }
}

[Output]
------------------------------------------------------
Test NS: record_count = 4 
record 0: IP address: 192.2.2.10
hostname = ns2.www.my_example.com
record 1: IP address: 192.2.2.11
hostname = ns1.www.my_example.com
record 2: IP address: 192.2.2.12
hostname = ns3.www.my_example.com
record 3: IP address: 192.2.2.13
hostname = ns4.www.my_example.com

nx_dns_domain_mail_exchange_get

查找输入主机名的邮件交换

原型

UINT nx_dns_domain_mail_exchange_get(
    NX_DNS *dns_ptr,
    UCHAR *host_name, 
    VOID *record_buffer,                                        
    UINT buffer_size, 
    UINT *record_count, 
    ULONG wait_option);

说明

如果定义了 NX_DNS_ENABLE_EXTENDED_RR_TYPES,则此服务发送带有指定域名的 MX 类型查询,以获取输入域名的邮件交换。 DNS 客户端会将 DNS 服务器响应中返回的 MX 记录复制到 record_buffer 内存位置。

注意

record_buffer 必须是 4 字节对齐的,才能接收数据。

在 NetX Duo DNS 客户端中,邮件交换记录类型 NX_DNS_MAIL_EXCHANGE_ENTRY 保存为 4 个参数(总共 12 字节):

  • nx_dns_mx_ipv4_address:邮件交换 IPv4 地址(4 字节)
  • nx_dns_mx_preference:首选项(2 字节)
  • nx_dns_mx_reserved0:保留 2 字节
  • nx_dns_mx_hostname_ptr:指向邮件交换服务器主机名的指针(4 字节)

下面显示的缓冲区包含四个 MX 记录。 每个记录的固定长度数据都显示在列表上方。 指向邮件交换服务器主机名的指针指向缓冲区末尾相应的主机名。

A buffer containing four MX records

如果输入 record_buffer 无法保留服务器答复中的所有 MX 数据,那么 record_buffer 会保留尽可能多的记录,并返回缓冲区中的记录数。

使用 *record_count 中返回的 MX 记录数,应用程序可分析 MX 参数,包括 record_buffer 中每个记录的邮件主机名。

输入参数

  • dns_ptr:指向 DNS 客户端的指针。
  • host_name:指向主机名以获取其 MX 数据的指针
  • record_buffer:指向相应位置以从中提取 MX 数据的指针
  • buffer_size:保存 MX 数据所用缓冲区的大小
  • record_count:指向所检索 MX 记录数的指针
  • wait_option:用于接收 DNS 服务器响应的等待选项

返回值

  • NX_SUCCESS (0x00):已成功获取 MX 数据
  • NX_DNS_NO_SERVER (0xA1):客户端服务器列表是空的
  • NX_DNS_QUERY_FAILED (0xA3):没有收到有效的 DNS 响应
  • NX_DNS_PARAM_ERROR (0xA8):非指针输入无效
  • NX_PTR_ERROR (0x07):IP 或 DNS 指针无效
  • NX_CALLER_ERROR (0x11):此服务的调用方无效

允许调用自

线程数

示例

#define MAX_RECORD_COUNT 10

ULONG  record_buffer[50];
UINT   record_count;  
NX_DNS_MX_ENTRY  *nx_dns_mx_entry_ptr[MAX_RECORD_COUNT];        

/* Request the mail exchange data for the specified host. */
status =  nx_dns_domain_mail_exchange_get(&client_dns, (UCHAR *)" www.my_example.com ", 
 										  record_buffer, sizeof(record_buffer),   
										  &record_count, 500);

/* Check for DNS query error. */
if (status != NX_SUCCESS)
{
    error_counter++;
}
       
else     
{
/* If status is NX_SUCCESS a DNS query was successfully completed and MX
   data is returned in record_buffer. */

    printf("------------------------------------------------------\n");
    printf("Test MX: ");
    printf("record_count = %d \n", record_count);      


    /* Get the mail exchange. */
    for(i =0; i< record_count; i++)
    {
        nx_dns_mx_entry_ptr[i] = (NX_DNS_MX_ENTRY *)
			   (record_buffer + i * sizeof(NX_DNS_MX_ENTRY));   

        printf("record %d: IP address: %d.%d.%d.%d\n", i, 
        	nx_dns_mx_entry_ptr[i] -> nx_dns_mx_ipv4_address >> 24,
			nx_dns_mx_entry_ptr[i] -> nx_dns_mx_ipv4_address >> 16 & 0xFF,                   
        	nx_dns_mx_entry_ptr[i] -> nx_dns_mx_ipv4_address >> 8 & 0xFF,
			nx_dns_mx_entry_ptr[i] -> nx_dns_mx_ipv4_address & 0xFF);

        printf("preference = %d \n ", 
			nx_dns_mx_entry_ptr[i] -> nx_dns_mx_preference);

		if(nx_dns_mx_entry_ptr[i] -> nx_dns_mx_hostname_ptr)
        	printf("hostname = %s\n", 
					nx_dns_mx_entry_ptr[i] -> nx_dns_mx_hostname_ptr);
		else
        	printf("hostname is not set\n");
}


[Output]

-----------------------------------------------------
Test MX: record_count = 5 
record 0: IP address: 192.2.2.10
preference = 40 
hostname = alt3.aspmx.l.www.my_example.com
record 1: IP address: 192.2.2.11
preference = 50 
hostname = alt4.aspmx.l.www.my_example.com
record 2: IP address: 192.2.2.12
preference = 10 
hostname = aspmx.l.www.my_example.com
record 3: IP address: 192.2.2.13
preference = 20 
hostname = alt1.aspmx.l.www.my_example.com
record 4: IP address: 192.2.2.14
preference = 30 
hostname = alt2.aspmx.l.www.my_example.com

nx_dns_domain_service_get

按输入主机名查找所提供服务

原型

UINT nx_dns_domain_service_get (
    NX_DNS *dns_ptr,
    UCHAR *host_name, 
    VOID *record_buffer,
    UINT buffer_size, 
    UINT *record_count,
    ULONG wait_option);

说明

如果定义了 NX_DNS_ENABLE_EXTENDED_RR_TYPES,则此服务发送带有指定域名的 SRV 类型查询,以查找与指定域关联的服务及其端口号。 DNS 客户端会将 DNS 服务器响应中返回的 SRV 记录复制到 record_buffer 内存位置。

注意

record_buffer 必须是 4 字节对齐的,才能接收数据。

在 NetX Duo DNS 客户端中,服务记录类型 NX_DNS_SRV_ ENTRY 保存为 6 个参数(总共 16 字节)。 这样,可将可变长度 SRV 数据高效存储在内存中:

  • 服务器 IPv4 地址:nx_dns_srv_ipv4_address(4 字节)
  • 服务器优先级:nx_dns_srv_priority(2 字节)
  • 服务器权重:nx_dns_srv_weight(2 字节)
  • 服务端口号:nx_dns_srv_port_number(2 字节)
  • 为实现 4 字节对齐保留:nx_dns_srv_reserved0(2 字节)
  • 指向服务器主机名的指针:*nx_dns_srv_hostname_ptr(4 字节)

所提供缓冲区中已存储四个 SRV 记录。 每个 NX_DNS_SRV_ENTRY 记录都包含指向记录缓冲区末尾相应的主机名字符串的指针 nx_dns_srv_hostname_ptr:

Four SRV records

如果输入 record_buffer 无法保留服务器答复中的所有 SRV 数据,那么 record_buffer 会保留尽可能多的记录,并返回缓冲区中的记录数。

使用 *record_count 中返回的 SRV 记录数,应用程序可分析 SRV 参数,包括 record_buffer 中每个记录的服务器主机名。

输入参数

  • dns_ptr:指向 DNS 客户端的指针。
  • host_name:指向主机名以获取其 SRV 数据的指针
  • record_buffer:指向相应位置以从中提取 SRV 数据的指针
  • buffer_size:保存 SRV 数据所用缓冲区的大小
  • record_count:指向所检索 SRV 记录数的指针
  • wait_option:用于接收 DNS 服务器响应的等待选项

返回值

  • NX_SUCCESS (0x00):已成功获取 SRV 数据
  • NX_DNS_NO_SERVER (0xA1):客户端服务器列表是空的
  • NX_DNS_QUERY_FAILED (0xA3):没有收到有效的 DNS 响应
  • NX_DNS_PARAM_ERROR (0xA8):非指针参数无效。
  • NX_PTR_ERROR (0x07):IP 或 DNS 指针无效
  • NX_CALLER_ERROR (0x11):此服务的调用方无效

允许来自

线程数

示例

#define MAX_RECORD_COUNT  10

UCHAR  record_buffer[50];
UINT   record_count;          
NX_DNS_SRV_ENTRY *nx_dns_srv_entry_ptr[MAX_RECORD_COUNT];

/* Request the service(s) provided by the specified host. */
status =  nx_dns_domain_service_get(&client_dns, (UCHAR *)"www.my_example.com ", 
								    record_buffer, sizeof(record_buffer), 
								    &record_count, 500);

/* Check for DNS query error. */
if (status != NX_SUCCESS)
{
    error_counter++;
}

else     
{
	/* If status is NX_SUCCESS a DNS query was successfully completed and SRV data
	   is returned in record_buffer. */

		printf("------------------------------------------------------\n");
		printf("Test SRV: ");
		printf("record_count = %d \n", record_count);      

		   
		/* Get the location of services. */
		for(i =0; i< record_count; i++)
		{
			nx_dns_srv_entry_ptr[i] = (NX_DNS_SRV_ENTRY *)
									(record_buffer + i * sizeof(NX_DNS_SRV_ENTRY)); 

			printf("record %d: IP address: %d.%d.%d.%d\n", i, 
					nx_dns_srv_entry_ptr[i] -> nx_dns_srv_ipv4_address >> 24,
					nx_dns_srv_entry_ptr[i] -> nx_dns_srv_ipv4_address >> 16 & 0xFF,                   
					nx_dns_srv_entry_ptr[i] -> nx_dns_srv_ipv4_address >> 8 & 0xFF,
					nx_dns_srv_entry_ptr[i] -> nx_dns_srv_ipv4_address & 0xFF);

		   printf("port number = %d\n", 
				   nx_dns_srv_entry_ptr[i] -> nx_dns_srv_port_number );
		   printf("priority = %d\n", nx_dns_srv_entry_ptr[i] -> nx_dns_srv_priority );
		   printf("weight = %d\n", nx_dns_srv_entry_ptr[i] -> nx_dns_srv_weight );

		   if(nx_dns_srv_entry_ptr[i] -> nx_dns_srv_hostname_ptr)
		   {
				printf("hostname = %s\n", 
						nx_dns_srv_entry_ptr[i] -> nx_dns_srv_hostname_ptr);
			}
		   else
				printf("hostname is not set\n");
		}
}

[Output]
----------------------------------------------------
Test SRV: record_count = 3 
record 0: IP address: 192.2.2.10
port number = 5222
priority = 20
weight = 0
hostname = alt4.xmpp.l.www.my_example.com
record 1: IP address: 192.2.2.11
port number = 5222
priority = 5
weight = 0
hostname = xmpp.l.www.my_example.com
record 2: IP address: 192.2.2.12
port number = 5222
priority = 20
weight = 0
hostname = alt1.xmpp.l.www.my_example.com

nx_dns_get_serverlist_size

返回 DNS 客户端服务器列表的大小

原型

UINT nx_dns_get_serverlist_size (
    NX_DNS *dns_ptr,
    UINT *size);

说明

此服务用于返回客户端列表中有效 DNS 服务器(IPv4 和 IPv6)的数量。

输入参数

  • dns_ptr:指向 DNS 控制块的指针
  • size:返回列表中服务器的数量

返回值

  • NX_SUCCESS (0x00):已成功返回 DNS 服务器列表大小
  • NX_PTR_ERROR (0x07):IP 或 DNS 指针无效。
  • NX_CALLER_ERROR (0x11):此服务的调用方无效

允许调用自

线程数

示例

UINT my_listsize;

/* Get the number of non null DNS Servers in the Client list. */
status =  nx_dns_get_serverlist_size (&my_dns, 5, &my_listsize);

/* If status is NX_SUCCESS the size of the DNS Server list was successfully
   returned. */

nx_dns_info_by_name_get

按主机名返回 DNS 服务器的 IP 地址和端口

原型

UINT nx_dns_info_by_name_get(
    NX_DNS *dns_ptr,
    UCHAR *host_name, 
    ULONG *host_address_ptr,  
    USHORT *host_port_ptr,
    ULONG wait_option);

说明

此服务可通过 DNS 查询,按输入主机名返回服务器 IP 和端口(服务记录)。 如果找不到服务记录,此例程会使用输入地址指针返回零 IP 地址,并返回非零错误状态,以指示错误。

输入参数

  • dns_ptr:指向 DNS 控制块的指针
  • host_name:指向主机名缓冲区的指针
  • host_address_ptr:指向要返回地址的指针
  • host_port_ptr:指向要返回的端口的指针
  • wait_option:用于 DNS 响应的等待选项

返回值

  • NX_SUCCESS (0x00):已成功返回 DNS 服务器记录
  • NX_DNS_NO_SERVER (0xA1):没有向客户端注册 DNS 服务器来发送主机名查询
  • NX_DNS_QUERY_FAILED (0xA3):DNS 查询失败;没有来自客户端列表中任何 DNS 服务器的响应,或输入主机名没有可用的服务记录。
  • NX_PTR_ERROR (0x07):IP 或 DNS 指针无效
  • NX_CALLER_ERROR (0x11):调用方无效

允许调用自

线程数

示例

ULONG ip_address
USHORT port;

/* Attempt to resolve the IP address and ports for this host name. */
status =  nx_dns_info_by_name_get(&my_dns, “www.abc1234.com”, &ip_address, &port, 200);

/* If status is NX_SUCCESS the DNS query was successful and the IP address and
   report for the hostname are returned. */

nx_dns_ipv4_address_by_name_get

查找输入主机名的 IPv4 地址

原型

UINT nx_ dns_ipv4_address_by_name_get (
    NX_DNS *dns_ptr, 
    UCHAR *host_name_ptr,
    VOID *buffer, 
    UINT buffer_size, 
    UINT *record_count, 
    ULONG wait_option);

说明

此服务可使用指定主机名发送类型为 A 的查询,以便获取输入主机名的 IP 地址。 DNS 客户端会将 DNS 服务器响应中返回的 A 记录 IPv4 地址复制到 record_buffer 内存位置。

注意

record_buffer 必须是 4 字节对齐的,才能接收数据。

多个 IPv4 地址存储在 4 字节对齐的缓冲区中,如下所示:

multiple address 4-byte aligned buffer

如果所提供的缓冲区无法保留所有 IP 地址数据,那么其余的 A 记录不会存储在 record_buffer 中。 这样,应用程序可检索到服务器回复中的一个、部分或全部可用 IP 地址数据。

使用 *record_count 中返回的 A 记录数,应用程序可分析 record_buffer 中的 IPv4 地址数据。

输入参数

  • dns_ptr:指向 DNS 客户端的指针。
  • host_name_ptr:指向用于获取 IPv4 地址的主机名的指针
  • buffer:指向要将 IPv4 数据提取到的位置的指针
  • buffer_size:保存 IPv4 数据所用缓冲区的大小
  • wait_option:用于接收 DNS 服务器响应的等待选项

返回值

  • NX_SUCCESS (0x00):已成功获取 IPv4 数据
  • NX_DNS_NO_SERVER (0xA1):客户端服务器列表是空的
  • NX_DNS_QUERY_FAILED (0xA3):没有收到有效的 DNS 响应
  • NX_PTR_ERROR (0x07):IP 或 DNS 指针无效
  • NX_CALLER_ERROR (0x11):此服务的调用方无效
  • NX_DNS_PARAM_ERROR (0xA8):非指针参数无效。

允许调用自

线程数

示例

#define MAX_RECORD_COUNT  20

ULONG           record_buffer[50];
UINT            record_count;
ULONG           *ipv4_address_ptr[MAX_RECORD_COUNT];

/* Request the IPv4 address for the specified host. */
status =  nx_dns_ipv4_address_by_name_get(&client_dns, 
                                          (UCHAR *)"www.my_example.com",  
                                           record_buffer,                  
                                           sizeof(record_buffer),&record_count,                
                                           500);

/* Check for DNS query error. */
if (status != NX_SUCCESS)
{
        error_counter++;
}    
        else     
{
	/* If status is NX_SUCCESS a DNS query was successfully completed the IPv4
  	   address(es) is returned in record_buffer. */

		  
			printf("------------------------------------------------------\n");
			printf("Test A: ");
			printf("record_count = %d \n", record_count);      


		   /* Get the IPv4 addresses of host. */
		   for(i =0; i< record_count; i++)
		   {
				ipv4_address_ptr[i] = (ULONG *)(record_buffer + i * sizeof(ULONG)); 
				printf("record %d: IP address: %d.%d.%d.%d\n", i, 
					*ipv4_address_ptr[i] >> 24,
					*ipv4_address_ptr[i] >> 16 & 0xFF,                   
					*ipv4_address_ptr[i] >> 8 & 0xFF,
					*ipv4_address_ptr[i] & 0xFF);
			}

}

[Output]

------------------------------------------------------
Test A: record_count = 5 
record 0: IP address: 192.2.2.10
record 1: IP address: 192.2.2.11
record 2: IP address: 192.2.2.12
record 3: IP address: 192.2.2.13
record 4: IP address: 192.2.2.14

nxd_dns_ipv6_address_by_name_get

查找输入主机名的 IPv6 地址

原型

UINT nxd_ dns_ipv6_address_by_name_get(
    NX_DNS *dns_ptr, 
    UCHAR *host_name_ptr,
     VOID *buffer, 
    UINT buffer_size, 
    UINT *record_count, 
    ULONG wait_option);

说明

此服务用于发送带有指定域名的 AAAA 类型查询,以获取输入域名的 IP 地址。 DNS 客户端会将 DNS 服务器响应中返回的 AAAA 记录中的 IPv6 地址复制到 record_buffer 内存位置。

注意

record_buffer 必须是 4 字节对齐的,才能接收数据。

存储在 4 字节对齐的缓冲区中的 IPv6 地址的格式如下所示:

IPv6 format 4-byte aligned buffer

如果输入 record_buffer 无法保留服务器答复中的所有 AAAA 数据,那么 record_buffer 会保留尽可能多的记录,并返回缓冲区中的记录数。

使用 record_count* 中返回的 AAAA 记录数,应用程序可以分析 record_buffer 中每个记录的 IPv6 地址。

输入参数

  • dns_ptr:指向 DNS 客户端的指针。
  • host_name_ptr:指向用于获取 IPv6 地址的主机名的指针
  • buffer:指向要将 IPv6 数据提取到的位置的指针
  • buffer_size:保留 IPv6 数据的缓冲区的大小
  • wait_option:用于接收 DNS 服务器响应的等待选项

返回值

  • NX_SUCCESS (0x00):已成功获取 IPv6 数据
  • NX_DNS_NO_SERVER (0xA1):客户端服务器列表是空的
  • NX_DNS_QUERY_FAILED (0xA3):没有收到有效的 DNS 响应
  • NX_PTR_ERROR (0x07):IP 或 DNS 指针无效
  • NX_CALLER_ERROR (0x11):此服务的调用方无效
  • NX_DNS_PARAM_ERROR (0xA8):非指针参数无效。

允许调用自

线程数

示例

#define 	 MAX_RECORD_COUNT  20

ULONG           record_buffer[50];
UINT            record_count;
NXD_ADDRESS    *ipv6_address_ptr[MAX_RECORD_COUNT];

/* Request the IPv4 address for the specified host. */
status =  nxd_dns_ipv6_address_by_name_get(&client_dns, 
                                           (UCHAR *)"www.my_example.com", 
                                           record__buffer,                  
                                           sizeof(record_buffer), 
                                           &record_count, 500);

/* Check for DNS query error. */
if (status != NX_SUCCESS)
{
        error_counter++;
}    
        else     
{
/* If status is NX_SUCCESS a DNS query was successfully completed the IPv6 
	address(es) is (are) returned in record_buffer. */
      
    printf("------------------------------------------------------\n");
    printf("Test AAAA: ");
    printf("record_count = %d \n", record_count);      

    /* Get the IPv6 addresses of host. */
    for(i =0; i< record_count; i++)
    {

        ipv6_address_ptr[i] = 
            (NX_DNS_IPV6_ADDRESS *)(record_buffer + i * sizeof(NX_DNS_IPV6_ADDRESS)); 
             
        printf("record %d: IP address: %x:%x:%x:%x:%x:%x:%x:%x\n", i, 
                ipv6_address_ptr[i] -> ipv6_address[0]  >>16 & 0xFFFF,
                ipv6_address_ptr[i] -> ipv6_address[0]  & 0xFFFF,
                ipv6_address_ptr[i] -> ipv6_address[1]  >>16 & 0xFFFF,
                ipv6_address_ptr[i] -> ipv6_address[1]  & 0xFFFF,
                ipv6_address_ptr[i] -> ipv6_address[2]  >>16 & 0xFFFF,
                ipv6_address_ptr[i] -> ipv6_address[2]  & 0xFFFF,
                ipv6_address_ptr[i] -> ipv6_address[3]  >>16 & 0xFFFF,
                ipv6_address_ptr[i] -> ipv6_address[3]  & 0xFFFF);
            }
}


[Output]
------------------------------------------------------
Test AAAA: record_count = 1 
record 0: IP address: 2001:0db8:0000:f101: 0000: 0000: 0000:01003

nx_dns_host_by_address_get

根据 IP 地址查找主机名

原型

UINT nx_dns_host_by_address_get(
    NX_DNS *dns_ptr,
    ULONG ip_address, 
    ULONG *host_name_ptr, 
    ULONG max_host_name_size, 
    ULONG wait_option);

说明

此服务用于请求对应用程序之前指定的一个或多个 DNS 服务器所提供的 IP 地址进行名称解析。 如果成功,以 NULL 结尾的主机名则会在 host_name_ptr 指定的字符串中返回。 这是 nxd_dns_host_by_address_get 服务的包装器函数,不接受 IPv6 地址。

输入参数

  • dns_ptr:指向以前所创建 DNS 实例的指针。

  • ip_address:要解析为名称的 IP 地址

  • host_name_ptr:指向主机名目标区域的指针

  • max_host_name_size:主机名目标区域的大小

  • wait_option:定义服务在每次 DNS 查询和查询重试后等待 DNS 服务器响应的时长(以计时器刻度为单位)。 等待选项的定义如下:

    超时值 (0x00000001-0xFFFFFFFE) TX_WAIT_FOREVER (0xFFFFFFFF)

    选择 TX_WAIT_FOREVER 会导致调用线程无限期暂停,直到 DNS 服务器响应请求。

    选择数值 (1-0xFFFFFFFE) 指定在等待 DNS 解析时调用线程保持暂停状态的最大计时器刻度数。

返回值

  • NX_SUCCESS (0x00):DNS 解析成功
  • NX_DNS_TIMEOUT (0xA2):获取 DNS 互斥时超时
  • NX_DNS_NO_SERVER (0xA1):没有指定 DNS 服务器地址
  • NX_DNS_QUERY_FAILED (0xA3):没有收到查询响应
  • NX_DNS_BAD_ADDRESS_ERROR (0xA4):输入地址为 NULL
  • NX_DNS_INVALID_ADDRESS_TYPE (0xB2):索引指向的地址类型(例如 IPv6)无效
  • NX_DNS_PARAM_ERROR (0xA8):非指针输入无效
  • NX_DNS_IPV6_NOT_SUPPORTED (0xB3):无法处理已禁用 IPv6 的记录
  • NX_PTR_ERROR (0x07):指针输入无效
  • NX_CALLER_ERROR:(0x11) 此服务的调用方无效

允许来自

线程数

示例

#define BUFFER_SIZE   200

UCHAR	resolved_name[200];

/* Get the name associated with IP address 192.2.2.10.  */
status =  nx_dns_host_by_address_get(&my_dns, IP_ADDRESS(192.2.2.10),
									 &resolved_name[0], BUFFER_SIZE, 450);

/* If status is NX_SUCCESS the name associated with the IP address
   can be found in the resolved_name variable.  */

nxd_dns_host_by_address_get

从 IP 地址中查找主机名

原型

UINT nxd_dns_host_by_address_get(
    NX_DNS *dns_ptr, 
    NXD_ADDRESS ip_address, 
    ULONG *host_name_ptr, 
    ULONG max_host_name_size, 
    ULONG wait_option);

说明

此服务用于请求对应用程序之前指定的一个或多个 DNS 服务器所提供的 ip_address 输入参数中的 IPv6 或 IPv4 地址进行名称解析。 如果成功,以 NULL 结尾的主机名则会在 host_name_ptr 指定的字符串中返回。

输入参数

  • dns_ptr:指向以前所创建 DNS 实例的指针。

  • ip_address:要解析为名称的 IP 地址

  • host_name_ptr:指向主机名目标区域的指针

  • max_host_name_size:主机名目标区域的大小

  • wait_option:定义服务在每次 DNS 查询和查询重试后等待 DNS 服务器响应的时长(以计时器刻度为单位)。 等待选项的定义如下:

    超时值 (0x00000001 through 0xFFFFFFFE) TX_WAIT_FOREVER (0xFFFFFFFF)

    选择 TX_WAIT_FOREVER 会导致调用线程无限期暂停,直到 DNS 服务器响应请求。

    选择数值 (1-0xFFFFFFFE) 指定在等待 DNS 解析时调用线程保持暂停状态的最大计时器刻度数。

返回值

  • NX_SUCCESS (0x00):DNS 解析成功
  • NX_DNS_TIMEOUT (0xA2):获取 DNS 互斥时超时
  • NX_DNS_NO_SERVER (0xA1):没有指定 DNS 服务器地址
  • NX_DNS_QUERY_FAILED (0xA3):没有收到查询响应
  • NX_DNS_BAD_ADDRESS_ERROR (0xA4):输入地址为 NULL
  • NX_DNS_IPV6_NOT_SUPPORTED (0xB3):无法处理已禁用 IPv6 的记录
  • NX_PTR_ERROR (0x07):IP 或 DNS 指针无效
  • NX_CALLER_ERROR (0x11):此服务的调用方无效
  • NX_DNS_PARAM_ERROR (0xA8):非指针输入无效

允许调用自

线程数

示例

UCHAR	resolved_name[200];
NXD_ADDRESS host_address;

host_address.nxd_ip_version = NX_IP_VERISON_V6;
host_address.nxd_ip_address.v6[0] = 0x20010db8;
host_address.nxd_ip_address.v6[1] = 0x0;
host_address.nxd_ip_address.v6[2] = 0xf101;
host_address.nxd_ip-address.v6[3] = 0x108;

/* Get the name associated with theinput host_address. */
status =  nxd_dns_host_by_address_get(&my_dns, &host_address,
									  resolved_name, sizeof(resolved_name), 4000);

/* Check for DNS query error. */
if (status != NX_SUCCESS)
{
     error_counter++;
}     
else     
{
     printf("------------------------------------------------------\n");
     printf("Test PTR: %s\n", record_buffer);
}

/* If status is NX_SUCCESS the name associated with the IP address
   can be found in the resolved_name variable. */


[Output]

 ------------------------------------------------------
 Test PTR: my_example.net

nx_dns_host_by_name_get

根据主机名查找 IP 地址

原型

UINT nx_dns_host_by_name_get(
    NX_DNS *dns_ptr,
    UCHAR *host_name, 
    ULONG *host_address_ptr,
    ULONG wait_option);

说明

此服务用于请求对应用程序之前指定的一个或多个 DNS 服务器所提供的名称进行名称解析。 如果成功,关联的 IP 地址则会在 host_address_ptr 指向的目标中返回。 这是 nxd_dns_host_by_name_get 服务的包装器函数,仅限 IPv4 地址输入。

输入参数

  • dns_ptr:指向以前所创建 DNS 实例的指针。

  • host_name:指向主机名的指针

  • host_address_ptr:返回的 DNS 服务器 IP 地址

  • wait_option:定义服务等待 DNS 解析的时长。 等待选项的定义如下:

    超时值 (0x00000001 through 0xFFFFFFFE) TX_WAIT_FOREVER (0xFFFFFFFF)

    选择 TX_WAIT_FOREVER 会导致调用线程无限期暂停,直到 DNS 服务器响应请求。

    选择数值 (1-0xFFFFFFFE) 指定在等待 DNS 解析时调用线程保持暂停状态的最大计时器刻度数。

返回值

  • NX_SUCCESS (0x00):DNS 解析成功。
  • NX_DNS_NO_SERVER (0xA1):没有指定 DNS 服务器地址
  • NX_DNS_QUERY_FAILED (0xA3):没有收到查询响应
  • NX_DNS_PARAM_ERROR (0xA8):非指针输入无效
  • NX_PTR_ERROR (0x07):指针输入无效
  • NX_CALLER_ERROR:(0x11) 此服务的调用方无效

允许来自

线程数

示例

ULONG host_address;

/* Get the IP address for the name “www.my_example.com”. */
   status =  nx_dns_host_by_name_get(&my_dns, “www.my_example.com”, &host_address, 4000);

/* Check for DNS query error. */
if (status != NX_SUCCESS)
{
    error_counter++;
}

else     
{

	/* If status is NX_SUCCESS the IP address for “www.my_example.com” can be found 
		in the “ip_address” variable. */
        
    printf("------------------------------------------------------\n");
    printf("Test A: \n");
    printf("IP address: %d.%d.%d.%d\n",
    host_address >> 24,
    host_address >> 16 & 0xFF,                   
    host_address >> 8 & 0xFF,
    host_address & 0xFF);
}

[Output]
 ------------------------------------------------------
Test A: 
IP address: 192.2.2.10

nxd_dns_host_by_name_get

从主机名中查找 IP 地址

原型

UINT nxd_dns_host_by_name_get(
    NX_DNS *dns_ptr, ULONG *host_name, 
    NXD_ADDRESS *host_address_ptr, 
    ULONG wait_option,
    UINT lookup_type);

说明

此服务用于请求对应用程序之前指定的一个或多个 DNS 服务器所提供的 IP 地址进行名称解析。 如果成功,关联的 IP 地址则会在 host_address_ptr 指向的 NXD_ADDRESS 中返回。 如果调用方专门将 lookup_type 输入设置为 NX_IP_VERSION_V6,则此服务会发送主机 IPv6 地址(AAAA 记录)查询。 如果调用方专门将 lookup_type 输入设置为 NX_IP_VERSION_V4,则此服务会发送主机 IPv4 地址(A 记录)查询。

输入参数

  • dns_ptr:指向之前创建的 DNS 客户端实例的指针。
  • host_name:指向要查找其 IP 地址的主机名的指针
  • host_address_ptr:指向包含 IP 地址的 NXD_ADDRESS 的目标的指针
  • wait_option:定义服务等待每次查询传输和重新传输的 DNS 服务器响应的时长(以计时器刻度为单位)。 等待选项的定义如下:
    • 超时值 (0x00000001 through 0xFFFFFFFE) TX_WAIT_FOREVER (0xFFFFFFFF)
    • 选择 TX_WAIT_FOREVER 会导致调用线程无限期暂停,直到 DNS 服务器响应请求。
    • 选择数值 (1-0xFFFFFFFE) 指定在等待 DNS 解析时调用线程保持暂停状态的最大计时器刻度数。
  • lookup_type:指明查找类型(A 与 AAAA)。

返回值

  • NX_SUCCESS (0x00):DNS 解析成功。
  • NX_DNS_NO_SERVER (0xA1):没有指定 DNS 服务器地址
  • NX_DNS_QUERY_FAILED (0xA3):没有收到查询响应
  • NX_DNS_BAD_ADDRESS_ERROR (0xA4):输入地址为 NULL
  • NX_DNS_IPV6_NOT_SUPPORTED (0xB3):无法处理已禁用 IPv6 的记录
  • NX_PTR_ERROR (0x07):指针输入无效
  • NX_CALLER_ERROR (0x11):此服务的调用方无效
  • NX_DNS_PARAM_ERROR (0xA8):非指针输入无效

允许调用自

线程数

示例

NXD_ADDRESS host_ipduo_address;

/* Create an AAAA query to obtain the IPv6 address for the host “www.my_example.com”. */
status =  nxd_dns_host_by_name_get(&my_dns, “www.my_example.com”, 
                                   &host_ipduo_address, 4000, 
                                   NX_IP_VERSION_V6);

if (status != NX_SUCCESS)
{
        error_counter++;
}
else
{
/* If status is NX_SUCCESS the IP address for “www.my_example.com” can be 
   found in the “ip_address” variable. */

    printf("------------------------------------------------------\n");
    printf("Test AAAA: \n");

    printf("IP address: %x:%x:%x:%x:%x:%x:%x:%x\n", 
           host_ipduo_address.nxd_ip_address.v6[0]  >>16 & 0xFFFF,
           host_ipduo_address.nxd_ip_address.v6[0]  & 0xFFFF,
           host_ipduo_address.nxd_ip_address.v6[1]  >>16 & 0xFFFF,
           host_ipduo_address.nxd_ip_address.v6[1]  & 0xFFFF,
           host_ipduo_address.nxd_ip_address.v6[2]  >>16 & 0xFFFF,
           host_ipduo_address.nxd_ip_address.v6[2]  & 0xFFFF,
           host_ipduo_address.nxd_ip_address.v6[3]  >>16 & 0xFFFF,
           host_ipduo_address.nxd_ip_address.v6[3]  & 0xFFFF);
}

[Output]

------------------------------------------------------
Test AAAA: 
IP address: 2607:f8b0:4007:800:0:0:0:1008

下面展示了使用此时间服务的另一个示例,这次使用的是 IPv4 地址和 A 记录类型:

/* Create a query to obtain the IPv4 address for the host “www.my_example.com”. */
status =  nxd_dns_host_by_name_get(&my_dns, “www.my_example.com”, &ip_address, 4000, 
								   NX_IP_VERSION_V4);

/* Check for DNS query error. */
if (status != NX_SUCCESS)
{
    error_counter++;
}
else     
{   
/* If status is NX_SUCCESS the IP address for “www.my_example.com” can be 
   found in the “ip_address” variable. */
  
     printf("------------------------------------------------------\n");
     printf("Test A: \n");
     printf("IP address: %d.%d.%d.%d\n",
			host_ipduo_address.nxd_ip_address.v4 >> 24,
            host_ipduo_address.nxd_ip_address.v4 >> 16 & 0xFF,                   
            host_ipduo_address.nxd_ip_address.v4 >> 8 & 0xFF,
            host_ipduo_address.nxd_ip_address.v4 & 0xFF);
 }

[Output]

------------------------------------------------------
Test A: 
IP address: 192.2.2.10

nx_dns_host_text_get

查找输入域名的文本字符串

原型

UINT nx_dns_host_text_get(
    NX_DNS *dns_ptr,
    UCHAR *host_name, 
    UCHAR *record_buffer, 
    UINT buffer_size,
    ULONG wait_option);

说明

此服务可使用指定域名和缓冲区发送类型为 TXT 的查询,以便获取任意字符串数据。

DNS 客户端会将 DNS 服务器响应中返回的 TXT 记录中的文本字符串复制到 record_buffer 内存位置。

注意

record_buffer 不必是 4 字节对齐的,也可以接收数据。

输入参数

  • dns_ptr:指向 DNS 客户端的指针。
  • host_name:指向要搜索主机所用名称的指针
  • record_buffer:指向相应位置以从中提取 TXT 数据的指针
  • buffer_size:保存 TXT 数据所用缓冲区的大小
  • wait_option:用于接收 DNS 服务器响应的等待选项

返回值

  • NX_SUCCESS (0x00):已成功获取 TXT 字符串
  • NX_DNS_NO_SERVER (0xA1):客户端服务器列表是空的
  • NX_DNS_QUERY_FAILED (0xA3):没有收到有效的 DNS 响应
  • NX_PTR_ERROR (0x07):指针输入无效
  • NX_CALLER_ERROR (0x11):此服务的调用方无效
  • NX_DNS_PARAM_ERROR (0xA8):非指针输入无效

允许调用自

线程数

示例

CHAR            record_buffer[50];

/* Request the text string for the specified host. */
status =  nx_dns_host_text_get(&client_dns, (UCHAR *)"www.my_example.com", 
							   record_buffer, 
							   sizeof(record_buffer), 500);


/* Check for DNS query error. */
if (status != NX_SUCCESS)
{
     error_counter++;
}
else     
{
	/* If status is NX_SUCCESS a DNS query was successfully completed and the
   	   text string is returned in record_buffer. */
 
     printf("------------------------------------------------------\n");
     printf("Test TXT:\n %s\n", record_buffer);
} 


[Output]

------------------------------------------------------
Test TXT: 
v=spf1 include:_www.my_example.com ip4:192.2.2.10/31 ip4:192.2.2.11/31 ~all

nx_dns_packet_pool_set

设置 DNS 客户端数据包池

原型

UINT nx_dns_packet_pool_set(
    NX_DNS *dns_ptr,
    NX_PACKET_POOL *pool_ptr);

说明

此服务用于将之前创建的数据包池设置为 DNS 客户端数据包池。 DNS 客户端将使用此数据包池来发送 DNS 查询,因此数据包有效负载不得小于 NX_DNS_PACKET_PAYLOAD(包含以太网头、IP 头和 UDP 头),并在 nxd_dns.h 中定义。

注意

在删除 DNS 客户端后,数据包池不会随之删除,由应用程序负责删除不再需要的数据包池。

只有在 nxd_dns.h 中定义了配置选项 NX_DNS_CLIENT_USER_CREATE_PACKET_POOL 时,此服务才可用

输入参数

  • dns_ptr:指向之前创建的 DNS 客户端实例的指针。
  • pool_ptr:指向以前所创建数据包池的指针

返回值

  • NX_SUCCESS (0x00):已成功完成。
  • NX_NOT_ENABLED (0x14):没有为客户端配置此选项
  • NX_PTR_ERROR (0x07):IP 或 DNS 客户端指针无效。
  • NX_CALLER_ERROR (0x11):此服务的调用方无效。

允许调用自

线程数

示例

NXD_DNS my_dns;
NX_PACKET_POOL client_pool;
NX_IP *ip_ptr;


/* Create the DNS Client. */
status =  nx_dns_create(&my_dns, ip_ptr, “My DNS Client”);

/* Create a packet pool for the DNS Client. */
status =  nx_packet_pool_create(&client_pool, "DNS Client Packet Pool", 
								NX_DNS_PACKET_PAYLOAD, free_mem_pointer, 
								NX_DNS_PACKET_POOL_SIZE);

/* Set the DNS Client packet pool. */
status =  nx_dns_packet_pool_set(&my_dns, &client_pool);

/* If status is NX_SUCCESS the DNS Client packet pool was successfully set. */

nx_dns_server_add

添加 DNS 服务器 IP 地址

原型

UINT nx_dns_server_add(
    NX_DNS *dns_ptr,
    ULONG server_address);

说明

此服务可向服务器列表添加 IPv4 DNS 服务器。

输入参数

  • dns_ptr:指向 DNS 控制块的指针。
  • server_address:DNS 服务器的 IP 地址

返回值

  • NX_SUCCESS (0x00):已成功添加服务器
  • NX_DNS_DUPLICATE_ENTRY
    NX_NO_MORE_ENTRIES (0x17):不允许再添加 DNS 服务器(列表已满)
  • NX_DNS_PARAM_ERROR (0xA8):非指针输入无效
  • NX_DNS_IPV6_NOT_SUPPORTED (0xB3):无法处理已禁用 IPv6 的记录
  • NX_PTR_ERROR (0x07):指针输入无效
  • NX_CALLER_ERROR (0x11):此服务的调用方无效
  • NX_DNS_BAD_ADDRESS_ERROR (0xA4):服务器地址输入为 NULL

允许调用自

线程数

示例

/* Add a DNS Server at IP address 202.2.2.13. */
status =  nx_dns_server_add(&my_dns, IP_ADDRESS(202,2,2,13));

/* If status is NX_SUCCESS a DNS Server was successfully added. */

nxd_dns_server_add

向客户端列表添加 DNS 服务器

原型

UINT nxd_dns_server_add(
    NX_DNS *dns_ptr,
    NXD_ADDRESS *server_address);

说明

此服务用于向 DNS 客户端服务器列表添加 DNS 服务器的 IP 地址。 server_address 可以是 IPv4 地址,也可以是 IPv6 地址。 如果客户端希望能够通过 IPv4 地址或 IPv6 地址访问同一台服务器,则应将这两个 IP 地址都作为条目添加到服务器列表中。

输入参数

  • dns_ptr:指向 DNS 控制块的指针。
  • server_address:指向包含 DNS 服务器的服务器 IP 地址的 NXD_ADDRESS 的指针。

返回值

  • NX_SUCCESS (0x00):已成功添加服务器
  • NX_DNS_DUPLICATE_ENTRY
    NX_NO_MORE_ENTRIES (0x17):不允许再添加 DNS 服务器(列表已满)
  • NX_DNS_IPV6_NOT_SUPPORTED (0xB3):无法处理已禁用 IPv6 的记录
  • NX_DNS_PARAM_ERROR (0xA8):非指针输入无效
  • NX_PTR_ERROR (0x07):指针输入无效
  • NX_CALLER_ERROR (0x11):此服务的调用方无效
  • NX_DNS_BAD_ADDRESS_ERROR (0xA4):服务器地址输入为 NULL
  • NX_DNS_INVALID_ADDRESS_TYPE (0xB2):索引指向的地址类型(例如 IPv6)无效

允许调用自

线程数

示例

NXD_ADDRESS server_address;

server_address.nxd_ip_version = NX_IP_VERISON_V6;
server_address.nxd_ip_address.v6[0] = 0x20010db8;
server_address.nxd_ip_address.v6[1] = 0x0;
server_address.nxd_ip_address.v6[2] = 0xf101;
server_address.nxd_ip-address.v6[3] = 0x108;


/* Add a DNS Server with the IP address pointed to by the server_address input. */
status =  nxd_dns_server_add(&my_dns, &server_address);

/* If status is NX_SUCCESS a DNS Server was successfully added. */

nx_dns_server_get

返回客户端列表中的 IPv4 DNS 服务器

原型

UINT nx_dns_server_get(
    NX_DNS *dns_ptr,
    UINT index, 
    ULONG *dns_server_address);

说明

此服务用于返回服务器列表中指定索引处的 IPv4 DNS 服务器地址。

注意

索引是从零开始的。 如果输入索引超过了 DNS 客户端列表的大小、在相应索引处找到了 IPv6 地址,或在指定的索引处找到了 NULL 地址,则会返回错误。 可以先调用 nx_dns_get_serverlist_size 服务来获取客户端列表中的 DNS 服务器数量。

此服务仅支持 IPv4 地址。 它调用支持 IPv4 和 IPv6 地址的 nxd_dns_server_get 服务。

输入参数

  • dns_ptr:指向 DNS 控制块的指针
  • index:DNS 客户端服务器列表索引
  • dns_server_address:指向 DNS 服务器 IP 地址的指针

返回值

  • NX_SUCCESS (0x00):已成功返回服务器
  • NX_DNS_SERVER_NOT_FOUND (0xA9):索引指向的槽是空的
  • NX_DNS_BAD_ADDRESS_ERROR (0xA4):索引指向的地址为 NULL
  • NX_DNS_INVALID_ADDRESS_TYPE (0xB2):索引指向的地址类型(例如 IPv6)无效
  • NX_DNS_PARAM_ERROR (0xA8):非指针输入无效
  • NX_PTR_ERROR (0x07):IP 或 DNS 指针无效。
  • NX_CALLER_ERROR (0x11):此服务的调用方无效

允许调用自

线程数

示例

ULONG my_server_address;

/* Get the DNS Server at index 5 (zero based) into the Client list. */
status =  nx_dns_server_get(&my_dns, 5, &my_server_addres);

/* If status is NX_SUCCESS a DNS Server was successfully
   returned. */

nxd_dns_server_get

返回客户端列表中的 DNS 服务器

原型

UINT nxd_dns_server_get(
    NX_DNS *dns_ptr,
    UINT index, 
    NXD_ADDRESS *dns_server_address);

说明

此服务用于返回服务器列表中指定索引处的 DNS 服务器 IP 地址。

注意

索引是从零开始的。 如果输入索引超过了 DNS 客户端列表的大小,或在指定的索引处找到了 NULL 地址,则会返回错误。 可以先调用 nx_dns_get_serverlist_size 服务来获取服务器列表中的 DNS 服务器数量。

此服务支持 IPv4 和 IPv6 地址。

输入参数

  • dns_ptr:指向 DNS 控制块的指针
  • index:DNS 客户端服务器列表索引
  • dns_server_address:指向 DNS 服务器 IP 地址的指针

返回值

  • NX_SUCCESS (0x00):已成功返回服务器 IP 地址
  • NX_DNS_SERVER_NOT_FOUND (0xA9):索引指向的槽是空的
  • NX_DNS_BAD_ADDRESS_ERROR (0xA4):索引指向的服务器地址为 NULL
  • NX_DNS_INVALID_ADDRESS_TYPE (0xB2):索引指向的地址类型(例如 IPv6)无效
  • NX_DNS_PARAM_ERROR (0xA8):非指针输入无效
  • NX_PTR_ERROR (0x07):IP 或 DNS 指针无效。
  • NX_CALLER_ERROR (0x11):此服务的调用方无效

允许调用自

线程数

示例

NXD_ADDRESS my_server_address;

/* Get the DNS Server at index 5 (zero based) into the Client list. */
status =  nxd_dns_server_get(&my_dns, 5, &my_server_addres);

/* If status is NX_SUCCESS a DNS Server was successfully
   returned. */

nx_dns_server_remove

从客户端列表中删除 IPv4 DNS 服务器

原型

UINT nx_dns_server_remove(
    NX_DNS *dns_ptr,
    ULONG server_address);

说明

此服务用于从客户端列表中删除 IPv4 DNS 服务器。 它是 nxd_dns_server_remove 的包装器函数。

输入参数

  • dns_ptr:指向 DNS 控制块的指针。
  • server_address:DNS 服务器的 IP 地址。

返回值

  • NX_SUCCESS (0x00):已成功删除 DNS 服务器
  • NX_DNS_SERVER_NOT_FOUND (0xA9):客户端列表中没有服务器
  • NX_DNS_BAD_ADDRESS_ERROR (0xA4):服务器地址输入为 NULL
  • NX_DNS_IPV6_NOT_SUPPORTED (0xB3):无法处理已禁用 IPv6 的记录
  • NX_PTR_ERROR (0x07):IP 或 DNS 指针无效。
  • NX_CALLER_ERROR (0x11):此服务的调用方无效

允许来自

线程数

示例

/* Remove the DNS Server at IP address is 202.2.2.13.  */
status =  nx_dns_server_remove(&my_dns, IP_ADDRESS(202,2,2,13));

/* If status is NX_SUCCESS a DNS Server was successfully
   removed.  */

nxd_dns_server_remove

从客户端列表中删除 DNS 服务器

原型

UINT nxd_dns_server_remove(
    NX_DNS *dns_ptr,
    NXD_ADDRESS *server_address);

说明

此服务用于从客户端列表中删除指定 IP 地址的 DNS 服务器。 输入 IP 地址接受 IPv4 和 IPv6 地址。 在删除服务器后,其余的服务器在列表中向下移动一个索引,以填补空槽。

输入参数

  • dns_ptr:指向 DNS 控制块的指针。
  • server_address:指向包含服务器 IP 地址的 DNS 服务器 NXD_ADDRESS 数据的指针。

返回值

  • NX_SUCCESS (0x00):已成功删除 DNS 服务器
  • NX_DNS_SERVER_NOT_FOUND (0xA9):客户端列表中没有服务器
  • NX_DNS_BAD_ADDRESS_ERROR (0xA4):服务器地址输入为 NULL
  • NX_DNS_IPV6_NOT_SUPPORTED (0xB3):无法处理已禁用 IPv6 的记录
  • NX_PTR_ERROR (0x07):IP 或 DNS 指针无效。
  • NX_CALLER_ERROR (0x11):此服务的调用方无效
  • NX_DNS_INVALID_ADDRESS_TYPE (0xB2):索引指向的地址类型(例如 IPv6)无效

允许调用自

线程数

示例

NXD_ADDRESS server_address;

server_address.nxd_ip_version = NX_IP_VERISON_V6;
server_address.nxd_ip_address.v6[0] = 0x20010db8;
server_address.nxd_ip_address.v6[1] = 0x0;
server_address.nxd_ip_address.v6[2] = 0xf101;
server_address.nxd_ip-address.v6[3] = 0x108;


/* Remove the DNS Server at the specified IP address from the Client list. */
status =  nxd_dns_server_remove(&my_dns,&server_ADDRESS);

/* If status is NX_SUCCESS a DNS Server was successfully removed. */

nx_dns_server_remove_all

从客户端列表中删除所有 DNS 服务器

原型

UINT nx_dns_server_remove_all(NX_DNS *dns_ptr);

说明

此服务可从客户端列表中删除所有 DNS 服务器。

输入参数

  • dns_ptr:指向 DNS 控制块的指针。

返回值

  • NX_SUCCESS (0x00):已成功删除 DNS 服务器
  • NX_DNS_ERROR (0xA0):无法获取保护互斥
  • NX_PTR_ERROR (0x07):IP 或 DNS 指针无效。
  • NX_CALLER_ERROR (0x11):此服务的调用方无效

允许来自

线程数

示例

/* Remove all DNS Servers from the Client list. */
status =  nx_dns_server_remove_all(&my_dns);

/* If status is NX_SUCCESS all DNS Servers were successfully removed. */