第 3 章 - Azure RTOS NetX 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 DNS 客户端中,SOA 记录类型 NX_DNS_SOA_ENTRY 保存为七个 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 可变长度数据”)存储在最后一条记录的可变长度数据之上:

Diagram representing the storage of a two S O A 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");
    }
}

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_ERROR:(0xA0) 缓存不是 4 字节对齐。
  • NX_DNS_PARAM_ERROR:(0xA8) DNS ID 无效。
  • NX_PTR_ERROR:(0x07) DNS 指针无效。
  • NX_CALLER_ERROR:(0x11) 此服务的调用方无效

获准方式

线程数

示例

UCHAR          dns_cache [2048]; 

/* 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) DNS ID 无效。
  • 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) DNS ID 无效。
  • 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);

说明

如果已在 nx_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);
} 
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_POOL_SIZE 和 NX_DNS_PACKET_PAYLOAD 进行定义。 如果 DNS 客户端应用程序喜欢提供以前创建的数据包池,则 IPv4 DNS 客户端的有效负载应为 512 字节的最大 DNS,以及 20 字节的 IP 标头、8 字节的 UDP 标头和 14 字节的以太网标头。

输入参数

  • 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 DNS 客户端中,NS 数据类型 NX_DNS_NS_ENTRY 保存为两个 4 字节参数:

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

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

Diagram of the buffer that contains four N X D N S N S 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) DNS ID 无效。
  • 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");
    }
}
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 DNS 客户端中,邮件交换记录类型 NX_DNS_MAIL_EXCHANGE_ENTRY 保存为四个参数,总计 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 记录。 每个记录的固定长度数据都显示在列表上方。 指向邮件交换服务器主机名的指针指向缓冲区末尾相应的主机名。

Diagram that shows the buffer containing four M X 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) DNS ID 无效。
  • 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");
    }
}
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 DNS 客户端中,服务记录类型 NX_DNS_SRV_ ENTRY 保存为六个参数,总计 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

Diagram of four S R V records stored in the supplied buffer.

如果输入 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) DNS ID 无效。
  • 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");
    }
}
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 服务器的数量。

输入参数

  • 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:指向端口以返回 DNS 响应 wait_option 等待选项的指针

返回值

  • 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 字节对齐的缓冲区中,如下所示:

Diagram of multiple I P v 4 addresses that are stored in the 4 byte aligned buffer.

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

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

输入参数

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

返回值

  • NX_SUCCESS:(0x00) 成功获取 IPv4 数据
  • 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  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);
    }
}
------------------------------------------------------
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

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 指定的字符串中返回。

输入参数

  • dns_ptr:指向以前所创建 DNS 实例的指针。
  • ip_address:要解析为名称的 IP 地址
  • host_name_ptr:指向主机名目标区域的指针
  • max_host_name_size:主机名目标区域的大小
  • wait_option:定义服务在每次 DNS 查询和查询重试后要等待 DNS 服务器响应的时长(以计时器刻度为单位)。等待选项定义如下:
    • timeout value:(0x00000001-0xFFFFFFFE) 选择数值 (1-0xFFFFFFFE) 可指定等待 DNS 解析时服务保持挂起状态的最大计时器刻度数。
    • TX_WAIT_FOREVER:(0xFFFFFFFF) 选择 TX_WAIT_FOREVER 会导致调用线程无限期挂起,直到 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) 空输入地址
  • NX_DNS_INVALID_ADDRESS_TYPE:(0xB2) 索引指向无效地址类型(例如 IPv6)
  • NX_DNS_PARAM_ERROR:(0xA8) 非指针输入无效
  • 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.  */

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 服务器所提供且 host_name 所指向的名称来解析名称。 如果成功,则 host_address_ptr 所指向的目标中会返回关联的 IP 地址。

输入参数

  • dns_ptr:指向以前所创建 DNS 实例的指针。
  • host_name:指向主机名的指针
  • host_address_ptr:指向 DNS 主机 IP 地址的指针
  • wait_option:定义服务等待 DNS 解析的时长。 等待选项定义如下:
    • timeout value:(0x00000001 - 0xFFFFFFFE) 选择数值 (1-0xFFFFFFFE) 可指定等待 DNS 解析时服务保持挂起状态的最大计时器刻度数。
    • TX_WAIT_FOREVER:(0xFFFFFFFF) 选择 TX_WAIT_FOREVER 会导致调用线程无限期挂起,直到 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 ip_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”, &ip_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_ip_address >> 24,
                host_ip_address >> 16 & 0xFF,                   
                host_ip_address >> 8 & 0xFF,
                host_ip_address & 0xFF);
    }
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);
} 
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 查询,因此数据包有效负载不能小于包括以太网帧、IP 和 UDP 标头的 NX_DNS_PACKET_PAYLOAD_UNALIGNED,并且需在 nx_dns.h 中进行定义。

注意

删除 DNS 客户端时,不会删除其数据包池,应用程序可在不再需要数据包池时将其删除。

注意

此服务仅在 nx_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) 此服务的调用方无效。

允许来自

线程数

示例

NX_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_ENTRYNX_NO_MORE_ENTRIES:(0x17) 不允许添加更多 DNS 服务器(列表已满)
  • NX_DNS_PARAM_ERROR:(0xA8) 非指针输入无效
  • NX_PTR_ERROR:(0x07) 指针输入无效
  • NX_CALLER_ERROR:(0x11) 此服务的调用方无效
  • NX_DNS_BAD_ADDRESS_ERROR:(0xA4) 空服务器地址输入

获准方式

线程数

示例

/* 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.  */

nx_dns_server_get

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

原型

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

说明

此服务可返回服务器列表中指定索引处的 IPv4 DNS 服务器地址。 请注意,该索引从零开始。 如果输入索引超出 DNS 客户端列表大小,则会返回错误。 可以先调用 nx_dns_get_serverlist_size 服务,以获取客户端列表中的 DNS 服务器数量。

输入参数

  • 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) 索引指向空地址
  • 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.  */

nx_dns_server_remove

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

原型

UINT nx_dns_server_remove(
    NX_DNS *dns_ptr,
    ULONG server_address);

说明

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

输入参数

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

返回值

  • NX_SUCCESS:(0x00) 成功删除 DNS 服务器
  • NX_DNS_SERVER_NOT_FOUND:(0xA9) 客户端列表中无服务器
  • NX_DNS_BAD_ADDRESS_ERROR:(0xA4) 空服务器地址输入
  • 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.  */

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.  */