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

本章按字母顺序提供所有 Azure RTOS NetX Duo DHCP 客户端服务说明(下面列出的)。

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

nx_dhcp_create

创建 DHCP 实例

原型

UINT nx_dhcp_create(
    NX_DHCP *dhcp_ptr, 
    NX_IP *ip_ptr,
    CHAR *name_ptr);

说明

此服务可为以前创建的 IP 实例创建 DHCP 实例。 默认情况下,已启用主接口来运行 DHCP。 DHCP 客户端的 NetX Duo 实现中虽不使用名称输入,但名称输入必须遵循主机名 RFC 1035 标准。 总长度不能超过 255 个字符,以点分隔的标签必须以字母开头,以字母或数字结尾,并且可以包含连字符,但不能包含其他非字母数字字符。

如果应用程序想要在(使用 nx_ip_interface_attach)注册到 IP 实例的另一个接口上运行 DHCP,则应用程序可以调用 nx_dhcp_set_interface_index,以便只在该接口上运行 DHCP,也可以调用 nx_dhcp_interface_enable,以便也在该接口上运行 DHCP。 有关更多详细信息,请参阅这些服务的说明。

注意

应用程序必须确保 DHCP 客户端数据包池的有效负载支持 RFC 2131 第 2 节所指定的最小 DHCP 消息大小(DHCP 消息数据以及 UDP、IP 和物理网络框架标头的大小为 548 字节)。

输入参数

  • dhcp_ptr:指向 DHCP 控制块的指针。
  • ip_ptr:指向以前所创建 IP 实例的指针。
  • name_ptr:指向 DHCP 实例主机名的指针。

返回值

  • NX_SUCCESS:(0x00) 成功创建 DHCP
  • NX_DHCP_INVALID_NAME:(0xA8) 主机名无效
  • NX_DHCP_INVALID_PAYLOAD:(0x9C) 有效负载太小,不适用于 DHCP 消息
  • NX_PTR_ERROR:(0x16) IP 或 DHCP 指针无效

获准方式

线程、初始化

示例

/* Create a DHCP instance.  */
status =  nx_dhcp_create(&my_dhcp, &my_ip, "My-DHCP");

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

nx_dhcp_interface_enable

启用指定接口运行 DHCP

原型

UINT nx_dhcp_interface_enable(
    NX_DHCP *dhcp_ptr,
    UINT interface_index);

说明

此服务可启用指定接口来运行 DHCP。 默认情况下,已启用主接口来运行 DHCP 客户端。 此时,可以通过调用 nx_dhcp_interface_start,在此接口上启动 DHCP,也可以通过调用 nx_dhcp_start 在所有已启用的接口上启动 DHCP。

注意

应用程序必须先使用 nx_ip_interface_attach 在 IP 实例中注册此接口。

此外,还必须有可用 DHCP 客户端接口“记录”,才能将此接口添加到已启用接口列表中。 默认情况下,NX_DHCP_CLIENT_MAX_RECORDS 定义为 1。 可将此选项设置为预计同时运行 DHCP 客户端所使用接口的最大数量。 通常 NX_DHCP_CLIENT_MAX_RECORDS 数量等于 NX_MAX_PHYSICAL_INTERFACES;但如果设备的物理接口比预计运行 DHCP 客户端的接口多,则可通过将 NX_DHCP_CLIENT_MAX_RECORDS 设置为比物理接口数小的数来节省内存。 物理接口与 DHCP 客户端接口记录之间不存在一对一映射。

此服务与 nx_dhcp_set_interface_index 不同,后者仅设置单个接口来运行 DHCP,而此服务只将指定接口添加到为 DHCP 所启用客户端接口的列表中。

要禁用 DHCP 的接口,应用程序可以调用 nx_dhcp_interface_disable 服务。

输入参数

  • dhcp_ptr:指向 DHCP 控制块的指针。
  • interface_index:启用 DHCP 所使用接口的索引

返回值

  • NX_SUCCESS:(0x00) 成功启用 DHCP
  • NX_DHCP_NO_RECORDS_AVAILABLE:(0xA7) 无可用记录,无法再为 DHCP 启用接口
  • NX_DHCP_INTERFACE_ALREADY_ENABLED:(0xA3) 已为 DHCP 启用接口
  • NX_PTR_ERROR:(0x16) IP 或 DHCP 指针无效
  • NX_INVALID_INTERFACE:(0x4C) 网络接口无效

获准方式

线程、初始化

示例

/* Enable DHCP on a secondary interface. It is already enabled on the primary 
   interface.  NX_DHCP_CLIENT_MAX_RECORDS is set to 2. */

status =  nx_dhcp_interface_enable(&my_dhcp, 1);
/* If status is NX_SUCCESS the interface was successfully enabled.  */


status = nx_dhcp_start(&my_dhcp);
/* If status is NX_SUCCESS DHCP is running on interface 0 and 1.  */

nx_dhcp_interface_disable

禁用指定接口运行 DHCP

原型


UINT nx_dhcp_interface_disable(
    NX_DHCP *dhcp_ptr, 
    UINT interface_index);

说明

此服务可禁用指定接口运行 DHCP。 此服务可在此接口上重新初始化 DHCP 客户端。

若要重新启动 DHCP 客户端,应用程序必须使用 nx_dhcp_interface_enable 重新启用接口,并通过调用 nx_dhcp_interface_start 重新启动 DHCP。

输入参数

  • dhcp_ptr:指向 DHCP 控制块的指针。
  • interface_index:禁用 DHCP 所使用接口的索引

返回值

  • NX_SUCCESS:(0x00) 成功创建 DHCP
  • NX_DHCP_INTERFACE_NOT_ENABLED:(0xA4) 没有为 DHCP 启用接口
  • NX_PTR_ERROR:(0x16) IP 或 DHCP 指针无效
  • NX_CALLER_ERROR:(0x11) 此服务的调用方无效
  • NX_INVALID_INTERFACE:(0x4C) 网络接口无效

允许来自

线程数

示例

/* Disable DHCP on a secondary interface. */

status =  nx_dhcp_interface_disable(&my_dhcp, 1);
/* If status is NX_SUCCESS the interface is successfully disabled.  */

nx_dhcp_clear_broadcast_flag

设置 DHCP 广播标记

原型

UINT nx_dhcp_clear_broadcast_flag(NX_DHCP *dhcp_ptr, UINT clear_flag);

说明

对于为 DHCP 启用的所有接口,此服务可设置或清除 DHCP 消息标头的广播标记。 对于某些 DHCP 消息(例如发现),设置广播标记进行广播是因为客户端没有 IP 地址。

clear_flag 值:

  • NX_TRUE:清除广播标记(请求单播响应)
  • NX_FALSE:设置广播标记(请求广播响应)

此服务适用于必须通过路由器访问 DHCP 服务器,而路由器拒绝转发广播消息的 DHCP 客户端。

输入参数

  • dhcp_ptr:指向 DHCP 控制块的指针
  • clear_flag:广播标记的设置值

返回值

  • NX_SUCCESS:(0x00) 成功设置标记
  • NX_PTR_ERROR:(0x16) IP 或 DHCP 指针无效

获准方式

线程、初始化

示例

/* Send DHCP Client messages with the broadcast flag cleared (e.g. request a  
    unicast response).  */
status =  nx_dhcp_clear_broadcast_flag(&my_dhcp, NX_TRUE);

/* If status is NX_SUCCESS the DHCP Client broadcast flag is updated.  */

nx_dhcp_interface_clear_broadcast_flag

设置或清除指定接口的广播标记

原型

UINT nx_dhcp_interface_clear_broadcast_flag(
    NX_DHCP *dhcp_ptr, 
    UINT interface_index, 
    UINT clear_flag);

说明

使用此服务,DHCP 客户端主机应用程序可设置或清除通过指定接口发送给 DHCP 服务器的 DHCP 客户端消息中的广播标记。 有关更多详细信息,请参阅 nx_dhcp_clear_broadcast_flag。

输入参数

  • dhcp_ptr:指向 DHCP 控制块的指针
  • interface_index:设置广播标记所使用接口的索引
  • clear_flag:广播标记的设置值

返回值

  • NX_SUCCESS:(0x00) 成功设置标记
  • NX_DHCP_INTERFACE_NOT_ENABLED:(0xA4) 没有为 DHCP 启用接口
  • NX_PTR_ERROR:(0x16) IP 或 DHCP 指针无效
  • NX_INVALID_INTERFACE:(0x4C) 网络接口无效

允许来自

线程、初始化

示例

/* Send DHCP Client messages with the broadcast flag cleared (e.g. request a 
   unicast response) on a previously attached secondary interface.  */

iface_index = 1;

status =  nx_dhcp_interface_clear_broadcast_flag(&my_dhcp, iface_index, NX_TRUE);

/* If status is NX_SUCCESS the DHCP Client broadcast flag is updated.  */

nx_dhcp_delete

删除 DHCP 实例

原型

UINT nx_dhcp_delete(NX_DHCP *dhcp_ptr);

说明

此服务可删除以前创建的 DHCP 实例。

输入参数

  • dhcp_ptr:指向以前所创建 DHCP 实例的指针。

返回值

  • NX_SUCCESS:(0x00) 成功删除 DHCP。
  • NX_PTR_ERROR:(0x16) DHCP 指针无效。
  • NX_CALLER_ERROR:(0x11) 此服务的调用方无效。

获准方式

线程数

示例

/* Delete a DHCP instance.  */
status =  nx_dhcp_delete(&my_dhcp);

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

nx_dhcp_force_renew

发送强制续订消息

原型

UINT nx_dhcp_force_renew(NX_DHCP *dhcp_ptr);

说明

使用此服务,主机应用程序可在为 DHCP 启用的所有接口上发送强制续订消息。 DHCP 客户端必须处于“绑定”状态。 此函数可将状态设置为“续订”,以使 DHCP 客户端在 T1 超时时间到期之前尝试续订。

若要在为 DHCP 启用多个接口的情况下,在特定接口上发送强制续订消息,请使用 nx_dhcp_interface_force_renew

输入参数

  • dhcp_ptr:指向以前所创建 DHCP 实例的指针。

返回值

  • NX_SUCCESS:(0x00) 已成功发送强制续订消息。
  • NX_DHCP_NOT_BOUND:(0x94) 未绑定客户端 IP 地址。
  • NX_PTR_ERROR:(0x16) DHCP 指针无效。
  • NX_CALLER_ERROR:(0x11) 此服务的调用方无效。

获准方式

线程数

示例

/* Send a force renew message from the Client.  */
status =  nx_dhcp_force_renew(&my_dhcp);

/* If status is NX_SUCCESS the DHCP client state is the RENEWING state and the    
   DHCP Client thread task will begin renewing before T1 is expired.  */

nx_dhcp_interface_force_renew

在指定接口上发送强制续订消息

原型

UINT nx_dhcp_interface_force_renew(
    NX_DHCP *dhcp_ptr, 
    UINT interface_index);

说明

只要已为 DHCP 启用输入接口,主机应用程序即可使用此服务,在该接口上发送强制续订消息(请参阅 nx_dhcp_interface_enable)。 指定接口上的 DHCP 客户端必须处于“绑定”状态。 此函数可将状态设置为“续订”,以使 DHCP 客户端在 T1 超时时间到期之前尝试续订。

输入参数

  • dhcp_ptr:指向以前所创建 DHCP 实例的指针。

返回值

  • NX_SUCCESS:(0x00) 已成功发送强制续订消息。
  • NX_DHCP_INTERFACE_NOT_ENABLED:(0xA4) 没有为 DHCP 启用接口
  • NX_PTR_ERROR:(0x16) IP 或 DHCP 指针无效
  • NX_INVALID_INTERFACE:(0x4C) 网络接口无效

获准方式

线程数

示例

/* Send a force renew message to the server on interface 1.  */
status =  nx_dhcp_interface_force_renew(&my_dhcp, 1);


/* If status is NX_SUCCESS the DHCP client state is the RENEWING state and the    
   DHCP Client thread task will begin renewing before T1 is expired.  */

nx_dhcp_packet_pool_set

设置 DHCP 客户端数据包池

原型

UINT nx_dhcp_packet_pool_set(
    NX_DHCP *dhcp_ptr,
    NX_PACKET_POOL *packet_pool_ptr);

说明

使用此服务,应用程序可在此服务调用中传递指向先前所创建数据包池的指针,从而创建 DHCP 客户端数据包池。 若要使用此功能,主机应用程序必须定义 NX_DHCP_CLIENT_USER_CREATE_PACKET_POOL。 定义后,nx_dhcp_create 服务不能创建客户端的数据包池。

注意

在创建数据包池时,建议应用程序使用 DHCP 客户端数据包池有效负载的默认值,如 nxd_dhcp_client.h 的 NX_DHCP_PACKET_PAYLOAD 所定义。

输入参数

  • dhcp_ptr:指向 DHCP 控制块的指针。
  • packet_pool_ptr:指向以前所创建数据包池的指针

返回值

  • NX_SUCCESS:(0x00) 已设置 DHCP 客户端数据包池
  • NX_NOT_ENABLED:(0x14) 未启用服务
  • NX_PTR_ERROR:(0x16) DHCP 指针无效
  • NX_DHCP_INVALID_PAYLOAD:(0x9C) 有效负载太小

获准方式

应用程序代码

示例

/* Create the packet pool. */
status =  nx_packet_pool_create(&dhcp_pool, "DHCP Client Packet Pool", 
                                 NX_DHCP_PACKET_PAYLOAD, pointer, 
                                 (15 * NX_DHCP_PACKET_PAYLOAD));

/* Create the DHCP Client. */
status =  nx_dhcp_create(&dhcp_0, &ip_0, "janetsdhcp1");

/* Set the DHCP Client packet pool.  */
status =  nx_dhcp_packet_pool_set(&my_dhcp, packet_pool_ptr);
/* If status is NX_SUCCESS packet pool was successfully set.  */

nx_dhcp_request_client_ip

为 DHCP 实例设置请求的 IP 地址

原型

UINT nx_dhcp_request_client_ip(
    NX_DHCP *dhcp_ptr, 
    ULONG client_ip_address, 
    UINT skip_discover_message);

说明

此服务可在为 DHCP 客户端记录中 DHCP 启用的第一个接口上设置 DHCP 客户端向 DHCP 服务器请求的 IP 地址。 如果已设置 skip_discover_message 标记,则 DHCP 客户端会跳过发现消息,并发送请求消息。

若要针对特定接口的 DHCP 消息设置特定 IP 请求,请使用 nx_dhcp_interface_request_client_ip 服务。

输入参数

  • dhcp_ptr:指向 DHCP 控制块的指针。
  • client_ip_address:向 DHCP 服务器请求的 IP 地址
  • skip_discover_message:
    • 如果为 true,则 DHCP 客户端发送请求消息
    • 如果为 false,则发送发现消息。

返回值

  • NX_SUCCESS:(0x00) 已设置请求的 IP 地址。
  • NX_PTR_ERROR:(0x16) DHCP 指针无效
  • NX_DHCP_INVALID_IP_REQUEST:(0x9D) 请求的 IP 地址为 NULL

获准方式

线程数

示例

/* Set the DHCP Client requested IP address and skip the discover message.  */

status =  nx_dhcp_request_client_ip(&my_dhcp, IP(192,168,0,6), NX_TRUE);

/* If status is NX_SUCCESS requested IP address was successfully set.  */

nx_dhcp_interface_request_client_ip

在指定接口上为 DHCP 实例设置请求的 IP 地址

原型

UINT nx_dhcp_interface_request_client_ip(
    NX_DHCP *dhcp_ptr,
    UINT  interface_index, 
    ULONG client_ip_address,
    UINT skip_discover_message);

说明

如果已为 DHCP 启用指定接口,则此服务可在该接口上设置 DHCP 客户端向 DHCP 服务器请求的 IP 地址(请参阅 nx_dhcp_interface_enable)。 如果已设置 skip_discover_message 标志,则 DHCP 客户端会跳过发现消息,并发送请求消息。

输入参数

  • dhcp_ptr:指向 DHCP 控制块的指针。
  • Interface_index:请求 IP 地址所使用接口的索引
  • client_ip_address:向 DHCP 服务器请求的 IP 地址
  • skip_discover_message:如果为 true,则 DHCP 客户端发送请求消息;否则发送发现消息。

返回值

  • NX_SUCCESS:(0x00) 已设置请求的 IP 地址。
  • NX_DHCP_INTERFACE_NOT_ENABLED:(0xA4) 没有为 DHCP 启用接口
  • NX_PTR_ERROR:(0x16) IP 或 DHCP 指针无效
  • NX_INVALID_INTERFACE:(0x4C) 网络接口无效

允许来自

线程数

示例

/* Set the DHCP Client requested IP address and skip the discover message on  
   interface 0.  */
status =  nx_dhcp_interface_request_client_ip(&my_dhcp, 0, IP(192,168,0,6), NX_TRUE);

/* If status is NX_SUCCESS requested IP address was successfully set.  */

nx_dhcp_reinitialize

清除 DHCP 客户端网络参数

原型

UINT nx_dhcp_reinitialize(NX_DHCP *dhcp_ptr);

说明

此服务可清除主机应用程序网络参数(IP 地址、网络地址和网络掩码),并可清除为 DHCP 启用的所有接口的 DHCP 客户端状态。 此服务与 nx_dhcp_stop 和 nx_dhcp_start 结合使用,可“重新启动”DHCP 状态机:

nx_dhcp_stop(&my_dhcp);
nx_dhcp_reinitialize(&my_dhcp);
nx_dhcp_start(&my_dhcp);

若要在为 DHCP 启用多个接口的情况下,重新初始化特定接口上的 DHCP 客户端,请使用 nx_dhcp_interface_reinitialize 服务。

输入参数

  • dhcp_ptr:指向以前所创建 DHCP 实例的指针。

返回值

  • NX_SUCCESS:(0x00) 已成功重新初始化 DHCP
  • NX_PTR_ERROR:(0x16) DHCP 指针无效

获准方式

线程数

示例

/* Reinitialize the previously started DHCP client.  */
status =  nx_dhcp_reinitialize(&my_dhcp);

/* If status is NX_SUCCESS the host application successfully reinitialized its network parameters and DHCP client state. */

nx_dhcp_interface_reinitialize

清除指定接口的 DHCP 客户端网络参数

原型

UINT nx_dhcp_interface_reinitialize(
    NX_DHCP *dhcp_ptr, 
    UINT interface_index);

说明

如果已为 DHCP 启用指定接口,则此服务可清除该接口的网络参数(IP 地址、网络地址和网络掩码)(请参阅 nx_dhcp_interface_enable)。 有关更多详细信息,请参阅 nx_dhcp_reinitialize

输入参数

  • dhcp_ptr:指向以前所创建 DHCP 实例的指针
  • interface_index:重新初始化所使用接口的索引

返回值

  • NX_SUCCESS:(0x00) 已成功重新初始化接口
  • NX_DHCP_INTERFACE_NOT_ENABLED:(0xA4) 没有为 DHCP 启用接口
  • NX_PTR_ERROR:(0x16) DHCP 指针无效
  • NX_CALLER_ERROR:(0x11) 此服务的调用方无效。
  • NX_INVALID_INTERFACE:(0x4C) 网络接口无效

获准方式

线程数

示例

/* Reinitialize the previously started DHCP client on interface 1.  */
status =  nx_dhcp_interface_reinitialize(&my_dhcp, 1);

/* If status is NX_SUCCESS the host application successfully reinitialized its network parameters and DHCP client state. */

nx_dhcp_release

释放租用的 IP 地址

原型

UINT nx_dhcp_release(NX_DHCP *dhcp_ptr);

说明

此服务可通过向 DHCP 服务器发送释放消息,释放从该服务器获取的 IP 地址。 此服务随后会重新初始化 DHCP 客户端。 此服务适用于为 DHCP 启用的所有接口。

应用程序可通过调用 nx_dhcp_start 来重新启动 DHCP 客户端。

若要在特定接口上将地址释放回 DHCP 服务器,请使用 nx_dhcp_interface_release 服务

输入参数

  • dhcp_ptr:指向以前所创建 DHCP 实例的指针。

返回值

  • NX_SUCCESS:(0x00) DHCP 释放成功。
  • NX_DHCP_NOT_BOUND:(0x94) 尚未租用 IP 地址,因此无法释放。
  • NX_PTR_ERROR:(0x16) DHCP 指针无效。
  • NX_CALLER_ERROR:(0x11) 此服务的调用方无效。

获准方式

线程数

示例

/* Release the previously leased IP address.  */
status =  nx_dhcp_release(&my_dhcp);

/* If status is NX_SUCCESS the previous IP lease was successfully released.  */

nx_dhcp_interface_release

在指定接口上释放 IP 地址

原型

UINT nx_dhcp_interface_release(NX_DHCP *dhcp_ptr, UINT interface_index);

说明

此服务可在指定接口上释放从 DHCP 服务器获取的 IP 地址,并重新初始化 DHCP 客户端。 用户可通过调用 nx_dhcp_start 来重新启动 DHCP 客户端。

输入参数

  • dhcp_ptr:指向以前所创建 DHCP 实例的指针。

返回值

  • NX_SUCCESS:(0x00) DHCP 释放成功。
  • NX_DHCP_INTERFACE_NOT_ENABLED:(0xA4) 没有为 DHCP 启用接口
  • NX_DHCP_NOT_BOUND:(0x94) 尚未租用 IP 地址,因此无法释放。
  • NX_PTR_ERROR:(0x16) DHCP 指针无效
  • NX_CALLER_ERROR:(0x11) 此服务的调用方无效。
  • NX_INVALID_INTERFACE:(0x4C) 网络接口无效

获准方式

线程数

示例

/* Release the previously leased IP address on interface 1.  */
status =  nx_dhcp_interface_release(&my_dhcp, 1);

/* If status is NX_SUCCESS the previous IP lease was successfully released.  */

nx_dhcp_decline

拒绝 DHCP 服务器分配的 IP 地址

原型

UINT nx_dhcp_decline(NX_DHCP *dhcp_ptr);

说明

此服务可在为 DHCP 启用的所有接口上拒绝从 DHCP 服务器租用的 IP 地址。 如果已定义 NX_DHCP_CLIENT_ SEND_ ARP_PROBE,则 DHCP 客户端会在检测到 IP 地址已在使用中时发送拒绝消息。 有关 NetX Duo DHCP 客户端中 ARP 探测配置的详细信息,请参阅第一章的“ARP 探测”。

如果应用程序通过其他方式发现 IP 地址正在使用中,则可使用此服务拒绝此地址。

此服务会重新初始化 DHCP 客户端,以便用户通过调用 nx_dhcp_start 来重新启动此客户端。

输入参数

  • dhcp_ptr:指向以前所创建 DHCP 实例的指针。

返回值

  • NX_SUCCESS:(0x00) 已成功发送拒绝消息
  • NX_DHCP_NOT_BOUND:(0x94) 未绑定 DHCP 客户端
  • NX_PTR_ERROR:(0x16) DHCP 指针无效
  • NX_CALLER_ERROR:(0x11) 此服务的调用方无效

获准方式

线程数

示例


/* Decline the IP address offered by the DHCP server.  */
status =  nx_dhcp_decline(&my_dhcp);

/* If status is NX_SUCCESS the previous IP address decline message was successfully trasnmitted.  */

nx_dhcp_interface_decline

在指定接口上拒绝 DHCP 服务器分配的 IP 地址

原型

UINT nx_dhcp_interface_decline(
    NX_DHCP *dhcp_ptr, 
    UINT interface_index);

说明

此服务可向服务器发送拒绝消息,以拒绝 DHCP 服务器分配的 IP 地址。 此服务还会重新初始化 DHCP 客户端。 有关更多详细信息,请参阅 nx_dhcp_decline

输入参数

  • dhcp_ptr:指向以前所创建 DHCP 实例的指针。
  • Interface_index:拒绝 IP 地址所使用接口的索引

返回值

  • NX_SUCCESS:(0x00) 已发送 DHCP 拒绝消息
  • NX_DHCP_NOT_BOUND:(0x94) 未绑定 DHCP 客户端
  • NX_DHCP_INTERFACE_NOT_ENABLED:(0xA4) 没有为 DHCP 启用接口
  • NX_PTR_ERROR:(0x16) DHCP 指针无效
  • NX_CALLER_ERROR:(0x11) 此服务的调用方无效。
  • NX_INVALID_INTERFACE:(0x4C) 网络接口无效

允许来自

线程数

示例

/* Decline the IP address offered by the DHCP server on interface 2.  */
status =  nx_dhcp_interface_decline(&my_dhcp, 2);

/* If status is NX_SUCCESS the previous IP address decline message was successfully trasnmitted.  */

nx_dhcp_send_request

向服务器发送 DHCP 消息

原型

UINT nx_dhcp_send_request(
    NX_DHCP *dhcp_ptr, 
    UINT dhcp_message_type);

说明

此服务可在为 DHCP 客户端记录中 DHCP 启用的第一个接口上向 DHCP 服务器发送指定 DHCP 消息。 若要发送释放或拒绝消息,应用程序必须分别使用 nx_dhcp[_interface]_release 或 nx_dhcp_interface_decline 服务

除发送 INFORM_REQUEST 消息类型以外,用户必须启动 DHCP 客户端才能使用此服务。

注意

此服务不适用于“驱动”DHCP 客户端状态机的主机应用程序。

输入参数

  • dhcp_ptr:指向 DHCP 控制块的指针。
  • dhcp_message_type:请求消息(在 nxd_dhcp_client.h 中定义)

返回值

  • NX_SUCCESS:(0x00) 已发送 DHCP 消息
  • NX_DHCP_NOT_STARTED:(0x96) 接口索引无效
  • NX_DHCP_INVALID_MESSAGE:(0x9B) 要发送的消息类型无效
  • NX_PTR_ERROR:(0x16) 指针输入无效

获准方式

线程数

示例

/* Send the DHCP INFORM REQUEST message to the server.  */

status =  nx_dhcp_send_request(&my_dhcp, NX_DHCP_TYPE_DHCPINFORM);
/* If status is NX_SUCCESS a DHCP message was successfully sent.  */

nx_dhcp_interface_send_request

在特定接口上向服务器发送 DHCP 消息

原型

UINT nx_dhcp_interface_send_request(
    NX_DHCP *dhcp_ptr, 
    UINT interface_index, 
    UINT dhcp_message_type);

说明

如果已为 DHCP 启用指定接口,则此服务可在该接口上向 DHCP 服务器发送消息。 若要发送释放或拒绝消息,应用程序必须分别使用 nx_dhcp[_interface]_release 或 nx_dhcp_interface_decline 服务

除发送 DHCP INFORM REQUEST 消息类型以外,用户必须启动 DHCP 客户端才能使用此服务。

此服务不适用于“驱动”DHCP 客户端状态机的主机应用程序。

输入参数

  • dhcp_ptr:指向 DHCP 控制块的指针。
  • Interface_index:发送消息所使用接口的索引
  • dhcp_message_type:请求消息(在 nxd_dhcp_client.h 中定义)

返回值

  • NX_SUCCESS:(0x00) 已发送 DHCP 消息
  • NX_DHCP_NOT_STARTED:(0x96) 接口索引无效
  • NX_DHCP_INVALID_MESSAGE:(0x9B) 要发送的消息类型无效
  • NX_DHCP_INTERFACE_NOT_ENABLED:(0xA4) 没有为 DHCP 启用接口
  • NX_PTR_ERROR:(0x16) DHCP 指针无效
  • NX_CALLER_ERROR:(0x11) 此服务的调用方无效。
  • NX_INVALID_INTERFACE:(0x4C) 网络接口无效

允许来自

线程数

示例

/* Send the INFORM REQUEST message to the server on the primary interface.  */

status =  nx_dhcp_interface_send_request(&my_dhcp, 0, NX_DHCP_TYPE_DHCPINFORM);
/* If status is NX_SUCCESS a DHCP message was successfully sent.  */

nx_dhcp_server_address_get

获取 DHCP 客户端的 DHCP 服务器 IP 地址

原型

UINT nx_dhcp_server_address_get(
    NX_DHCP *dhcp_ptr, 
    ULONG server_address);

说明

此服务可在为 DHCP 客户端记录中 DHCP 启用的第一个接口上检索 DHCP 客户端的 DHCP 服务器 IP 地址。 仅当 DHCP 客户端绑定到 DHCP 服务器分配的 IP 地址后,调用方才能使用此服务。 主机应用程序可使用 nx_ip_status_check 服务验证是否已设置 IP 地址,也可以使用 nx_dhcp_state_change_notify,并查询 DHCP 客户端状态是否为 NX_DHCP_STATE_BOUND。 有关设置状态更改回调函数的更多详细信息,请参阅 nx_dhcp_state_change_notify。

若要在为 DHCP 客户端启用多个接口的情况下,在特定接口上查找 DHCP 服务器,请使用 nx_dhcp_interface_server_address_get 服务

输入参数

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

返回值

  • NX_SUCCESS:(0x00) 已返回 DHCP 服务器地址
  • NX_DHCP_NO_INTERFACES_ENABLED:(0xA5) 没有为 DHCP 启用接口
  • NX_PTR_ERROR:(0x16) 输入指针无效
  • NX_CALLER_ERROR:(0x11) 此服务的调用方无效。

获准方式

线程数

示例

/* Use the state change notify service to determine the Client transition to the bound state and get its DHCP server IP address.*/

void dhcp_state_change(NX_DHCP *dhcp_ptr, UCHAR new_state)
{
ULONG server_address;
UINT  status;

/* Increment state changes counter.  */
state_changes++;

if (dhcp_0.nx_dhcp_state == NX_DHCP_STATE_BOUND)
    	{
            status = nx_dhcp_server_address_get(&dhcp_0, &server_address);
    	}

}

nx_dhcp_interface_server_address_get

在指定接口上获取 DHCP 客户端的 DHCP 服务器 IP 地址

原型

UINT nx_dhcp_interface_server_address_get(
    NX_DHCP *dhcp_ptr, 
    UINT interface_index,
    ULONG server_address);

说明

如果已为 DHCP 启用指定接口,则此服务可在该接口上检索 DHCP 客户端的 DHCP 服务器 IP 地址。 DHCP 客户端必须处于“绑定”状态。 在该接口上启动 DHCP 客户端后,主机应用程序可使用 nx_ip_status_check 服务验证是否已设置 IP 地址,也可以使用 DHCP 客户端状态更改回调函数,并查询 DHCP 客户端状态是否为 NX_DHCP_STATE_BOUND。 有关设置状态更改回调函数的更多详细信息,请参阅 nx_dhcp_state_change_notify

输入参数

  • dhcp_ptr:指向 DHCP 控制块的指针。
  • Interface_index:获取 IP 地址所使用接口的索引
  • server_address:指向服务器 IP 地址的指针

返回值

  • NX_SUCCESS:(0x00) 已返回 DHCP 服务器地址
  • NX_DHCP_NO_INTERFACES_ENABLED:(0xA5) 没有为 DHCP 启用接口
  • NX_DHCP_NOT_BOUND:(0x94) 未绑定 DHCP 客户端
  • NX_PTR_ERROR:(0x16) DHCP 指针无效
  • NX_CALLER_ERROR:(0x11) 此服务的调用方无效。
  • NX_INVALID_INTERFACE:(0x4C) 网络接口无效

允许来自

线程数

示例

/* Use the state change notify service to determine the Client transition to the 
bound state and get its DHCP server IP address. */

void dhcp_state_change(NX_DHCP *dhcp_ptr, UCHAR new_state)
{

ULONG server_address;
UINT  status;

/* Increment state changes counter.  */
state_changes++;

/* Get the DHCP server IP address on interface 1 */
if (dhcp_0.nx_dhcp_state == NX_DHCP_STATE_BOUND)
    	{
         status = nx_dhcp_interface_server_address_get(&dhcp_0, 1, 
                                                       &server_address);
    	}
}

nx_dhcp_set_interface_index

设置 DHCP 实例的网络接口

原型

UINT nx_dhcp_set_interface_index(
    NX_DHCP *dhcp_ptr,
    UINT index);

说明

在运行已配置单个网络接口的 DHCP 客户端时,此服务可为 DHCP 实例设置连接到 DHCP 服务器所使用的网络接口。

默认情况下,DHCP 客户端在主接口上运行。 若要在辅助服务中运行 DHCP,请使用此服务设置辅助接口作为 DHCP 客户端接口。 应用程序之前必须使用 nx_ip_interface_attach 服务在 IP 实例中注册指定接口。

注意

此服务适用于仅在一个接口上运行 DHCP 客户端的应用程序。 若要在多个接口上运行 DHCP,请参阅 nx_dhcp_interface_enable 了解更多详细信息。

输入参数

  • dhcp_ptr:指向 DHCP 控制块的指针。
  • index:设备网络接口的索引

返回值

  • NX_SUCCESS:(0x00) 已成功设置接口。
  • NX_INVALID_INTERFACE:(0x4C) 网络接口无效
  • NX_DHCP_INTERFACE_ALREADY_ENABLED:(0xA3) 已为 DHCP 启用接口
  • NX_DHCP_NO_RECORDS_AVAILABLE:(0xA7) 无可用记录,无法再启用一个
  • NX_PTR_ERROR:(0x16) DHCP 指针无效

获准方式

线程数

示例

/* Set the DHCP Client interface to the secondary interface (index 1).  */
status =  nx_dhcp_set_interface_index(&my_dhcp, 1);
/* If status is NX_SUCCESS a DHCP interface was successfully set.  */

nx_dhcp_start

启动 DHCP 处理

原型

UINT nx_dhcp_start(NX_DHCP *dhcp_ptr);

说明

此服务可在为 DHCP 启用的所有接口上启动 DHCP 处理。 默认情况下,当应用程序调用 nx_dhcp_create 时,已为 DHCP 启用主接口。

若要验证 IP 实例何时在 DHCP 客户端接口上绑定 IP 地址,请使用 nx_ip_status_check 确认 IP 地址是否有效。

如果其他接口已在运行 DHCP,则此服务不会影响它们。

若要在启用多个接口的情况下,在特定接口上启动 DHCP,请使用 nx_dhcp_interface_start 服务。

输入参数

  • dhcp_ptr:指向以前所创建 DHCP 实例的指针。

返回值

  • NX_SUCCESS:(0x00) 成功启动 DHCP。
  • NX_DHCP_ALREADY_STARTED:(0x93) 已启动 DHCP。
  • NX_PTR_ERROR:(0x16) DHCP 指针无效。
  • NX_CALLER_ERROR:(0x11) 服务调用方无效。

允许来自

线程数

示例

/* Start the DHCP processing for this IP instance.  */
status =  nx_dhcp_start(&my_dhcp);

/* If status is NX_SUCCESS the DHCP was successfully started.  */

nx_dhcp_interface_start

在指定接口上启动 DHCP 处理

原型

UINT nx_dhcp_interface_start(
    NX_DHCP *dhcp_ptr, 
    UINT interface_index);

说明

如果已为 DHCP 启用指定接口,则此服务可在该接口上启动 DHCP 处理。 有关为 DHCP 启用接口的更多详细信息,请参阅 nx_dhcp_interface_enable。 默认情况下,当应用程序调用 nx_dhcp_create 时,已为 DHCP 启用主接口。

如果没有其他接口运行 DHCP 客户端,则此服务将启动/恢复 DHCP 客户端线程,并(重新)激活 DHCP 客户端计时器。

应用程序应使用 nx_ip_status_check 验证是否已获取 IP 地址。

输入参数

  • dhcp_ptr:指向以前所创建 DHCP 实例的指针。
  • Interface_index:启动 DHCP 客户端所使用接口的索引

返回值

  • NX_SUCCESS:(0x00) 成功启动 DHCP。
  • NX_DHCP_ALREADY_STARTED:(0x93) 已启动 DHCP。
  • NX_PTR_ERROR:(0x16) DHCP 指针无效。
  • NX_CALLER_ERROR:(0x11) 服务调用方无效。
  • NX_INVALID_INTERFACE:(0x4C) 网络接口无效

获准方式

线程数

示例

/* Start the DHCP processing for this IP instance on interface 1.  */
status =  nx_dhcp_interface_start(&my_dhcp, 1);

/* If status is NX_SUCCESS the DHCP was successfully started.  */

nx_dhcp_state_change_notify

设置 DHCP 状态更改回调函数

原型

UINT nx_dhcp_state_change_notify(
    NX_DHCP *dhcp_ptr, 
    VOID (*dhcp_state_change_notify)(
        NX_DHCP *dhcp_ptr,
        UCHAR new_state));

说明

此服务可注册指定回调函数 dhcp_state_change_notify,以通知应用程序 DHCP 状态更改。 回调函数可提供 DHCP 客户端已转换的状态。

下面是与各种 DHCP 状态关联的值:

  • NX_DHCP_STATE_BOOT:1
  • NX_DHCP_STATE_INIT:2
  • NX_DHCP_STATE_SELECTING:3
  • NX_DHCP_STATE_REQUESTING:4
  • NX_DHCP_STATE_BOUND:5
  • NX_DHCP_STATE_RENEWING:6
  • NX_DHCP_STATE_REBINDING:7
  • NX_DHCP_STATE_FORCERENEW:8
  • NX_DHCP_STATE_ADDRESS_PROBING:9

输入参数

  • dhcp_ptr:指向以前所创建 DHCP 实例的指针。
  • dhcp_state_change_notify:状态更改回调函数指针

返回值

  • NX_SUCCESS:(0x00) 成功设置回调函数。
  • NX_PTR_ERROR:(0x16) DHCP 指针无效。
  • NX_CALLER_ERROR:(0x11) 服务调用方无效。

允许来自

线程、初始化

示例

/* Register the “my_state_change” function to be called on any DHCP state change, assuming DHCP has alreadybeen created.  */
status =  nx_dhcp_state_change_notify(&my_dhcp, my_state_change);

/* If status is NX_SUCCESS the callback function was successfully
   registered.  */

nx_dhcp_interface_state_change_notify

在指定接口上设置 DHCP 状态更改回调函数

原型

UINT nx_dhcp_interface_state_change_notify(
    NX_DHCP *dhcp_ptr,
    UINT interface_index,
    VOID (*dhcp_state_change_notify)(
        NX_DHCP *dhcp_ptr, 
        UINT interface_index,
        UCHAR new_state));

说明

此服务可注册指定回调函数,以通知应用程序 DHCP 状态更改。 回调函数输入参数是接口索引和 DHCP 客户端在该接口上已转换的状态。

有关状态更改函数的详细信息,请参阅 nx_dhcp_state_change_notify()。

输入参数

  • dhcp_ptr:指向以前所创建 DHCP 实例的指针。
  • dhcp_interface_state_change_notify:应用程序回调函数指针

返回值

  • NX_SUCCESS:(0x00) 成功设置回调函数。
  • NX_PTR_ERROR:(0x16) DHCP 指针无效。

获准方式

线程、初始化

示例

/* Register the “my_state_change” function to be called on any DHCP state change,   
   assuming DHCP has alreadybeen created.  */

void dhcp_interstate_state_change(NX_DHCP *dhcp_ptr, UINT iface_index, 
                                  UCHAR new_state);


status =  nx_dhcp_interstate_state_change_notify(&my_dhcp,  
                                                 dhcp_interstate_state_change);

/* If status is NX_SUCCESS the callback function was successfully
   registered.  */

nx_dhcp_stop

停止 DHCP 处理

原型

UINT nx_dhcp_stop(NX_DHCP *dhcp_ptr);

说明

此服务可在已启动 DHCP 处理的所有接口上停止 DHCP 处理。 如果没有接口处理 DHCP,此服务会挂起 DHCP 客户端线程,并停用 DHCP 客户端计时器。

若要在为 DHCP 启用多个接口的情况下,在特定接口上停止 DHCP,请使用 nx_dhcp_interface_stop 服务。

输入参数

  • dhcp_ptr:指向以前所创建 DHCP 实例的指针。

返回值

  • NX_SUCCESS:(0x00) 成功停止 DHCP
  • NX_DHCP_NOT_STARTED:(0x96) 未启动 DHCP 实例。
  • NX_PTR_ERROR:(0x16) DHCP 指针无效。
  • NX_CALLER_ERROR:(0x11) 服务调用方无效。

允许来自

线程数

示例

/* Stop the DHCP processing for this IP instance.  */
status =  nx_dhcp_stop(&my_dhcp);

/* If status is NX_SUCCESS the DHCP was successfully stopped.  */

nx_dhcp_interface_stop

在指定接口上停止 DHCP 处理

原型

UINT nx_dhcp_interface_stop(
    NX_DHCP *dhcp_ptr,
    UINT interface_index);

说明

如果已启动 DHCP,则此服务可在指定接口上停止 DHCP 处理。 如果没有其他接口运行 DHCP,则会挂起 DHCP 线程和计时器。

输入参数

  • dhcp_ptr:指向以前所创建 DHCP 实例的指针。
  • Interface_index:停止 DHCP 处理所使用的接口

返回值

  • NX_SUCCESS:(0x00) 成功停止 DHCP
  • NX_DHCP_NOT_STARTED:(0x96) 未启动 DHCP。
  • NX_PTR_ERROR:(0x16) DHCP 指针无效。
  • NX_CALLER_ERROR:(0x11) 服务调用方无效。
  • NX_INVALID_INTERFACE:(0x4C) 网络接口无效

获准方式

线程数

示例

/* Stop DHCP processing for this IP instance on interface 1.  */
status =  nx_dhcp_interface_stop(&my_dhcp, 1);

/* If status is NX_SUCCESS the DHCP was successfully stopped.  */

nx_dhcp_user_option_retrieve

检索上次服务器响应中的 DHCP 选项

原型

UINT nx_dhcp_user_option_retrieve(
    NX_DHCP *dhcp_ptr,
    UINT request_option, 
    UCHAR *destination_ptr,
    UINT *destination_size);

说明

此服务可在为 DHCP 客户端记录中 DHCP 启用的第一个接口上从选项缓冲区中检索指定 DHCP 选项。 如果成功,则会将选项数据复制到指定缓冲区中。

输入参数

  • dhcp_ptr:指向以前所创建 DHCP 实例的指针。
  • request_option:RFC 所指定的 DHCP 选项。 请参阅 nxd_dhcp_client.h 中的 NX_DHCP_OPTION 选项。
  • destination_ptr:指向响应字符串目标的指针。
  • destination_size:指向目标大小的指针,返回值后,目标可容纳所返回字节数的内容。

返回值

  • NX_SUCCESS:(0x00) 成功检索选项。
  • NX_DHCP_NOT_BOUND:(0x94) 未绑定 DHCP 客户端。
  • NX_DHCP_NO_INTERFACES_ENABLED:(0xA5) 没有为 DHCP 启用接口
  • NX_DHCP_DEST_TO_SMALL:(0x95) 目标太小,无法容纳响应。
  • NX_DHCP_PARSE_ERROR:(0x97) 在服务器响应中找不到选项。
  • NX_PTR_ERROR:(0x16) 输入指针无效。
  • NX_CALLER_ERROR:(0x11) 此服务的调用方无效。

获准方式

线程数

示例

UCHAR  dns_ip_string[4];
ULONG  size;

/* Obtain the IP address of the DNS server.  */
size =    sizeof(dnx_ip_string);
status =  nx_dhcp_user_option_retrieve(&my_dhcp, NX_DHCP_OPTION_DNS_SVR,
                                        dns_ip_string, &size);

/* If status is NX_SUCCESS the DNS IP address is in dns_ip_string.  */

nx_dhcp_interface_user_option_retrieve

在指定接口上从上次服务器响应中检索 DHCP 选项

原型

UINT nx_dhcp_interface_user_option_retrieve(
    NX_DHCP *dhcp_ptr,
    UINT interface_index,
    UINT request_option, UCHAR *destination_ptr,
    UINT *destination_size);

说明

如果已为 DHCP 启用指定接口,则此服务可在该接口上从 DHCP 选项缓冲区中检索指定 DHCP 选项。 如果成功,则会将选项数据复制到指定缓冲区中。

输入参数

  • dhcp_ptr:指向以前所创建 DHCP 实例的指针。
  • Interface_index:检索指定选项所使用接口的索引
  • request_option:RFC 所指定的 DHCP 选项。 请参阅 nxd_dhcp_client.h 中的 NX_DHCP_OPTION 选项。
  • destination_ptr:指向响应字符串目标的指针。
  • destination_size:指向目标大小的指针,返回值后,目标可容纳所返回字节数的内容。

返回值

  • NX_SUCCESS:(0x00) 成功检索选项。
  • NX_DHCP_NOT_BOUND:(0x94) 未分配 IP 地址
  • NX_DHCP_DEST_TO_SMALL:(0x95) 缓冲区太小
  • NX_DHCP_PARSE_ERROR:(0x97) 在服务器响应中找不到 DHCP 选项。
  • NX_PTR_ERROR:(0x16) DHCP 指针无效。
  • NX_CALLER_ERROR:(0x11) 服务调用方无效。
  • NX_INVALID_INTERFACE:(0x4C) 网络接口无效

允许来自

线程数

示例

UCHAR  dns_ip_string[4];
ULONG  size;

/* Obtain the IP address of the DNS server on the prmary interface.  */
size =    sizeof(dnx_ip_string);
status =  nx_dhcp_interface_user_option_retrieve(&my_dhcp, 0, NX_DHCP_OPTION_DNS_SVR,
                                                  dns_ip_string, &size);

/* If status is NX_SUCCESS the DNS IP address is in dns_ip_string.  */

nx_dhcp_user_option_convert

将四字节转换为 ULONG

原型

ULONG nx_dhcp_user_option_convert(UCHAR *option_string_ptr);

说明

此服务可将“option_string_ptr”指向的四个字符转换为无符号长值。 在有 IP 地址时,此服务特别有用。

输入参数

  • option_string_ptr:指向以前所检索选项字符串的指针。

返回值

  • Value:前四字节的值。

获准方式

线程数

示例

UCHAR  dns_ip_string[4];
ULONG  dns_ip;

/* Convert the first four bytes of “dns_ip_string” to an actual IP
address in “dns_ip.”  */
dns_ip=  nx_dhcp_user_option_convert(dns_ip_string);

/* If status is NX_SUCCESS the DNS IP address is in “dns_ip.”  */

nx_dhcp_user_option_add_callback_set

设置回调函数,以添加用户提供的选项

原型

ULONG nx_dhcp_user_option_add_callbcak_set(
    NX_DHCP *dhcp_ptr, 
    UINT (*dhcp_user_option_add)(
        NX_DHCP *dhcp_ptr, 
        UINT iface_index, 
        UINT message_type, 
        UCHAR *user_option_ptr, 
        UINT *user_option_length));

说明

此服务可注册指定回调函数,以添加用户提供的选项。

如果已指定回调函数,则应用程序可通过 iface_index 和 message_type 将用户提供的选项添加到数据包中。

注意

在用户的例程中, 添加用户提供的选项时,应用程序必须遵循 DHCP 选项格式。 用户选项的总大小必须小于或等于 user_option_length,并且必须按实际选项长度更新 user_option_length。 如果成功添加选项,则返回 NX_TRUE,否则返回 NX_FALSE。

输入参数

  • dhcp_ptr:指向以前所创建 DHCP 实例的指针。
  • dhcp_user_option_add:指向用户选项添加函数的指针。

返回值

  • NX_SUCCESS:(0x00) 成功设置回调函数。
  • NX_PTR_ERROR:(0x16) 指针无效。

获准方式

线程数

示例

/* Register the “my_dhcp_user_option_add” function to be called when add DHCP
options, assuming DHCP has already been created.  */

status =  nx_dhcp_user_option_add_callback_set(&my_dhcp, my_dhcp_user_option_add);

/* If status is NX_SUCCESS the callback function was successfully registered.  */