第 4 章 - Azure RTOS NetX 服务说明

本章按字母顺序介绍所有 Azure RTOS NetX 服务。 服务名称设计为将所有相似的服务组合在一起。 例如,所有的 ARP 服务都可以在本章开头找到。

注意

请注意,无法充分利用高性能 NetX API 的旧式应用程序代码可以使用与 BSD 兼容的套接字 API。 有关与 BSD 兼容的套接字 API 的详细信息,请参阅“附录 D”。

在每一项说明的“返回值”部分中,以粗体显示的值不受用于禁用 API 错误检查的 NX_DISABLE_ERROR_CHECKING 选项影响,而不以粗体显示的值则会被完全禁用。 “允许调用自”部分指示可从中调用每项 NetX 服务的来源。

nx_arp_dynamic_entries_invalidate

使 ARP 缓存中的所有动态条目失效

原型

UINT nx_arp_dynamic_entries_invalidate(NX_IP *ip_ptr);

说明

此服务会使 ARP 缓存中当前包含的所有动态 ARP 条目失效。

参数

  • ip_ptr:指向以前所创建 IP 实例的指针。

返回值

  • NX_SUCCESS:(0x00) 使 ARP 缓存失效成功。
  • NX_NOT_ENABLED:(0x14) ARP 未启用。
  • NX_PTR_ERROR:(0x07) IP 地址无效。
  • NX_CALLER_ERROR:(0x11) 调用方不是线程。

允许调用自

线程数

可以抢占

示例

/* Invalidate all dynamic entries in the ARP cache. */
status = nx_arp_dynamic_entries_invalidate(&ip_0);
/* If status is NX_SUCCESS the dynamic ARP entries were successfully invalidated. */

另请参阅

  • nx_arp_dynamic_entry_set、nx_arp_enable、nx_arp_gratuitous_send,
  • nx_arp_hardware_address_find、nx_arp_info_get,
  • nx_arp_ip_address_find、nx_arp_static_entries_delete,
  • nx_arp_static_entry_create、nx_arp_static_entry_delete

nx_arp_dynamic_entry_set

设置动态 ARP 条目

原型

UINT nx_arp_dynamic_entry_set(
    NX_IP *ip_ptr,
    ULONG ip_address,
    ULONG physical_msw,
    ULONG physical_lsw);

说明

此服务从 ARP 缓存分配动态条目,并将指定的 IP 设置为物理地址映射。 如果指定了零物理地址,则会将实际的 ARP 请求发送到网络,以便解析该物理地址。 另请注意,如果已激活 ARP 老化,或者 ARP 缓存已用尽并且这是最近最少使用的 ARP 条目,则会删除此条目。

参数

  • ip_ptr:指向以前所创建 IP 实例的指针。
  • ip_address:要映射的 IP 地址。
  • physical_msw:物理地址的高 16 位 (47-32)。
  • physical_lsw:物理地址的低 32 位 (31-0)。

返回值

  • NX_SUCCESS:(0x00) 设置 ARP 动态条目成功。
  • NX_NO_MORE_ENTRIES:(0x17) 在 ARP 缓存中没有更多的 ARP 条目可供使用。
  • NX_IP_ADDRESS_ERROR:(0x21) IP 地址无效。
  • NX_PTR_ERROR:(0x07) IP 实例指针无效。
  • NX_NOT_ENABLED (0x14) 尚未启用此组件。
  • NX_CALLER_ERROR:(0x11) 此服务的调用方无效。

允许调用自

线程数

可以抢占

示例

/* Setup a dynamic ARP entry on the previously created IP Instance 0. */
status = nx_arp_dynamic_entry_set(&ip_0, IP_ADDRESS(1,2,3,4),
    0x1022, 0x1234);
/* If status is NX_SUCCESS, there is now a dynamic mapping between
    the IP address of 1.2.3.4 and the physical hardware address of
    10:22:00:00:12:34. */

另请参阅

  • nx_arp_dynamic_entries_invalidate、nx_arp_enable,
  • nx_arp_gratuitous_send、nx_arp_hardware_address_find,
  • nx_arp_info_get、nx_arp_ip_address_find、nx_arp_static_entries_delete,
  • nx_arp_static_entry_create、nx_arp_static_entry_delete

nx_arp_enable

启用地址解析协议 (ARP)。

原型

UINT nx_arp_enable(
    NX_IP *ip_ptr, 
    VOID *arp_cache_memory, 
    ULONG arp_cache_size);

说明

此服务可为特定的 IP 实例初始化 NetX 的 ARP 组件。 ARP 初始化包括设置 ARP 缓存,以及设置发送和接收 ARP 消息所需的各种 ARP 处理例程。

参数

  • ip_ptr:指向以前所创建 IP 实例的指针。
  • arp_cache_memory:指向要放置 ARP 缓存的内存区域的指针。
  • arp_cache_size:每个 ARP 条目为 52 个字节,因此 ARP 条目总数为大小除以 52。

返回值

  • NX_SUCCESS:(0x00) 启用 ARP 成功。
  • NX_PTR_ERROR:(0x07) IP 或缓存内存指针无效。
  • NX_SIZE_ERROR:(0x09) 用户提供的 ARP 缓存内存太小。
  • NX_CALLER_ERROR:(0x11) 此服务的调用方无效。
  • NX_ALREADY_ENABLED:(0x15) 此组件已启用。

允许调用自

初始化、线程

可以抢占

示例

/* Enable ARP and supply 1024 bytes of ARP cache memory for
    previously created IP Instance ip_0. */
status = nx_arp_enable(&ip_0, (void *) pointer, 1024);
/* If status is NX_SUCCESS, ARP was successfully enabled for this IP instance.*/

另请参阅

  • nx_arp_dynamic_entries_invalidate、nx_arp_dynamic_entry_set,
  • nx_arp_gratuitous_send、nx_arp_hardware_address_find,
  • nx_arp_info_get、nx_arp_ip_address_find、nx_arp_static_entries_delete,
  • nx_arp_static_entry_create、nx_arp_static_entry_delete

nx_arp_gratuitous_send

发送免费 ARP 请求

原型

UINT nx_arp_gratuitous_send(
    NX_IP *ip_ptr,
    VOID (*response_handler) (NX_IP *ip_ptr, NX_PACKET *packet_ptr));

说明

只要接口 IP 地址有效,此服务就会通过所有物理接口传输免费 ARP 请求。 如果随后收到 ARP 响应,则会调用提供的响应处理程序处理对该免费 ARP 的响应。

参数

  • ip_ptr:指向以前所创建 IP 实例的指针。
  • response_handler:指向响应处理函数的指针。 如果提供了 NX_NULL,则会忽略响应。

返回值

  • NX_SUCCESS:(0x00) 发送免费 ARP 成功。
  • NX_NO_PACKET (0x01) 没有可用的数据包。
  • NX_NOT_ENABLED:(0x14) ARP 未启用。
  • NX_IP_ADDRESS_ERROR:(0x21) 当前 IP 地址无效。
  • NX_PTR_ERROR:(0x07) IP 指针无效。
  • NX_CALLER_ERROR:(0x11) 调用方不是线程。

允许调用自

线程数

可以抢占

示例

/* Send gratuitous ARP without any response handler. */
status = nx_arp_gratuitous_send(&ip_0, NX_NULL);

/* If status is NX_SUCCESS the gratuitous ARP was successfully sent. */

另请参阅

  • nx_arp_dynamic_entries_invalidate、nx_arp_dynamic_entry_set,
  • nx_arp_enable、nx_arp_hardware_address_find、nx_arp_info_get,
  • nx_arp_ip_address_find、nx_arp_static_entries_delete,
  • nx_arp_static_entry_create、nx_arp_static_entry_delete

nx_arp_hardware_address_find

根据给定的 IP 地址查找物理硬件地址

原型

UINT nx_arp_hardware_address_find(
    NX_IP *ip_ptr,
    ULONG ip_address, 
    ULONG *physical_msw, 
    ULONG *physical_lsw);

说明

此服务尝试在 ARP 缓存中查找与提供的 IP 地址相关联的物理硬件地址。

参数

  • ip_ptr:指向以前所创建 IP 实例的指针。
  • ip_address:要搜索的 IP 地址。
  • physical_msw:指向变量的指针,该变量用于返回物理地址的高 16 位 (47-32)。
  • physical_lsw:指向变量的指针,该变量用于返回物理地址的低 32 位 (31-0)。

返回值

  • NX_SUCCESS:(0x00) 查找 ARP 硬件地址成功。
  • NX_ENTRY_NOT_FOUND:(0x16) 在 ARP 缓存中找不到映射。
  • NX_IP_ADDRESS_ERROR:(0x21) IP 地址无效。
  • NX_PTR_ERROR:(0x07) IP 指针或内存指针无效。
  • NX_CALLER_ERROR (0x11) 此服务的调用方无效。
  • NX_NOT_ENABLED (0x14) 尚未启用此组件。

允许调用自

线程数

可以抢占

示例

/* Search for the hardware address associated with the IP address of
    1.2.3.4 in the ARP cache of the previously created IP
    Instance 0. */
status = nx_arp_hardware_address_find(
    &ip_0, 
    IP_ADDRESS(1,2,3,4),
    &physical_msw, 
    &physical_lsw);

/* If status is NX_SUCCESS, the variables physical_msw and
    physical_lsw contain the hardware address.*/

另请参阅

  • nx_arp_dynamic_entries_invalidate、nx_arp_dynamic_entry_set,
  • nx_arp_enable、nx_arp_gratuitous_send、nx_arp_info_get,
  • nx_arp_ip_address_find、nx_arp_static_entries_delete,
  • nx_arp_static_entry_create、nx_arp_static_entry_delete

nx_arp_info_get

检索 ARP 活动的相关信息

原型

UINT nx_arp_info_get(
    NX_IP *ip_ptr,
    ULONG *arp_requests_sent,
    ULONG *arp_requests_received,
    ULONG *arp_responses_sent,
    ULONG *arp_responses_received,
    ULONG *arp_dynamic_entries,
    ULONG *arp_static_entries,
    ULONG *arp_aged_entries,
    ULONG *arp_invalid_messages);

说明

此服务检索相关联的 IP 实例的 ARP 活动相关信息。

如果目标指针为 NX_NULL,则不会将该特定信息返回给调用方

参数

  • ip_ptr:指向以前所创建 IP 实例的指针。
  • arp_requests_sent:此指针指向从此 IP 实例发送的全部 ARP 请求的目标。
  • arp_requests_received:此指针指向从网络收到的全部 ARP 请求的目标。
  • arp_responses_sent:此指针指向从此 IP 实例发送的全部 ARP 响应的目标。
  • arp_responses_received:此指针指向从网络收到的全部 ARP 响应的目标。
  • arp_dynamic_entries:此指针指向当前数量的动态 ARP 条目的目标。
  • arp_static_entries:此指针指向当前数量的静态 ARP 条目的目标。
  • arp_aged_entries:此指针指向已老化且已失效的 ARP 条目总数的目标。
  • arp_invalid_messages:此指针指向已收到但无效 ARP 消息总数的目标。

返回值

  • NX_SUCCESS:(0x00) 检索 ARP 信息成功。
  • NX_PTR_ERROR:(0x07) IP 指针无效。
  • NX_CALLER_ERROR (0x11) 此服务的调用方无效。
  • NX_NOT_ENABLED (0x14) 尚未启用此组件。

允许调用自

线程数

可以抢占

示例

/* Pickup ARP information for ip_0. */
status = nx_arp_info_get(
    &ip_0, 
    &arp_requests_sent,
    &arp_requests_received,
    &arp_responses_sent,
    &arp_responses_received,
    &arp_dynamic_entries,
    &arp_static_entries,
    &arp_aged_entries,
    &arp_invalid_messages);
/* If status is NX_SUCCESS, the ARP information has been stored in
    the supplied variables. */

另请参阅

  • nx_arp_dynamic_entries_invalidate、nx_arp_dynamic_entry_set,
  • nx_arp_enable、nx_arp_gratuitous_send,
  • nx_arp_hardware_address_find、nx_arp_ip_address_find,
  • nx_arp_static_entries_delete、nx_arp_static_entry_create,
  • nx_arp_static_entry_delete

nx_arp_ip_address_find

根据给定的物理地址查找 IP 地址

原型

UINT nx_arp_ip_address_find(
    NX_IP *ip_ptr, 
    ULONG *ip_address,
    ULONG physical_msw, 
    ULONG physical_lsw);

说明

此服务尝试在 ARP 缓存中查找与提供的物理地址相关联的 IP 地址。

参数

  • ip_ptr:指向以前所创建 IP 实例的指针。
  • ip_address:指向返回的 IP 地址的指针(如果找到已映射的 IP 地址)。
  • physical_msw:要搜索的物理地址的高 16 位 (47-32)。
  • physical_lsw:要搜索的物理地址的低 32 位 (31-0)。

返回值

  • NX_SUCCESS:(0x00) 查找 ARP IP 地址成功
  • NX_ENTRY_NOT_FOUND:(0x16) 在 ARP 缓存中找不到映射。
  • NX_PTR_ERROR:(0x07) IP 指针或内存指针无效。
  • NX_CALLER_ERROR (0x11) 此服务的调用方无效。
  • NX_NOT_ENABLED (0x14) 尚未启用此组件。
  • NX_INVALID_PARAMETERS:(0x4D) physical_msw 和 physical_lsw 均为 0。

允许调用自

线程数

可以抢占

示例

/* Search for the IP address associated with the hardware address of
    0x0:0x01234 in the ARP cache of the previously created IP
    Instance ip_0. */
status = nx_arp_ip_address_find(&ip_0, &ip_address, 0x0, 0x1234);

/* If status is NX_SUCCESS, the variables ip_address contains the
    associated IP address.*/

另请参阅

  • nx_arp_dynamic_entries_invalidate、nx_arp_dynamic_entry_set,
  • nx_arp_enable、nx_arp_gratuitous_send,
  • nx_arp_hardware_address_find、nx_arp_info_get,
  • nx_arp_static_entries_delete、nx_arp_static_entry_create,
  • nx_arp_static_entry_delete

nx_arp_static_entries_delete

删除所有静态 ARP 条目

原型

UINT nx_arp_static_entries_delete(NX_IP *ip_ptr);

说明

此服务用于删除 ARP 缓存中的所有静态条目。

参数

  • ip_ptr:指向以前所创建 IP 实例的指针。

返回值

  • NX_SUCCESS:(0x00) 静态条目已删除。
  • NX_PTR_ERROR:(0x07) ip_ptr 指针无效。
  • NX_CALLER_ERROR (0x11) 此服务的调用方无效。
  • NX_NOT_ENABLED (0x14) 尚未启用此组件。

允许调用自

初始化、线程

可以抢占

示例

/* Delete all the static ARP entries for IP Instance 0, assuming
    "ip_0" is the NX_IP structure for IP Instance 0. */

status = nx_arp_static_entries_delete(&ip_0);

/* If status is NX_SUCCESS all static ARP entries in the ARP cache
have been deleted. */

另请参阅

  • nx_arp_dynamic_entries_invalidate、nx_arp_dynamic_entry_set,
  • nx_arp_enable、nx_arp_gratuitous_send,
  • nx_arp_hardware_address_find、nx_arp_info_get,
  • nx_arp_ip_address_find、nx_arp_static_entry_create,
  • nx_arp_static_entry_delete

nx_arp_static_entry_create

在 ARP 缓存中创建静态的 IP 到硬件映射

原型

UINT nx_arp_static_entry_create(
    NX_IP *ip_ptr,
    ULONG ip_address,
    ULONG physical_msw,
    ULONG physical_lsw);

说明

此服务针对指定的 IP 实例,在 ARP 缓存中创建静态的 IP 到物理地址映射。 静态 ARP 条目不受 ARP 定期更新的影响。

参数

  • ip_ptr:指向以前所创建 IP 实例的指针。
  • ip_address:要映射的 IP 地址。
  • physical_msw:要映射的物理地址的高 16 位 (47-32)。
  • physical_lsw:要映射的物理地址的低 32 位 (31-0)。

返回值

  • NX_SUCCESS:(0x00) 创建 ARP 静态条目成功。
  • NX_NO_MORE_ENTRIES:(0x17) 在 ARP 缓存中没有更多的 ARP 条目可供使用。
  • NX_IP_ADDRESS_ERROR:(0x21) IP 地址无效。
  • NX_PTR_ERROR:(0x07) IP 指针无效。
  • NX_CALLER_ERROR (0x11) 此服务的调用方无效。
  • NX_NOT_ENABLED (0x14) 尚未启用此组件。
  • NX_INVALID_PARAMETERS:(0x4D) physical_msw 和 physical_lsw 均为 0。

允许调用自

初始化、线程

可以抢占

示例

/* Create a static ARP entry on the previously created IP
    Instance 0. */

status = nx_arp_static_entry_create(&ip_0, IP_ADDRESS(1,2,3,4),
    0x0, 0x1234);

/* If status is NX_SUCCESS, there is now a static mapping between
    the IP address of 1.2.3.4 and the physical hardware address of
    00:00:00:00:12:34. */

另请参阅

  • nx_arp_dynamic_entries_invalidate、nx_arp_dynamic_entry_set,
  • nx_arp_enable、nx_arp_gratuitous_send,
  • nx_arp_hardware_address_find、nx_arp_info_get,
  • nx_arp_ip_address_find、nx_arp_static_entries_delete,
  • nx_arp_static_entry_delete

nx_arp_static_entry_delete

从 ARP 缓存中删除静态的 IP 到硬件映射

原型

UINT nx_arp_static_entry_delete(
    NX_IP *ip_ptr,
    ULONG ip_address,
    ULONG physical_msw,
    ULONG physical_lsw);

说明

此服务针对指定的 IP 实例,在 ARP 缓存中查找并删除先前创建的静态 IP 到物理地址映射。

参数

  • ip_ptr:指向以前所创建 IP 实例的指针。
  • ip_address:以静态方式映射的 IP 地址。
  • physical_msw:以静态方式映射的物理地址的高 16 位 (47 - 32)。
  • physical_lsw:以静态方式映射的物理地址的低 32 位 (31 - 0)。

返回值

  • NX_SUCCESS:(0x00) 删除 ARP 静态条目成功。
  • NX_ENTRY_NOT_FOUND:(0x16) 在 ARP 缓存中找不到静态 ARP 条目。
  • NX_PTR_ERROR:(0x07) IP 指针无效。
  • NX_CALLER_ERROR (0x11) 此服务的调用方无效。
  • NX_NOT_ENABLED (0x14) 尚未启用此组件。
  • NX_IP_ADDRESS_ERROR:(0x21) IP 地址无效。
  • NX_INVALID_PARAMETERS:(0x4D) physical_msw 和 physical_lsw 均为 0。

允许调用自

线程数

可以抢占

示例

/* Delete a static ARP entry on the previously created IP
    instance ip_0. */
status = nx_arp_static_entry_delete(&ip_0, IP_ADDRESS(1,2,3,4),
    0x0, 0x1234);
/* If status is NX_SUCCESS, the previously created static ARP entry
    was successfully deleted. */

另请参阅

  • nx_arp_dynamic_entries_invalidate、nx_arp_dynamic_entry_set,
  • nx_arp_enable、nx_arp_gratuitous_send,
  • nx_arp_hardware_address_find、nx_arp_info_get,
  • nx_arp_ip_address_find、nx_arp_static_entries_delete,
  • nx_arp_static_entry_create

nx_icmp_enable

启用 Internet 控制消息协议 (ICMP)

原型

UINT nx_icmp_enable(NX_IP *ip_ptr);

说明

此服务针对指定的 IP 实例启用 ICMP 组件。 ICMP 组件负责处理 Internet 错误消息以及 ping 请求和回复。

参数

  • ip_ptr:指向以前所创建 IP 实例的指针。

返回值

  • NX_SUCCESS:(0x00) 启用 ICMP 成功。
  • NX_ALREADY_ENABLED:(0x15) ICMP 已启用。
  • NX_PTR_ERROR:(0x07) IP 指针无效。
  • NX_CALLER_ERROR (0x11) 此服务的调用方无效。

允许调用自

初始化、线程

可以抢占

示例

/* Enable ICMP on the previously created IP Instance ip_0. */
status = nx_icmp_enable(&ip_0);

/* If status is NX_SUCCESS, ICMP is enabled. */

另请参阅

  • nx_icmp_info_get、nx_icmp_ping

nx_icmp_info_get

检索 ICMP 活动的相关信息

原型

UINT nx_icmp_info_get(
    NX_IP *ip_ptr,
    ULONG *pings_sent,
    ULONG *ping_timeouts,
    ULONG *ping_threads_suspended,
    ULONG *ping_responses_received,
    ULONG *icmp_checksum_errors,
    ULONG *icmp_unhandled_messages);

说明

此服务检索所指定 IP 实例的 ICMP 活动相关信息。

如果目标指针为 NX_NULL,则不会将该特定信息返回给调用方

参数

  • ip_ptr:指向以前所创建 IP 实例的指针。
  • pings_sent:此指针指向已发送的 ping 总数的目标。
  • ping_timeouts:此指针指向 ping 超时总数的目标。
  • ping_threads_suspended:此指针指向在 ping 请求上挂起的线程总数的目标。
  • ping_responses_received:此指针指向已收到的 ping 响应总数的目标。
  • icmp_checksum_errors:此指针指向 ICMP 校验和错误总数的目标。
  • icmp_unhandled_messages:此指针指向未处理的 ICMP 消息总数的目标。

返回值

  • NX_SUCCESS:(0x00) 检索 ICMP 信息成功。
  • NX_CALLER_ERROR:(0x11) 此服务的调用方无效。
  • NX_PTR_ERROR:(0x07) IP 指针无效。
  • NX_NOT_ENABLED (0x14) 尚未启用此组件。

允许调用自

初始化、线程

可以抢占

示例

/* Retrieve ICMP information from previously created IP
    instance ip_0. */
status = nx_icmp_info_get(
    &ip_0, 
    &pings_sent, 
    &ping_timeouts,
    &ping_threads_suspended,
    &ping_responses_received,
    &icmp_checksum_errors,
    &icmp_unhandled_messages);

/* If status is NX_SUCCESS, ICMP information was retrieved. */

另请参阅

  • nx_icmp_enable、nx_icmp_ping

nx_icmp_ping

向指定的 IP 地址发送 ping 请求

原型

UINT nx_icmp_ping(
    NX_IP *ip_ptr,
    ULONG ip_address,
    CHAR *data, ULONG data_size,
    NX_PACKET **response_ptr,
    ULONG wait_option);

说明

此服务用于向指定的 IP 地址发送 ping 请求,并按指定的时间长度等待 ping 响应消息。 如果未收到响应,则会返回错误。 否则,将在 response_ptr 所指向的变量中返回完整的响应消息。

如果返回了 NX_SUCCESS,则应用程序负责在不再需要所收到的数据包后将其释放。

参数

  • ip_ptr:指向以前所创建 IP 实例的指针。

  • ip_address:要 ping 的 IP 地址,以主机字节顺序表示。 data:指向 ping 消息数据区域的指针。

  • data_size:ping 数据中的字节数

  • response_ptr:此指针指向将在其中返回 ping 响应消息的数据包指针。

  • wait_option:定义等待 ping 响应的时长。 等待选项的定义如下:

    • NX_NO_WAIT (0x00000000)
    • NX_WAIT_FOREVER (0xFFFFFFFF)
    • 以时钟周期为单位的超时值(0x00000001 到 0xFFFFFFFE)

返回值

  • NX_SUCCESS:(0x00) ping 成功。 响应消息指针已放入 response_ptr 所指向的变量中。
  • NX_NO_PACKET:(0x01) 无法分配 ping 请求数据包。
  • NX_OVERFLOW:(0x03) 指定的数据区超过此 IP 实例的默认数据包大小。
  • NX_NO_RESPONSE:(0x29) 所请求的 IP 未响应。
  • NX_WAIT_ABORTED:(0x1A) 已通过调用 tx_thread_wait_abort 中止所请求的挂起。
  • NX_IP_ADDRESS_ERROR:(0x21) IP 地址无效。
  • NX_PTR_ERROR:(0x07) IP 指针或响应指针无效。
  • NX_CALLER_ERROR (0x11) 此服务的调用方无效。
  • NX_NOT_ENABLED (0x14) 尚未启用此组件。

允许调用自

线程数

可以抢占

示例

/* Issue a ping to IP address 1.2.3.5 from the previously created IP
    Instance ip_0. */
status = nx_icmp_ping(&ip_0, IP_ADDRESS(1,2,3,5), "abcd", 4,
    &response_ptr, 10);

/* If status is NX_SUCCESS, a ping response was received from IP
    address 1.2.3.5 and the response packet is contained in the
    packet pointed to by response_ptr. It should have the same "abcd"
    four bytes of data. */

另请参阅

  • nx_icmp_enable、nx_icmp_info_get

nx_igmp_enable

启用 Internet 组管理协议 (IGMP)

原型

UINT nx_igmp_enable(NX_IP *ip_ptr);

说明

此服务在指定的 IP 实例上启用 IGMP 组件。 IGMP 组件负责提供对 IP 多播组管理操作的支持。

参数

  • ip_ptr:指向以前所创建 IP 实例的指针。

返回值

  • NX_SUCCESS:(0x00) 启用 IGMP 成功。
  • NX_PTR_ERROR:(0x07) IP 指针无效。
  • NX_CALLER_ERROR:(0x11) 此服务的调用方无效。
  • NX_ALREADY_ENABLED:(0x15) 此组件已启用。

允许调用自

初始化、线程

可以抢占

示例

/* Enable IGMP on the previously created IP Instance ip_0. */
status = nx_igmp_enable(&ip_0);

/* If status is NX_SUCCESS, IGMP is enabled. */

另请参阅

  • nx_igmp_info_get、nx_igmp_loopback_disable,
  • nx_igmp_loopback_enable、nx_igmp_multicast_interface_join,
  • nx_igmp_multicast_join、nx_igmp_multicast_leave

nx_igmp_info_get

检索 IGMP 活动的相关信息

原型

UINT nx_igmp_info_get(
    NX_IP *ip_ptr,
    ULONG *igmp_reports_sent,
    ULONG *igmp_queries_received,
    ULONG *igmp_checksum_errors,
    ULONG *current_groups_joined);

说明

此服务检索所指定 IP 实例的 IGMP 活动相关信息。

如果目标指针为 NX_NULL,则不会将该特定信息返回给调用方

参数

  • ip_ptr:指向以前所创建 IP 实例的指针。
  • igmp_reports_sent:此指针指向已发送的 ICMP 报告总数的目标。
  • igmp_queries_received:此指针指向多播路由器收到的查询总数的目标。
  • igmp_checksum_errors:此指针指向接收数据包中 IGMP 校验和错误总数的目标。
  • current_groups_joined:此指针指向通过此 IP 实例加入的当前数量的组的目标。

返回值

  • NX_SUCCESS:(0x00) 检索 IGMP 信息成功。
  • NX_PTR_ERROR:(0x07) IP 指针无效。
  • NX_CALLER_ERROR:(0x11) 此服务的调用方无效。
  • NX_NOT_ENABLED (0x14) 尚未启用此组件。

允许调用自

初始化、线程

可以抢占

示例

/* Retrieve IGMP information
    from previously created IP Instance ip_0. */
status = nx_igmp_info_get(
    &ip_0, 
    &igmp_reports_sent,
    &igmp_queries_received,
    &igmp_checksum_errors,
    &current_groups_joined);
/* If status is NX_SUCCESS, IGMP information was retrieved. */

另请参阅

  • nx_igmp_enable、nx_igmp_loopback_disable,
  • nx_igmp_loopback_enable、nx_igmp_multicast_interface_join,
  • nx_igmp_multicast_join、nx_igmp_multicast_leave

nx_igmp_loopback_disable

禁用 IGMP 环回

原型

UINT nx_igmp_loopback_disable(NX_IP *ip_ptr);

说明

此服务用于对加入的所有后续多播组禁用 IGMP 环回。

参数

  • ip_ptr:指向以前所创建 IP 实例的指针。

返回值

  • NX_SUCCESS:(0x00) 禁用 IGMP 环回成功。
  • NX_NOT_ENABLED:(0x14) IGMP 未启用。
  • NX_PTR_ERROR:(0x07) IP 指针无效。
  • NX_CALLER_ERROR:(0x11) 调用方不是线程或初始化。

允许调用自

初始化、线程

可以抢占

示例

/* Disable IGMP loopback for all subsequent multicast groups joined. */
status = nx_igmp_loopback_disable(&ip_0);

/* If status is NX_SUCCESS IGMP loopback is disabled. */

另请参阅

  • nx_igmp_enable、nx_igmp_info_get、nx_igmp_loopback_enable,
  • nx_igmp_multicast_interface_join、nx_igmp_multicast_join,
  • nx_igmp_multicast_leave

nx_igmp_loopback_enable

启用 IGMP 环回

原型

UINT nx_igmp_loopback_enable(NX_IP *ip_ptr);

说明

此服务用于对加入的所有后续多播组启用 IGMP 环回。

参数

  • ip_ptr:指向以前所创建 IP 实例的指针。

返回值

  • NX_SUCCESS:(0x00) 禁用 IGMP 环回成功。
  • NX_NOT_ENABLED:(0x14) IGMP 未启用。
  • NX_PTR_ERROR:(0x07) IP 指针无效。
  • NX_CALLER_ERROR:(0x11) 调用方不是线程或初始化。

允许调用自

初始化、线程

可以抢占

示例

/* Enable IGMP loopback for all subsequent multicast groups joined. */
status = nx_igmp_loopback_enable(&ip_0);

/* If status is NX_SUCCESS IGMP loopback is enabled. */

另请参阅

  • nx_igmp_enable、nx_igmp_info_get、nx_igmp_loopback_disable,
  • nx_igmp_multicast_interface_join、nx_igmp_multicast_join,
  • nx_igmp_multicast_leave

nx_igmp_multicast_interface_join

让 IP 实例通过接口加入指定的多播组

原型

UINT nx_igmp_multicast_interface_join(
    NX_IP *ip_ptr,
    ULONG group_address,
    UINT interface_index);

说明

此服务让 IP 实例通过指定的网络接口加入指定的多播组。 系统会维护内部计数器,以跟踪加入同一个组的次数。 加入多播组之后,IGMP 组件就会允许通过指定的网络接口接收具有该组地址的 IP 数据包,并且还会向路由器报告该 IP 是该多播组的成员。 IGMP 成员身份加入、报告和退出消息也会通过指定的网络接口发送。

参数

  • ip_ptr:指向以前所创建 IP 实例的指针。
  • group_address:要加入的 D 类 IP 多播组地址,以主机字节顺序表示。
  • interface_index:附加到 NetX 实例的接口的索引。

返回值

  • NX_SUCCESS:(0x00) 加入多播组成功。
  • NX_NO_MORE_ENTRIES:(0x17) 无法再加入更多的多播组,已超过最大数目。
  • NX_PTR_ERROR:(0x07) IP 指针无效。
  • NX_INVALID_INTERFACE:(0x4C) 设备索引指向无效的网络接口。
  • NX_IP_ADDRESS_ERROR:(0x21) 提供的多播组地址不是有效的 D 类地址。
  • NX_CALLER_ERROR:(0x11) 此服务的调用方无效。
  • NX_NOT_ENABLED:(0x14) IP 多播支持未启用。

允许调用自

线程数

可以抢占

示例

/* Previously created IP Instance joins the multicast group
    244.0.0.200, via the interface at index 1 in the IP interface list. */
#define INTERFACE_INDEX 1
status = nx_igmp_multicast_interface_join
    (&ip, IP_ADDRESS(244,0,0,200),
    INTERFACE_INDEX);

/* If status is NX_SUCCESS, the IP instance has successfully joined
    the multicast group. */

另请参阅

  • nx_igmp_enable、nx_igmp_info_get、nx_igmp_loopback_disable,
  • nx_igmp_loopback_enable、nx_igmp_multicast_join,
  • nx_igmp_multicast_leave

nx_igmp_multicast_join

让 IP 实例加入指定的多播组

原型

UINT nx_igmp_multicast_join(
    NX_IP *ip_ptr, 
    ULONG group_address);

说明

此服务用于让 IP 实例加入指定的多播组。 系统会维护内部计数器,以跟踪加入同一个组的次数。 如果这是网络上的第一个表明主机打算加入该组的加入请求,则会指示驱动程序发送 IGMP 报告。 加入之后,IGMP 组件就会允许接收具有该组地址的 IP 数据包,并向路由器报告该 IP 是该多播组的成员。

注意

若要在非主要设备上加入多播组,请使用 nx_igmp_multicast_interface_join 服务

参数

  • ip_ptr:指向以前所创建 IP 实例的指针。
  • group_address:要加入的 D 类 IP 多播组地址。

返回值

  • NX_SUCCESS:(0x00) 加入多播组成功。
  • NX_NO_MORE_ENTRIES:(0x17) 无法再加入更多的多播组,已超过最大数目。
  • NX_INVALID_INTERFACE:(0x4C) 设备索引指向无效的网络接口。
  • NX_IP_ADDRESS_ERROR:(0x21) IP 组地址无效。
  • NX_PTR_ERROR:(0x07) IP 指针无效。
  • NX_CALLER_ERROR:(0x11) 此服务的调用方无效。
  • NX_NOT_ENABLED (0x14) 尚未启用此组件。

允许调用自

线程数

可以抢占

示例

/* Previously created IP Instance ip_0 joins the multicast group
    224.0.0.200. */
status = nx_igmp_multicast_join(&ip_0, IP_ADDRESS(224,0,0,200));

/* If status is NX_SUCCESS, this IP instance has successfully
    joined the multicast group 224.0.0.200. */

另请参阅

  • nx_igmp_enable、nx_igmp_info_get、nx_igmp_loopback_disable,
  • nx_igmp_loopback_enable、nx_igmp_multicast_interface_join,
  • nx_igmp_multicast_leave

nx_igmp_multicast_leave

让 IP 实例退出指定的多播组

原型

UINT nx_igmp_multicast_leave(
    NX_IP *ip_ptr, 
    ULONG group_address);

说明

如果退出请求数与加入请求数相匹配,该服务会使 IP 实例退出指定的多播组。 否则,只是将内部加入计数减小。

参数

  • ip_ptr:指向以前所创建 IP 实例的指针。
  • group_address:要退出的多播组。

返回值

  • NX_SUCCESS:(0x00) 加入多播组成功。
  • NX_ENTRY_NOT_FOUND:(0x16) 找不到以前的加入请求。
  • NX_INVALID_INTERFACE:(0x4C) 设备索引指向无效的网络接口。
  • NX_IP_ADDRESS_ERROR:(0x21) IP 组地址无效。
  • NX_PTR_ERROR:(0x07) IP 指针无效。
  • NX_CALLER_ERROR:(0x11) 此服务的调用方无效。
  • NX_NOT_ENABLED (0x14) 尚未启用此组件。

允许调用自

线程数

可以抢占

示例

/* Cause IP instance to leave the multicast group 224.0.0.200. */
status = nx_igmp_multicast_leave(&ip_0, IP_ADDRESS(224,0,0,200);

/* If status is NX_SUCCESS, this IP instance has successfully left
    the multicast group 224.0.0.200. */

另请参阅

  • nx_igmp_enable、nx_igmp_info_get、nx_igmp_loopback_disable,
  • nx_igmp_loopback_enable、nx_igmp_multicast_interface_join,
  • nx_igmp_multicast_join

nx_ip_address_change_notifiy

在 IP 地址更改时通知应用程序

原型

UINT nx_ip_address_change_notify(
    NX_IP *ip_ptr,
    VOID(*change_notify)(NX_IP *,VOID *),
    VOID *additional_info);

说明

此服务注册一个应用程序通知函数,每当 IP 地址更改时,都会调用该函数。

参数

  • ip_ptr:指向以前所创建 IP 实例的指针。
  • change_notify:指向 IP 更改通知函数的指针。 如果此参数为 NX_NULL,则会禁用 IP 地址更改通知。
  • additional_info:指向可选附加信息的指针,此信息也会在 IP 地址更改时提供给通知函数。

返回值

  • * NX_SUCCESS:(0x00) IP 地址更改通知成功
  • NX_PTR_ERROR:(0x07) IP 指针无效。
  • NX_CALLER_ERROR (0x11) 此服务的调用方无效。

允许调用自

初始化、线程

可以抢占

示例

/* Register the function "my_ip_changed" to be called whenever
the IP address is changed. */
status = nx_ip_address_change_notify(&ip_0, my_ip_changed, NX_NULL);

/* If status is NX_SUCCESS, the "my_ip_changed" function will be
    called whenever the IP address changes. */

另请参阅

  • nx_ip_address_get、nx_ip_address_set、nx_ip_create、nx_ip_delete,
  • nx_ip_driver_direct_command、nx_ip_driver_interface_direct_command,
  • nx_ip_forwarding_disable、nx_ip_forwarding_enable,
  • nx_ip_fragment_disable、nx_ip_fragment_enable、nx_ip_info_get,
  • nx_ip_status_check、nx_system_initialize

nx_ip_address_get

检索 IP 地址和网络掩码

原型

UINT nx_ip_address_get(
    NX_IP *ip_ptr,
    ULONG *ip_address,
    ULONG *network_mask);

说明

此服务检索主要网络接口的 IP 地址及其子网掩码。

若要获取辅助设备的信息,请使用 nx_ip_interface_address_get 服务。

参数

  • ip_ptr:指向以前所创建 IP 实例的指针。
  • ip_address:指向 IP 地址目标的指针。
  • network_mask:指向网络掩码目标的指针。

返回值

  • NX_SUCCESS:(0x00) 获取 IP 地址成功。
  • NX_PTR_ERROR:(0x07) IP 或返回变量指针无效。
  • NX_CALLER_ERROR:(0x11) 此服务的调用方无效。

允许调用自

初始化、线程

可以抢占

示例

/* Get the IP address and network mask from the previously created
    IP Instance ip_0. */
status = nx_ip_address_get(&ip_0,
    &ip_address, &network_mask);

/* If status is NX_SUCCESS, the variables ip_address and
    network_mask contain the IP and network mask respectively. */

另请参阅

  • nx_ip_address_change_notify、nx_ip_address_set、nx_ip_create,
  • nx_ip_delete、nx_ip_driver_direct_command,
  • nx_ip_driver_interface_direct_command、nx_ip_forwarding_disable,
  • nx_ip_forwarding_enable、nx_ip_fragment_disable,
  • nx_ip_fragment_enable、nx_ip_info_get、nx_ip_status_check,
  • nx_system_initialize

nx_ip_address_set

设置 IP 地址和网络掩码

原型

UINT nx_ip_address_set(
    NX_IP *ip_ptr,
    ULONG ip_address,
    ULONG network_mask);

说明

此服务可设置主要网络接口的 IP 地址和网络掩码。

若要设置辅助设备的 IP 地址和网络掩码,请使用 nx_ip_interface_address_set 服务

参数

  • ip_ptr:指向以前所创建 IP 实例的指针。
  • ip_address:新 IP 地址。
  • network_mask:新网络掩码。

返回值

  • NX_SUCCESS:(0x00) 设置 IP 地址成功。
  • NX_IP_ADDRESS_ERROR:(0x21) IP 地址无效。
  • NX_PTR_ERROR:(0x07) IP 指针无效。
  • NX_CALLER_ERROR (0x11) 此服务的调用方无效。

允许调用自

初始化、线程

可以抢占

示例

/* Set the IP address and network mask to 1.2.3.4 and 0xFFFFFF00
    for the previously created IP Instance ip_0. */
status = nx_ip_address_set(&ip_0, IP_ADDRESS(1,2,3,4), 0xFFFFFF00UL);

/* If status is NX_SUCCESS, the IP instance now has an IP address
    of 1.2.3.4 and a network mask of 0xFFFFFF00. */

另请参阅

  • nx_ip_address_change_notify、nx_ip_address_get、nx_ip_create,
  • nx_ip_delete、nx_ip_driver_direct_command,
  • nx_ip_driver_interface_direct_command、nx_ip_forwarding_disable,
  • nx_ip_forwarding_enable、nx_ip_fragment_disable,
  • nx_ip_fragment_enable、nx_ip_info_get、nx_ip_status_check,
  • nx_system_initialize

nx_ip_create

创建 IP 实例

原型

UINT nx_ip_create(
    NX_IP *ip_ptr, 
    CHAR *name, 
    ULONG ip_address,
    ULONG network_mask, 
    NX_PACKET_POOL *default_pool,
    VOID (*ip_network_driver)(NX_IP_DRIVER *),
    VOID *memory_ptr, 
    ULONG memory_size,
    UINT priority);

说明

此服务使用用户提供的 IP 地址和网络驱动程序创建 IP 实例。 此外,应用程序必须为 IP 实例提供先前创建的数据包池,以用于内部数据包分配。 请注意,直到此 IP 的线程执行之后,才会调用提供的应用程序网络驱动程序。

参数

  • ip_ptr:指向用于创建新 IP 实例的控制块的指针。
  • name:此新 IP 实例的名称。
  • ip_address:此新 IP 实例的 IP 地址。
  • network_mask:描述 IP 地址网络部分的掩码,用于实现子网和超网。
  • default_pool:指向先前创建的 NetX 数据包池的控制块的指针。
  • ip_network_driver:用户提供的网络驱动程序,用于发送和接收 IP 数据包。
  • memory_ptr:指向 IP 帮助程序线程堆栈区域的内存区域的指针。
  • memory_size:IP 帮助程序线程堆栈的内存区域中的字节数。
  • priority:IP 帮助程序线程的优先级。

返回值

  • NX_SUCCESS (0x00) 成功创建 IP 实例。
  • NX_NOT_IMPLEMENTED (0x4A) 未正确配置 NetX 库。
  • NX_PTR_ERROR (0x07) IP、网络驱动程序函数指针、数据包池或内存指针无效。
  • NX_SIZE_ERROR:(0x09) 提供的堆栈大小太小。
  • NX_CALLER_ERROR (0x11) 此服务的调用方无效。
  • NX_IP_ADDRESS_ERROR:(0x21) 提供的 IP 地址无效。
  • NX_OPTION_ERROR:(0x21) 提供的 IP 线程优先级无效。

允许调用自

初始化、线程

可以抢占

示例

/* Create an IP instance with an IP address of 1.2.3.4 and a network
    mask of 0xFFFFFF00UL. The "ethernet_driver" specifies the entry
    point of the application specific network driver and the
    "stack_memory_ptr" specifies the start of a 1024 byte memory
    area that is used for this IP instance’s helper thread.  */
status = nx_ip_create(
    &ip_0, 
    "NetX IP Instance ip_0",
    IP_ADDRESS(1, 2, 3, 4),
    0xFFFFFF00UL, &pool_0, 
    ethernet_driver,
    stack_memory_ptr, 
    1024, 
    1);

/* If status is NX_SUCCESS, the IP instance has been created. */

另请参阅

  • nx_ip_address_change_notify、nx_ip_address_get、nx_ip_address_set,
  • nx_ip_delete、nx_ip_driver_direct_command,
  • nx_ip_driver_interface_direct_command、nx_ip_forwarding_disable,
  • nx_ip_forwarding_enable、nx_ip_fragment_disable,
  • nx_ip_fragment_enable、nx_ip_info_get、nx_ip_status_check,
  • nx_system_initialize

nx_ip_delete

删除先前创建的 IP 实例

原型

UINT nx_ip_delete(NX_IP *ip_ptr);

说明

此服务用于删除先前创建的 IP 实例,并释放该 IP 实例所拥有的所有系统资源。

参数

  • ip_ptr:指向以前所创建 IP 实例的指针。

返回值

  • NX_SUCCESS:(0x00) 删除 IP 成功。
  • NX_SOCKETS_BOUND:(0x28) 此 IP 实例仍有与其绑定的 UDP 或 TCP 套接字。 必须先取消绑定并删除所有套接字,然后才能删除该 IP 实例之前。
  • NX_PTR_ERROR:(0x07) IP 指针无效。
  • NX_CALLER_ERROR:(0x11) 此服务的调用方无效。

允许调用自

线程数

可以抢占

示例

/* Delete a previously created IP instance. */
status = nx_ip_delete(&ip_0);

/* If status is NX_SUCCESS, the IP instance has been deleted. */

另请参阅

  • nx_ip_address_change_notify、nx_ip_address_get、nx_ip_address_set,
  • nx_ip_create、nx_ip_driver_direct_command,
  • nx_ip_driver_interface_direct_command、nx_ip_forwarding_disable,
  • nx_ip_forwarding_enable、nx_ip_fragment_disable,
  • nx_ip_fragment_enable、nx_ip_info_get、nx_ip_status_check,
  • nx_system_initialize

nx_ip_driver_direct_command

向网络驱动程序发送命令

原型

UINT nx_ip_driver_direct_command(
    NX_IP *ip_ptr,
    UINT command,
    ULONG *return_value_ptr);

说明

此服务提供在 nx_ip_create 调用期间指定的应用程序主网络接口驱动程序的直接接口。

可以使用应用程序特定的命令,但前提是其数字值大于或等于 NX_LINK_USER_COMMAND。

若要针对辅助设备发出命令,请使用 nx_ip_driver_interface_direct_command 服务。

参数

  • ip_ptr:指向以前所创建 IP 实例的指针。
  • command:数字命令代码。 标准命令定义如下:
    • NX_LINK_GET_STATUS (10)
    • NX_LINK_GET_SPEED (11)
    • NX_LINK_GET_DUPLEX_TYPE (12)
    • NX_LINK_GET_ERROR_COUNT (13)
    • NX_LINK_GET_RX_COUNT (14)
    • NX_LINK_GET_TX_COUNT (15)
    • NX_LINK_GET_ALLOC_ERRORS (16)
    • NX_LINK_USER_COMMAND (50)
  • return_value_ptr:指向调用方中的返回变量的指针。

返回值

  • NX_SUCCESS:(0x00) 网络驱动程序直接命令成功。
  • NX_UNHANDLED_COMMAND:(0x44) 网络驱动程序命令未得到处理或未实现。
  • NX_PTR_ERROR:(0x07) IP 或返回值指针无效。
  • NX_CALLER_ERROR:(0x11) 此服务的调用方无效。
  • NX_INVALID_INTERFACE:(0x4C) 接口索引无效。

允许调用自

线程数

可以抢占

示例

/* Make a direct call to the application-specific network driver
    for the previously created IP instance. For this example, the
    network driver is interrogated for the link status. */
status = nx_ip_driver_direct_command(
    &ip_0, NX_LINK_GET_STATUS,
    &link_status);

/* If status is NX_SUCCESS, the link_status variable contains a
    NX_TRUE or NX_FALSE value representing the status of the
    physical link. */

另请参阅

  • nx_ip_address_change_notify、nx_ip_address_get、nx_ip_address_set,
  • nx_ip_create、nx_ip_delete、nx_ip_driver_interface_direct_command,
  • nx_ip_forwarding_disable、nx_ip_forwarding_enable,
  • nx_ip_fragment_disable、nx_ip_fragment_enable、nx_ip_info_get,
  • nx_ip_status_check、nx_system_initialize

nx_ip_driver_interface_direct_command

向网络驱动程序发送命令

原型

UINT nx_ip_driver_interface_direct_command(
    NX_IP *ip_ptr,
    UINT command,
    UINT interface_index,
    ULONG *return_value_ptr);

说明

此服务用于向 IP 实例中应用程序的网络设备驱动程序发出直接命令。 可以使用应用程序特定的命令,但前提是其数字值大于或等于 NX_LINK_USER_COMMAND。

参数

  • ip_ptr:指向以前所创建 IP 实例的指针。
  • command:数字命令代码。 标准命令定义如下:
    • NX_LINK_GET_STATUS (10)
    • NX_LINK_GET_SPEED (11)
    • NX_LINK_GET_DUPLEX_TYPE (12)
    • NX_LINK_GET_ERROR_COUNT (13)
    • NX_LINK_GET_RX_COUNT (14)
    • NX_LINK_GET_TX_COUNT (15)
    • NX_LINK_GET_ALLOC_ERRORS (16)
    • NX_LINK_USER_COMMAND (50)
  • interface_index:应将该命令发送到的网络接口的索引。
  • return_value_ptr:指向调用方中的返回变量的指针。

返回值

  • NX_SUCCESS:(0x00) 网络驱动程序直接命令成功。
  • NX_UNHANDLED_COMMAND:(0x44) 网络驱动程序命令未得到处理或未实现。
  • NX_INVALID_INTERFACE:(0x4C) 接口索引无效
  • NX_PTR_ERROR:(0x07) IP 或返回值指针无效。
  • NX_CALLER_ERROR (0x11) 此服务的调用方无效。

允许调用自

线程数

可以抢占

示例

/* Make a direct call to the application-specific network driver
    for the previously created IP instance. For this example, the
    network driver is interrogated for the link status. */

/* Set the interface index to the primary device. */
UINT interface_index = 0;
    status = nx_ip_driver_interface_direct_command(&ip_0,
    NX_LINK_GET_STATUS,
    interface_index,
    &link_status);
/* If status is NX_SUCCESS, the link_status variable contains a
    NX_TRUE or NX_FALSE value representing the status of the
    physical link. */

另请参阅

  • nx_ip_address_change_notify、nx_ip_address_get、nx_ip_address_set,
  • nx_ip_create、nx_ip_delete、nx_ip_driver_direct_command,
  • nx_ip_forwarding_disable、nx_ip_forwarding_enable,
  • nx_ip_fragment_disable、nx_ip_fragment_enable、nx_ip_info_get,
  • nx_ip_status_check、nx_system_initialize

nx_ip_forwarding_disable

禁用 IP 数据包转发

原型

UINT nx_ip_forwarding_disable(NX_IP *ip_ptr);

说明

此服务用于在 NetX IP 组件内禁止转发 IP 数据包。 创建 IP 任务时,会自动禁用此服务。

参数

  • ip_ptr:指向以前所创建 IP 实例的指针。

返回值

  • NX_SUCCESS:(0x00) 禁用 IP 转发成功。
  • NX_PTR_ERROR:(0x07) IP 指针无效。
  • NX_CALLER_ERROR:(0x11) 此服务的调用方无效。

允许调用自

初始化、线程、计时器

可以抢占

示例

/* Disable IP forwarding on this IP instance. */
status = nx_ip_forwarding_disable(&ip_0);

/* If status is NX_SUCCESS, IP forwarding has been disabled on the
    previously created IP instance. */

另请参阅

  • nx_ip_address_change_notify、nx_ip_address_get、nx_ip_address_set,
  • nx_ip_create、nx_ip_delete、nx_ip_driver_direct_command,
  • nx_ip_driver_interface_direct_command、nx_ip_forwarding_enable,
  • nx_ip_fragment_disable、nx_ip_fragment_enable、nx_ip_info_get,
  • nx_ip_status_check、nx_system_initialize

nx_ip_forwarding_enable

启用 IP 数据包转发

原型

UINT nx_ip_forwarding_enable(NX_IP *ip_ptr);

说明

此服务用于在 NetX IP 组件内允许转发 IP 数据包。 创建 IP 任务时,会自动禁用此服务。

参数

  • ip_ptr:指向以前所创建 IP 实例的指针。

返回值

  • NX_SUCCESS:(0x00) 启用 IP 转发成功。
  • NX_PTR_ERROR:(0x07) IP 指针无效。
  • NX_CALLER_ERROR:(0x11) 此服务的调用方无效。

允许调用自

初始化、线程、计时器

可以抢占

示例

/* Enable IP forwarding on this IP instance. */
status = nx_ip_forwarding_enable(&ip_0);

/* If status is NX_SUCCESS, IP forwarding has been enabled on the
    previously created IP instance. */

另请参阅

  • nx_ip_address_change_notify、nx_ip_address_get、nx_ip_address_set,
  • nx_ip_create、nx_ip_delete、nx_ip_driver_direct_command,
  • nx_ip_driver_interface_direct_command、nx_ip_forwarding_disable,
  • nx_ip_fragment_disable、nx_ip_fragment_enable、nx_ip_info_get,
  • nx_ip_status_check、nx_system_initialize

nx_ip_fragment_disable

禁用 IP 数据包分段

原型

UINT nx_ip_fragment_disable(NX_IP *ip_ptr);

说明

此服务可禁用 IP 数据包分段和重组功能。 对于正在等待重组的数据包,此服务会将其释放。 创建 IP 任务时,此服务会自动禁用。

参数

  • ip_ptr:指向以前所创建 IP 实例的指针。

返回值

  • NX_SUCCESS:(0x00) 禁用 IP 分段成功。
  • NX_PTR_ERROR:(0x07) IP 指针无效。
  • NX_CALLER_ERROR (0x11) 此服务的调用方无效。
  • NX_NOT_ENABLED:(0x14) IP 分段在该 IP 实例上未启用。

允许调用自

初始化、线程

可以抢占

示例

/* Disable IP fragmenting on this IP instance. */
status = nx_ip_fragment_disable(&ip_0);

/* If status is NX_SUCCESS, disables IP fragmenting on the
    previously created IP instance. */

另请参阅

  • nx_ip_address_change_notify、nx_ip_address_get、nx_ip_address_set,
  • nx_ip_create、nx_ip_delete、nx_ip_driver_direct_command,
  • nx_ip_driver_interface_direct_command、nx_ip_forwarding_disable,
  • nx_ip_forwarding_enable、nx_ip_fragment_enable、nx_ip_info_get,
  • nx_ip_status_check、nx_system_initialize

nx_ip_fragment_enable

启用 IP 数据包分段

原型

UINT nx_ip_fragment_enable(NX_IP *ip_ptr);

说明

此服务可启用 IP 数据包分段和重组功能。 创建 IP 任务时,会自动禁用此服务。

参数

  • ip_ptr:指向以前所创建 IP 实例的指针。

返回值

  • NX_SUCCESS:(0x00) 启用 IP 分段成功。
  • NX_PTR_ERROR:(0x07) IP 指针无效。
  • NX_CALLER_ERROR (0x11) 此服务的调用方无效。
  • NX_NOT_ENABLED (0x14) IP 分段功能未编译到 NetX 中。

允许调用自

初始化、线程

可以抢占

示例

/* Enable IP fragmenting on this IP instance. */
status = nx_ip_fragment_enable(&ip_0);

/* If status is NX_SUCCESS, IP fragmenting has been enabled on the
    previously created IP instance. */

另请参阅

  • nx_ip_address_change_notify、nx_ip_address_get、nx_ip_address_set,
  • nx_ip_create、nx_ip_delete、nx_ip_driver_direct_command,
  • nx_ip_driver_interface_direct_command、nx_ip_forwarding_disable,
  • nx_ip_forwarding_enable、nx_ip_fragment_disable、nx_ip_info_get,
  • nx_ip_status_check、nx_system_initialize

nx_ip_gateway_address_set

设置网关 IP 地址

原型

UINT nx_ip_gateway_address_set(
    NX_IP *ip_ptr, 
    ULONG ip_address);

说明

此服务用于设置 IP 网关 IP 地址。 所有网络出站流量都会路由到该网关进行传输。 该网关必须可通过其中一个网络接口直接访问。

参数

  • ip_ptr:指向以前所创建 IP 实例的指针。
  • ip_address:网关的 IP 地址。

返回值

  • NX_SUCCESS:(0x00) 设置网关 IP 地址成功。
  • NX_PTR_ERROR:(0x07) IP 实例指针无效。
  • NX_IP_ADDRESS_ERROR:(0x21) IP 地址无效。
  • NX_CALLER_ERROR:(0x11) 此服务的调用方无效。

允许调用自

初始化、线程

可以抢占

示例

/* Setup the Gateway address for previously created IP
    Instance ip_0. */
status = nx_ip_gateway_address_set(&ip_0, IP_ADDRESS(1,2,3,99));

/* If status is NX_SUCCESS, all out-of-network send requests are
    routed to 1.2.3.99. */

另请参阅

  • nx_ip_info_get、nx_ip_static_route_add、nx_ip_static_route_delete

nx_ip_info_get

检索 IP 活动的相关信息

原型

UINT nx_ip_info_get(
    NX_IP *ip_ptr,
    ULONG *ip_total_packets_sent,
    ULONG *ip_total_bytes_sent,
    ULONG *ip_total_packets_received,
    ULONG *ip_total_bytes_received,
    ULONG *ip_invalid_packets,
    ULONG *ip_receive_packets_dropped,
    ULONG *ip_receive_checksum_errors,
    ULONG *ip_send_packets_dropped,
    ULONG *ip_total_fragments_sent,
    ULONG *ip_total_fragments_received);

说明

此服务检索所指定 IP 实例的 IP 活动相关信息。

如果目标指针为 NX_NULL,则不会将该特定信息返回给调用方

参数

  • ip_ptr:指向以前所创建 IP 实例的指针。
  • ip_total_packets_sent:此指针指向已发送的 IP 数据包总数的目标。
  • ip_total_bytes_sent:此指针指向已发送的总字节数的目标。
  • ip_total_packets_received:此指针指向 IP 接收数据包总数的目标。
  • ip_total_bytes_received:此指针指向已接收的 IP 总字节数的目标。
  • ip_invalid_packets:此指针指向无效 IP 数据包总数的目标。
  • ip_receive_packets_dropped:此指针指向已删除的接收数据包总数的目标。
  • ip_receive_checksum_errors:此指针指向接收数据包中校验和错误总数的目标。
  • ip_send_packets_dropped:此指针指向已删除的发送数据包总数的目标。
  • ip_total_fragments_sent:此指针指向已发送的片段总数的目标。
  • ip_total_fragments_received:此指针指向已接收的片段总数的目标。

返回值

  • NX_SUCCESS:(0x00) 检索 IP 信息成功。
  • NX_CALLER_ERROR:(0x11) 此服务的调用方无效。
  • NX_PTR_ERROR:(0x07) IP 指针无效。

允许调用自

初始化、线程

可以抢占

示例

/* Retrieve IP information from previously created IP
Instance 0. */
status = nx_ip_info_get(&ip_0,
    &ip_total_packets_sent,
    &ip_total_bytes_sent,
    &ip_total_packets_received,
    &ip_total_bytes_received,
    &ip_invalid_packets,
    &ip_receive_packets_dropped,
    &ip_receive_checksum_errors,
    &ip_send_packets_dropped,
    &ip_total_fragments_sent,
    &ip_total_fragments_received);

/* If status is NX_SUCCESS, IP information was retrieved. */

另请参阅

  • nx_ip_address_change_notify、nx_ip_address_get、nx_ip_address_set,
  • nx_ip_create、nx_ip_delete、nx_ip_driver_direct_command,
  • nx_ip_driver_interface_direct_command、nx_ip_forwarding_disable,
  • nx_ip_forwarding_enable、nx_ip_fragment_disable,
  • nx_ip_fragment_enable、nx_ip_status_check、nx_system_initialize

nx_ip_interface_address_get

检索接口 IP 地址

原型

UINT nx_ip_interface_address_get (
    NX_IP *ip_ptr,
    UINT interface_index,
    ULONG *ip_address,
    ULONG *network_mask);

说明

此服务可检索指定网络接口的 IP 地址。

如果指定的设备不是主要设备,则必须预先附加到该 IP 实例。

参数

  • ip_ptr:指向以前所创建 IP 实例的指针。
  • interface_index:接口索引,与附加到 IP 实例的网络接口的索引值相同。
  • ip_address:指向设备接口 IP 地址的目标的指针。
  • network_mask:指向设备接口网络掩码的目标的指针。

返回值

  • NX_SUCCESS:(0x00) 获取 IP 地址成功。
  • NX_INVALID_INTERFACE:(0x4C) 指定的网络接口无效。
  • NX_CALLER_ERROR:(0x11) 此服务的调用方无效。
  • NX_PTR_ERROR:(0x07) IP 指针无效。

允许调用自

初始化、线程

可以抢占

示例

#define INTERFACE_INDEX 1
/* Get device IP address and network mask for the specified
    interface index 1 in IP instance list of interfaces). */
status = nx_ip_interface_address_get(ip_ptr,INTERFACE_INDEX,
    &ip_address, &network_mask);

/* If status is NX_SUCCESS the interface address was successfully
    retrieved. */

另请参阅

  • nx_ip_interface_address_set、nx_ip_interface_attach,
  • nx_ip_interface_info_get、nx_ip_interface_status_check,
  • nx_ip_link_status_change_notify_set

nx_ip_interface_address_set

设置接口 IP 地址和网络掩码

原型

UINT nx_ip_interface_address_set(
    NX_IP *ip_ptr,
    UINT interface_index,
    ULONG ip_address,
    ULONG network_mask);

说明

此服务可为指定的 IP 接口设置 IP 地址和网络掩码。

指定的接口必须预先附加到该 IP 实例。

参数

  • ip_ptr:指向以前所创建 IP 实例的指针。
  • interface_index:附加到 NetX 实例的接口的索引。
  • ip_address:新的网络接口 IP 地址。
  • network_mask:新的接口网络掩码。

返回值

  • NX_SUCCESS:(0x00) 设置 IP 地址成功。
  • NX_INVALID_INTERFACE:(0x4C) 指定的网络接口无效。
  • NX_CALLER_ERROR (0x11) 此服务的调用方无效。
  • NX_PTR_ERROR:(0x07) 指针无效。
  • NX_IP_ADDRESS_ERROR:(0x21) IP 地址无效

允许调用自

初始化、线程

可以抢占

示例

#define INTERFACE_INDEX 1
/* Set device IP address and network mask for the specified
    interface index 1 in IP instance list of interfaces). */
status = nx_ip_interface_address_set(ip_ptr, INTERFACE_INDEX,
    ip_address, network_mask);

/* If status is NX_SUCCESS the interface IP address and mask was
successfully set. */

另请参阅

  • nx_ip_interface_address_get、nx_ip_interface_attach,
  • nx_ip_interface_info_get、nx_ip_interface_status_check,
  • nx_ip_link_status_change_notify_set

nx_ip_interface_attach

将网络接口附加到 IP 实例

原型

UINT nx_ip_interface_attach(
    NX_IP *ip_ptr, 
    CHAR *interface_name,
    ULONG ip_address,
    ULONG network_mask,
    VOID(*ip_link_driver)
    (struct NX_IP_DRIVER_STRUCT *));

说明

此服务用于向 IP 接口添加物理网络接口。 请注意,IP 实例是使用主接口创建的,因此每个额外的接口都是主接口的辅助接口。 附加到 IP 实例的网络接口总数(包括主接口)不得超过 NX_MAX_PHYSICAL_INTERFACES。

如果 IP 线程尚未运行,则辅助接口会在初始化所有物理接口的 IP 线程启动过程中进行初始化。

如果 IP 线程未在运行,则辅助接口会在 nx_ip_interface_attach 服务中进行初始化

ip_ptr 必须指向有效的 NetX IP 结构。

必须根据 IP 实例的网络接口数配置 NX_MAX_PHYSICAL_INTERFACES。 默认值为一。

参数

  • ip_ptr:指向以前所创建 IP 实例的指针。
  • interface_name:指向接口名称字符串的指针。
  • ip_address:设备 IP 地址,以主机字节顺序表示。
  • network_mask:设备网络掩码,以主机字节顺序表示。
  • ip_link_driver:接口的以太网驱动程序。

返回值

  • NX_SUCCESS:(0x00) 条目已添加到静态路由表中。
  • NX_NO_MORE_ENTRIES (0x17) 已超过最大接口数
  • NX_MAX_PHYSICAL_INTERFACES。
  • NX_DUPLICATED_ENTRY (0x52) 提供的 IP 地址已在该 IP 实例上使用。
  • NX_CALLER_ERROR:(0x11) 此服务的调用方无效。
  • NX_PTR_ERROR:(0x07) 指针输入无效。
  • NX_IP_ADDRESS_ERROR:(0x21) IP 地址输入无效。

允许调用自

初始化、线程

可以抢占

示例

/* Attach secondary device for device IP address 192.168.1.68 with
    the specified Ethernet driver. */
status = nx_ip_interface_attach(ip_ptr, “secondary_port”,
    IP_ADDRESS(192,168,1,68),
    0xFFFFFF00UL,
    nx_etherDriver);
/* If status is NX_SUCCESS the interface was successfully added to
    the IP instance interface table. */

另请参阅

  • nx_ip_interface_address_get、nx_ip_interface_address_set,
  • nx_ip_interface_info_get、nx_ip_interface_status_check,
  • nx_ip_link_status_change_notify_set

nx_ip_interface_info_get

检索网络接口参数

原型

UINT nx_ip_interface_info_get(
    NX_IP *ip_ptr,
    UINT interface_index,
    CHAR **interface_name,
    ULONG *ip_address,
    ULONG *network_mask,
    ULONG *mtu_size,
    ULONG *physical_address_msw,
    ULONG *physical_address_lsw);

说明

此服务用于检索所指定网络接口的网络参数相关信息。 所有数据都会按主机字节顺序进行检索。

ip_ptr 必须指向有效的 NetX IP 结构。 如果指定的接口不是主要接口,则必须将其预先附加到该 IP 实例。

参数

  • ip_ptr:指向以前所创建 IP 实例的指针。
  • interface_index:指定网络接口的索引。
  • interface_name:指向缓冲区的指针,该缓冲区中包含网络接口名称。
  • ip_address:指向接口 IP 地址目标的指针。
  • network_mask:指向网络掩码目标的指针。
  • mtu_size:指向此接口的最大传输单元目标的指针。
  • physical_address_msw:指向设备 MAC 地址高 16 位的目标的指针。
  • physical_address_lsw:指向设备 MAC 地址低 32 位的目标的指针。

返回值

  • NX_SUCCESS:(0x00) 已获取接口信息。
  • NX_PTR_ERROR:(0x07) 指针输入无效。
  • NX_INVALID_INTERFACE:(0x4C) IP 指针无效。
  • NX_CALLER_ERROR:(0x11) 未从系统初始化或线程上下文调用该服务。

允许调用自

初始化、线程

可以抢占

示例

/* Retrieve interface parameters for the specified interface (index
    1 in IP instance list of interfaces). */
#define INTERFACE_INDEX 1

status = nx_ip_interface_info_get(ip_ptr, INTERFACE_INDEX,
    &name_ptr, &ip_address,
    &network_mask,
    &mtu_size,
    &physical_address_msw,
    &physical_address_lsw);

/* If status is NX_SUCCESS the interface information is
    successfully retrieved. */

另请参阅

  • nx_ip_interface_address_get、nx_ip_interface_address_set,
  • nx_ip_interface_attach、nx_ip_interface_status_check,
  • nx_ip_link_status_change_notify_set

nx_ip_interface_status_check

检查 IP 实例的状态

原型

UINT nx_ip_interface_status_check(
    NX_IP *ip_ptr,
    UINT interface_index
    ULONG needed_status,
    ULONG *actual_status,
    ULONG wait_option);

说明

此服务用于检查并选择性等待先前所创建 IP 实例的网络接口的指定状态。

参数

  • ip_ptr:指向以前所创建 IP 实例的指针。
  • interface_index:接口索引号
  • needed_status:所请求的 IP 状态,以位图形式定义,如下所示:
    • NX_IP_INITIALIZE_DONE (0x0001)
    • NX_IP_ADDRESS_RESOLVED (0x0002)
    • NX_IP_LINK_ENABLED (0x0004)
    • NX_IP_ARP_ENABLED (0x0008)
    • NX_IP_UDP_ENABLED (0x0010)
    • NX_IP_TCP_ENABLED (0x0020)
    • NX_IP_IGMP_ENABLED (0x0040)
    • NX_IP_RARP_COMPLETE (0x0080)
    • NX_IP_INTERFACE_LINK_ENABLED (0x0100)
  • * actual_status:指向实际位集目标的指针
  • * wait_option:定义所请求的状态位不可用时该服务的行为方式。 等待选项的定义如下:
    • NX_NO_WAIT (0x00000000)
    • NX_WAIT_FOREVER (0xFFFFFFFF)
    • 以时钟周期为单位的超时值(0x00000001 到 0xFFFFFFFE)

返回值

  • NX_SUCCESS:(0x00) 检查 IP 状态成功。
  • NX_NOT_SUCCESSFUL:(0x43) 未在指定的超时时间内满足状态请求。
  • NX_PTR_ERROR:(0x07) IP 指针无效或已变为无效,或实际状态指针无效。
  • NX_OPTION_ERROR:(0x0a) 必需的状态选项无效。
  • NX_CALLER_ERROR (0x11) 此服务的调用方无效。
  • NX_INVALID_INTERFACE:(0x4C) 接口索引超出范围, 或接口无效。

允许调用自

线程数

可以抢占

示例

/* Wait 10 ticks for the link up status on the previously created IP
    instance. */
status = nx_ip_interface_status_check(&ip_0, 1, NX_IP_LINK_ENABLED,
    &actual_status, 10);

/* If status is NX_SUCCESS, the secondary link for the specified IP
    instance is up. */

另请参阅

  • nx_ip_interface_address_get、nx_ip_interface_address_set,
  • nx_ip_interface_attach、nx_ip_interface_info_get,
  • nx_ip_link_status_change_notify_set

设置链路状态更改通知回调函数

原型

UINT nx_ip_link_status_change_notify_set(
    NX_IP *ip_ptr,
    VOID (*link_status_change_notify)(NX_IP *ip_ptr, UINT interface_index, UINT link_up));

说明

此服务用于配置链路状态更改通知回调函数。 当主要或辅助接口状态更改(例如 IP 地址更改)时,会调用用户提供的 link_status_change_notify 例程。如果 link_status_change_notify 为 NULL,则会禁用链路状态更改通知回调功能。

参数

  • ip_ptr:IP 控制块指针
  • link_status_change_notify:用户提供的回调函数,物理接口更改时会调用该函数。

返回值

  • NX_SUCCESS:(0x00) 设置成功
  • NX_PTR_ERROR:(0x07) IP 控制块指针或新物理地址指针无效
  • NX_CALLER_ERROR:(0x11) 未从系统初始化或线程上下文调用该服务。

允许调用自

初始化、线程

可以抢占

示例

/* Configure a callback function to be used when the physical
    interface status is changed. */
status = nx_ip_link_status_change_notify_set(&ip_0, my_change_cb);

/* If status == NX_SUCCESS, the link status change notify function
    is set. */

另请参阅

  • nx_ip_interface_address_get、nx_ip_interface_address_set,
  • nx_ip_interface_attach、nx_ip_interface_info_get,
  • nx_ip_interface_status_check

nx_ip_raw_packet_disable

禁用原始数据包发送/接收

原型

UINT nx_ip_raw_packet_disable(NX_IP *ip_ptr);

说明

此服务用于禁止此 IP 实例传输和接收原始 IP 数据包。 如果先前已启用原始数据包服务,并且接收队列中存在原始数据包,则此服务会释放任何已收到的原始数据包。

参数

  • ip_ptr:指向以前所创建 IP 实例的指针。

返回值

  • NX_SUCCESS:(0x00) 禁用 IP 原始数据包成功。
  • NX_PTR_ERROR:(0x07) IP 指针无效。
  • NX_CALLER_ERROR (0x11) 此服务的调用方无效。

允许调用自

初始化、线程

可以抢占

示例

/* Disable raw packet sending/receiving for this IP instance. */
status = nx_ip_raw_packet_disable(&ip_0);

/* If status is NX_SUCCESS, raw IP packet sending/receiving has
    been disabled for the previously created IP instance. */

另请参阅

  • nx_ip_raw_packet_enable、nx_ip_raw_packet_receive,
  • nx_ip_raw_packet_send、nx_ip_raw_packet_interface_send

nx_ip_raw_packet_enable

启用原始数据包处理

原型

UINT nx_ip_raw_packet_enable(NX_IP *ip_ptr);

说明

此服务用于允许此 IP 实例传输和接收原始 IP 数据包。 传入的 TCP、UDP、ICMP 和 IGMP 数据包仍由 NetX 处理。 上层协议类型未知的数据包由原始数据包接收例程处理。

参数

  • ip_ptr:指向以前所创建 IP 实例的指针。

返回值

  • NX_SUCCESS:(0x00) 启用 IP 原始数据包成功。
  • NX_PTR_ERROR:(0x07) IP 指针无效。
  • NX_CALLER_ERROR:(0x11) 此服务的调用方无效。

允许调用自

初始化、线程

可以抢占

示例

/* Enable raw packet sending/receiving for this IP instance. */
status = nx_ip_raw_packet_enable(&ip_0);

/* If status is NX_SUCCESS, raw IP packet sending/receiving has
    been enabled for the previously created IP instance. */

另请参阅

  • nx_ip_raw_packet_disable、nx_ip_raw_packet_receive,
  • nx_ip_raw_packet_send、nx_ip_raw_packet_interface_send

nx_ip_raw_packet_interface_send

通过指定网络接口发送原始 IP 数据包

原型

UINT nx_ip_raw_packet_interface_send(
    NX_IP *ip_ptr,
    NX_PACKET *packet_ptr,
    ULONG destination_ip,
    UINT address_index,
    ULONG type_of_service);

说明

此服务将指定的本地 IP 地址用作源地址,通过关联的网络接口将原始 IP 数据包发送到目标 IP 地址。 请注意,此例程会立即返回,因此不知道实际是否已发送该 IP 数据包。 网络驱动程序负责在传输完成后释放该数据包。 此服务与其他服务的不同之处在于,无法知道是否已实际发送该数据包。 该数据包可能会在 Internet 上丢失。

请注意,必须启用原始 IP 处理。

此服务与 nx_ip_raw_packet_send 类似,只不过此服务允许应用程序从指定的物理接口发送原始 IP 数据包

参数

  • ip_ptr:指向先前创建的 IP 任务的指针。
  • packet_ptr:指向要传输的数据包的指针。
  • destination_ip:用于发送数据包的 IP 地址。
  • address_index:用于发送数据包的接口的地址索引。
  • type_of_service:用于数据包的服务类型。

返回值

  • NX_SUCCESS:(0x00) 传输数据包成功。
  • NX_IP_ADDRESS_ERROR:(0x21) 没有合适的传出接口可用。
  • NX_NOT_ENABLED:(0x14) 原始 IP 数据包处理未启用。
  • NX_CALLER_ERROR:(0x11) 此服务的调用方无效。
  • NX_PTR_ERROR:(0x07) 指针输入无效。
  • NX_OPTION_ERROR:(0x0A) 指定了无效的服务类型。
  • NX_OVERFLOW:(0x03) 数据包前置指针无效。
  • NX_UNDERFLOW:(0x02) 数据包前置指针无效。
  • NX_INVALID_INTERFACE:(0x4C) 指定了无效的接口索引。

允许调用自

线程数

可以抢占

示例

#define ADDRESS_IDNEX 1
/* Send packet out on interface 1 with normal type of service. */
status = nx_ip_raw_packet_interface_send(ip_ptr, packet_ptr,
    destination_ip,
    ADDRESS_INDEX,
    NX_IP_NORMAL);
/* If status is NX_SUCCESS the packet was successfully transmitted. */

另请参阅

  • nx_ip_raw_packet_disable、nx_ip_raw_packet_enable,
  • nx_ip_raw_packet_receive、nx_ip_raw_packet_send

nx_ip_raw_packet_receive

接收原始 IP 数据包

原型

UINT nx_ip_raw_packet_receive(
    NX_IP *ip_ptr,
    NX_PACKET **packet_ptr,
    ULONG wait_option);

说明

此服务用于从指定的 IP 实例接收原始 IP 数据包。 如果原始数据包接收队列中已有 IP 数据包,则会将第一个(最旧)数据包返回给调用方。 如果没有可用的数据包,则调用方可能会挂起,如等待选项所指定。

如果返回了 NX_SUCCESS,则应用程序负责在不再需要收到的数据包时将其释放。

参数

  • ip_ptr:指向以前所创建 IP 实例的指针。
  • packet_ptr:此指针指向放置收到的原始 IP 数据包的指针。
  • wait_option:定义没有可用的原始 IP 数据包时该服务的行为方式。 等待选项的定义如下:
    • NX_NO_WAIT (0x00000000)
    • NX_WAIT_FOREVER (0xFFFFFFFF)
    • 以时钟周期为单位的超时值(0x00000001 到 0xFFFFFFFE)

返回值

  • NX_SUCCESS:(0x00) 接收 IP 原始数据包成功。
  • NX_NO_PACKET:(0x01) 没有可用的数据包。
  • NX_WAIT_ABORTED:(0x1A) 已通过调用 tx_thread_wait_abort 中止所请求的挂起。
  • NX_NOT_ENABLED (0x14) 尚未启用此组件。
  • NX_PTR_ERROR:(0x07) IP 指针或返回数据包指针无效。
  • NX_CALLER_ERROR:(0x11) 此服务的调用方无效

允许调用自

线程数

可以抢占

示例

/* Receive a raw IP packet for this IP instance, wait for a maximum
    of 4 timer ticks. */
status = nx_ip_raw_packet_receive(&ip_0, &packet_ptr, 4);

/* If status is NX_SUCCESS, the raw IP packet pointer is in the
    variable packet_ptr. */

另请参阅

  • nx_ip_raw_packet_disable、nx_ip_raw_packet_enable,
  • nx_ip_raw_packet_send、nx_ip_raw_packet_interface_send

nx_ip_raw_packet_send

发送原始 IP 数据包

原型

UINT nx_ip_raw_packet_send(
    NX_IP *ip_ptr,
    NX_PACKET *packet_ptr,
    ULONG destination_ip,
    ULONG type_of_service);

说明

此服务用于将原始 IP 数据包发送到目标 IP 地址。 请注意,此例程会立即返回,因此不知道实际是否已发送该 IP 数据包。 网络驱动程序负责在传输完成后释放该数据包。

对于多宿主系统,NetX 会使用目标 IP 地址来查找适当的网络接口,并将该接口的 IP 地址用作源地址。 如果目标 IP 地址为广播或多播,则使用第一个有效接口。 在本例中,应用程序使用 nx_ip_raw_packet_interface_send

除非返回了错误,否则应用程序不应在此调用后释放该数据包。 这样做会导致不可预知的结果,因为网络驱动程序会在传输后释放该数据包。

参数

  • ip_ptr:指向以前所创建 IP 实例的指针。
  • packet_ptr:指向要发送的原始 IP 数据包的指针。
  • destination_ip:目标 IP 地址,这可以是特定的主机 IP 地址、网络广播、内部环回或多播地址。
  • type_of_service:定义用于传输的服务类型,合法值如下所示:
    • NX_IP_NORMAL (0x00000000)
    • NX_IP_MIN_DELAY (0x00100000)
    • NX_IP_MAX_DATA (0x00080000)
    • NX_IP_MAX_RELIABLE (0x00040000)
    • NX_IP_MIN_COST (0x00020000)

返回值

  • NX_SUCCESS:(0x00) 发起 IP 原始数据包发送成功。
  • NX_IP_ADDRESS_ERROR:(0x21) IP 地址无效。
  • NX_NOT_ENABLED:(0x14) 原始 IP 功能未启用。
  • NX_OPTION_ERROR:(0x0A) 服务类型无效。
  • NX_UNDERFLOW:(0x02) 空间不足,无法在数据包开头附加 IP 标头。
  • NX_OVERFLOW:(0x03) 数据包追加指针无效。
  • NX_PTR_ERROR:(0x07) IP 指针或数据包指针无效。
  • NX_CALLER_ERROR (0x11) 此服务的调用方无效。

允许调用自

线程数

可以抢占

示例

/* Send a raw IP packet to IP address 1.2.3.5. */
status = nx_ip_raw_packet_send(&ip_0, packet_ptr,
    IP_ADDRESS(1,2,3,5),
    NX_IP_NORMAL);

/* If status is NX_SUCCESS, the raw IP packet pointed to by
    packet_ptr has been sent. */

另请参阅

  • nx_ip_raw_packet_disable、nx_ip_raw_packet_enable,
  • nx_ip_raw_packet_receive、nx_ip_raw_packet_send,
  • nx_ip_raw_packet_interface_send

nx_ip_static_route_add

将静态路由添加到路由表

原型

UINT nx_ip_static_route_add(
    NX_IP *ip_ptr,
    ULONG network_address,
    ULONG net_mask,
    ULONG next_hop);

说明

此服务用于在静态路由表中添加一个条目。 请注意,next_hop 地址必须可从其中一个本地网络设备直接访问。

请注意,ip_ptr 必须指向有效的 NetX IP 结构,而且必须在定义了 NX_ENABLE_IP_STATIC_ROUTING 的情况下生成 NetX 库才能使用此服务。 默认情况下,NetX 是在未定义 NX_ENABLE_IP_STATIC_ROUTING 的情况下生成的。

参数

  • ip_ptr:指向以前所创建 IP 实例的指针。
  • network_address:目标网络地址,以主机字节顺序表示
  • net_mask:目标网络掩码,以主机字节顺序表示
  • next_hop:目标网络的下一个跃点地址,以主机字节顺序表示

返回值

  • NX_SUCCESS:(0x00) 条目已添加到静态路由表中。
  • NX_OVERFLOW:(0x03) 静态路由表已满。
  • NX_NOT_SUPPORTED:(0x4B) 此功能尚未编译在内。
  • NX_IP_ADDRESS_ERROR:(0x21) 无法通过本地接口直接访问下一个跃点。
  • NX_CALLER_ERROR:(0x11) 此服务的调用方无效。
  • NX_PTR_ERROR:(0x07) ip_ptr 指针无效。

允许调用自

初始化、线程

可以抢占

示例

/* Specify the next hop for the 192.168.10.0 through the gateway
    192.168.1.1. */
status = nx_ip_static_route_add(ip_ptr, IP_ADDRESS(192,168,10,0),
    0xFFFFFF00UL,
    IP_ADDRESS(192,168,1,1));

/* If status is NX_SUCCESS the route was successfully added to the
    static routing table. */

另请参阅

  • nx_ip_gateway_address_set、nx_ip_info_get、nx_ip_static_route_delete

nx_ip_static_route_delete

从路由表中删除静态路由

原型

UINT nx_ip_static_route_delete(
    NX_IP *ip_ptr,
    ULONG network_address, 
    ULONG net_mask);

说明

此服务用于从静态路由表中删除条目。

请注意,ip_ptr 必须指向有效的 NetX IP 结构,而且必须在定义了 NX_ENABLE_IP_STATIC_ROUTING 的情况下生成 NetX 库才能使用此服务。 默认情况下,NetX 是在未定义 NX_ENABLE_IP_STATIC_ROUTING 的情况下生成的。

参数

  • ip_ptr:指向以前所创建 IP 实例的指针。
  • network_address:目标网络地址,以主机字节顺序表示。
  • net_mask:目标网络掩码,以主机字节顺序表示。

允许来自

初始化、线程

可以抢占

示例

/* Remove the static route for 192.168.10.0 from the routing table.*/
status = nx_ip_static_route_delete(ip_ptr,
    IP_ADDRESS(192,168,10,0), 0xFFFFFF00UL,);

/* If status is NX_SUCCESS the route was successfully removed from
    the static routing table. */

另请参阅

  • nx_ip_gateway_address_set、nx_ip_info_get、nx_ip_static_route_add

nx_ip_status_check

检查 IP 实例的状态

原型

UINT nx_ip_status_check(
    NX_IP *ip_ptr,
    ULONG needed_status,
    ULONG *actual_status,
    ULONG wait_option);

说明

此服务用于检查并选择性等待先前所创建 IP 实例的主网络接口的指定状态。 若要获取辅助接口的状态,应用程序应使用 nx_ip_interface_status_check 服务

参数

  • ip_ptr:指向以前所创建 IP 实例的指针。
  • needed_status:所请求的 IP 状态,以位图形式定义,如下所示:
    • NX_IP_INITIALIZE_DONE (0x0001)
    • NX_IP_ADDRESS_RESOLVED (0x0002)
    • NX_IP_LINK_ENABLED (0x0004)
    • NX_IP_ARP_ENABLED (0x0008)
    • NX_IP_UDP_ENABLED (0x0010)
    • NX_IP_TCP_ENABLED (0x0020)
    • NX_IP_IGMP_ENABLED (0x0040)
    • NX_IP_RARP_COMPLETE (0x0080)
    • NX_IP_INTERFACE_LINK_ENABLED (0x0100)
  • actual_status:指向实际位集目标的指针。
  • wait_option:定义所请求的状态位不可用时该服务的行为方式。 等待选项的定义如下:
    • NX_NO_WAIT (0x00000000)
    • NX_WAIT_FOREVER (0xFFFFFFFF)
    • 以时钟周期为单位的超时值(0x00000001 到 0xFFFFFFFE)

返回值

  • NX_SUCCESS:(0x00) 检查 IP 状态成功。
  • NX_NOT_SUCCESSFUL:(0x43) 未在指定的超时时间内满足状态请求。
  • NX_PTR_ERROR:(0x07) IP 指针无效或已变为无效,或实际状态指针无效。
  • NX_OPTION_ERROR:(0x0a) 必需的状态选项无效。
  • NX_CALLER_ERROR (0x11) 此服务的调用方无效。

允许调用自

线程数

可以抢占

示例

/* Wait 10 ticks for the link up status on the previously created IP
    instance. */
status = nx_ip_status_check(&ip_0, NX_IP_LINK_ENABLED,
    &actual_status, 10);

/* If status is NX_SUCCESS, the link for the specified IP instance
    is up. */

另请参阅

  • nx_ip_address_change_notify、nx_ip_address_get、nx_ip_address_set,
  • nx_ip_create、nx_ip_delete、nx_ip_driver_direct_command,
  • nx_ip_driver_interface_direct_command、nx_ip_forwarding_disable,
  • nx_ip_forwarding_enable、nx_ip_fragment_disable,
  • nx_ip_fragment_enable、nx_ip_info_get、nx_system_initialize

nx_packet_allocate

从指定的池分配数据包

原型

UINT nx_packet_allocate(
    NX_PACKET_POOL *pool_ptr,
    NX_PACKET **packet_ptr,
    ULONG packet_type,
    ULONG wait_option);

说明

此服务用于从指定的池分配数据包,并根据指定的数据包类型调整该数据包中的预置指针。 没有可用的数据包时,此服务会根据提供的等待选项挂起。

参数

  • pool_ptr:指向先前创建的数据包池的指针。
  • packet_ptr:此指针指向分配的数据包指针的指针。
  • packet_type:定义所请求的数据包类型。 有关支持的数据包类型的列表,请参阅第 3 章第 49 页的“数据包池”。
  • wait_option:定义数据包池中没有可用数据包时的等待时间(以时钟周期为单位)。 等待选项的定义如下:
    • NX_NO_WAIT (0x00000000)
    • NX_WAIT_FOREVER (0xFFFFFFFF)
    • 以时钟周期为单位的超时值(0x00000001 到 0xFFFFFFFE)

返回值

  • NX_SUCCESS:(0x00) 分配数据包成功。
  • NX_NO_PACKET (0x01) 没有可用的数据包。
  • NX_WAIT_ABORTED:(0x1A) 已通过调用 tx_thread_wait_abort 中止所请求的挂起。
  • NX_INVALID_PARAMETERS (0x4D) 数据包大小无法支持协议。
  • NX_OPTION_ERROR:(0x0A) 数据包类型无效。
  • NX_PTR_ERROR:(0x07) 池指针或数据包返回指针无效。
  • NX_CALLER_ERROR:(0x11) 来自非线程的等待选项无效。

允许调用自

初始化、线程、计时器和 ISR(应用程序网络驱动程序)。 在 ISR 或计时器上下文中使用时,等待选项必须是 NX_NO_WAIT。

可以抢占

示例

/* Allocate a new UDP packet from the previously created packet pool
    and suspend for a maximum of 5 timer ticks if the pool is
    empty. */
status = nx_packet_allocate(&pool_0, &packet_ptr, NX_UDP_PACKET, 5);

/* If status is NX_SUCCESS, the newly allocated packet pointer is
    found in the variable packet_ptr. */

另请参阅

  • nx_packet_copy、nx_packet_data_append,
  • nx_packet_data_extract_offset、nx_packet_data_retrieve,
  • nx_packet_length_get、nx_packet_pool_create、nx_packet_pool_delete,
  • nx_packet_pool_info_get、nx_packet_release,
  • nx_packet_transmit_release

nx_packet_copy

复制数据包

原型

UINT nx_packet_copy(
    NX_PACKET *packet_ptr,
    NX_PACKET **new_packet_ptr,
    NX_PACKET_POOL *pool_ptr,
    ULONG wait_option);

说明

此服务用于将提供的数据包中的信息,复制到一个或多个从提供的数据包池分配的新数据包。 如果成功,则会在 new_packet_ptr 所指向的目标中返回指向新数据包的指针。

参数

  • packet_ptr:指向源数据包的指针。
  • new_packet_ptr:目标的指针,在该目标中返回指向数据包新副本的指针。
  • pool_ptr:先前创建的数据包池的指针,该池用于为副本分配一个或多个数据包。
  • wait_option:定义了没有可用的数据包时该服务的等待方式。 等待选项的定义如下:
    • NX_NO_WAIT (0x00000000)
    • NX_WAIT_FOREVER (0xFFFFFFFF)
    • 以时钟周期为单位的超时值(0x00000001 到 0xFFFFFFFE)

返回值

  • NX_SUCCESS:(0x00) 复制数据包成功。
  • NX_NO_PACKET:(0x01) 没有可供复制的数据包。
  • NX_INVALID_PACKET:(0x12) 源数据包为空,或者复制失败。
  • NX_WAIT_ABORTED:(0x1A) 已通过调用 tx_thread_wait_abort 中止所请求的挂起。
  • NX_INVALID_PARAMETERS (0x4D) 数据包大小无法支持协议。
  • NX_PTR_ERROR:(0x07) 池指针、数据包指针或目标指针无效。
  • NX_UNDERFLOW:(0x02) 数据包前置指针无效。
  • NX_OVERFLOW:(0x03) 数据包追加指针无效。
  • NX_CALLER_ERROR:(0x11) 在初始化期间或在 ISR 中指定了等待选项。

允许调用自

初始化、线程、计时器和 ISR

可以抢占

示例

NX_PACKET *new_copy_ptr;

/* Copy packet pointed to by "old_packet_ptr" using packets from
    previously created packet pool_0. */
status = nx_packet_copy(old_packet, &new_copy_ptr, &pool_0, 20);

/* If status is NX_SUCCESS, new_copy_ptr points to the packet copy. */

另请参阅

  • nx_packet_allocate、nx_packet_data_append,
  • nx_packet_data_extract_offset、nx_packet_data_retrieve,
  • nx_packet_length_get、nx_packet_pool_create、nx_packet_pool_delete,
  • nx_packet_pool_info_get、nx_packet_release,
  • nx_packet_transmit_release

nx_packet_data_append

将数据追加到数据包末尾

原型

UINT nx_packet_data_append(
    NX_PACKET *packet_ptr,
    VOID *data_start, 
    ULONG data_size,
    NX_PACKET_POOL *pool_ptr,
    ULONG wait_option);

说明

此服务用于将数据追加到指定的数据包末尾。 提供的数据区域会复制到该数据包中。 如果没有足够的可用内存,并且已启用链式数据包功能,则会分配一个或多个数据包来满足该请求。 如果未启用链式数据包功能,则会返回 NX_SIZE_ERROR。

参数

  • packet_ptr:数据包指针。
  • data_start:此指针指向要追加到数据包的用户数据区域的开头。
  • data_size:用户数据区域的大小。
  • pool_ptr:数据包池的指针,在当前数据包中空间不足时,会从该池分配另一个数据包。
  • wait_option:定义没有可用的数据包时该服务的行为方式。 等待选项的定义如下:
    • NX_NO_WAIT (0x00000000)
    • NX_WAIT_FOREVER (0xFFFFFFFF)
    • 以时钟周期为单位的超时值(0x00000001 到 0xFFFFFFFE)

返回值

  • NX_SUCCESS:(0x00) 追加数据包成功。
  • NX_NO_PACKET (0x01) 没有可用的数据包。
  • NX_WAIT_ABORTED (0x1A) 已通过调用 tx_thread_wait_abort 中止所请求的挂起。
  • NX_INVALID_PARAMETERS (0x4D) 数据包大小无法支持协议。
  • NX_UNDERFLOW:(0x02) 预置指针小于有效负载开始位置。
  • NX_OVERFLOW:(0x03) 追加指针大于有效负载结束位置。
  • NX_PTR_ERROR:(0x07) 池、数据包或数据指针无效。
  • NX_SIZE_ERROR:(0x09) 数据大小无效。
  • NX_CALLER_ERROR:(0x11) 来自非线程的等待选项无效。

允许调用自

初始化、线程、计时器和 ISR(应用程序网络驱动程序)

可以抢占

示例

/* Append "abcd" to the specified packet. */
status = nx_packet_data_append(packet_ptr, "abcd", 4, &pool_0, 5);

/* If status is NX_SUCCESS, the additional four bytes "abcd" have
    been appended to the packet. */

另请参阅

  • nx_packet_allocate、nx_packet_copy、nx_packet_data_extract_offset,
  • nx_packet_data_retrieve、nx_packet_length_get、nx_packet_pool_create,
  • nx_packet_pool_delete、nx_packet_pool_info_get、nx_packet_release,
  • nx_packet_transmit_release

nx_packet_data_extract_offset

通过偏移量从数据包中提取数据

原型

UINT nx_packet_data_extract_offset(
    NX_PACKET *packet_ptr,
    ULONG offset,
    VOID *buffer_start,
    ULONG buffer_length,
    ULONG *bytes_copied);

说明

此服务用于将 NetX 数据包(或数据包链)中的数据复制到指定的缓冲区,该数据从相对于数据包前置指针的指定偏移量开头,并具有指定的大小(以字节为单位)。 实际复制的字节数会在 bytes_copied 中返回。此服务不会从该数据包中删除数据,也不会调整前置指针或其他内部状态信息。

参数

  • packet_ptr:指向要提取的数据包的指针
  • offset:相对于当前前置指针的偏移量。
  • buffer_start:指向保存缓冲区开头的指针
  • buffer_length:要复制的字节数
  • bytes_copied:实际复制的字节数

返回值

  • NX_SUCCESS:(0x00) 复制数据包成功
  • NX_PACKET_OFFSET_ERROR:(0x53) 提供了无效的偏移量值
  • NX_PTR_ERROR:(0x07) 数据包指针或缓冲区指针无效

允许调用自

初始化、线程、计时器和 ISR

可以抢占

示例

/* Extract 10 bytes from the start of the received packet buffer
    into the specified memory area. */
status = nx_packet_data_extract_offset(my_packet, 0, &data[0], 10,
    &bytes_copied);

/* If status is NX_SUCCESS, 10 bytes were successfully copied into
    the data buffer. */

另请参阅

  • nx_packet_allocate、nx_packet_copy、nx_packet_data_append,
  • nx_packet_data_retrieve、nx_packet_length_get、nx_packet_pool_create,
  • nx_packet_pool_delete、nx_packet_pool_info_get、nx_packet_release,
  • nx_packet_transmit_release

nx_packet_data_retrieve

从数据包中检索数据

原型

UINT nx_packet_data_retrieve(
    NX_PACKET *packet_ptr,
    VOID *buffer_start, 
    ULONG *bytes_copied);

说明

此服务用于将提供的数据包中的数据复制到提供的缓冲区。 复制的实际字节数会在 bytes_copied 所指向的目标中返回。

请注意,此服务不会更改该数据包的内部状态。 所检索的数据仍存在于该数据包中。

目标缓冲区的大小必须足以容纳该数据包的内容。 否则内存会损坏,导致不可预知的结果。

参数

  • packet_ptr:指向源数据包的指针。
  • buffer_start:指向缓冲区开头的指针。
  • bytes_copied:此指针指向复制的字节数的目标。

返回值

  • NX_SUCCESS:(0x00) 检索数据包数据成功。
  • NX_INVALID_PACKET:(0x12) 数据包无效。
  • NX_PTR_ERROR:(0x07) 数据包指针、缓冲区开头指针或复制字节数指针无效。

允许调用自

初始化、线程、计时器和 ISR

可以抢占

示例

UCHAR buffer[512];
ULONG bytes_copied;

/* Retrieve data from packet pointed to by "packet_ptr". */
status = nx_packet_data_retrieve(packet_ptr, buffer, &bytes_copied);

/* If status is NX_SUCCESS, buffer contains the contents of the
    packet, the size of which is contained in "bytes_copied." */

另请参阅

  • nx_packet_allocate、nx_packet_copy、nx_packet_data_append,
  • nx_packet_data_extract_offset、nx_packet_length_get,
  • nx_packet_pool_create、nx_packet_pool_delete,
  • nx_packet_pool_info_get、nx_packet_release,
  • nx_packet_transmit_release

nx_packet_length_get

获取数据包数据的长度

原型

UINT nx_packet_length_get(
    NX_PACKET *packet_ptr, 
    ULONG *length);

说明

此服务用于获取所指定数据包中的数据长度。

参数

  • packet_ptr:指向数据包的指针。
  • length:数据包长度的目标。

允许来自

初始化、线程、计时器和 ISR

可以抢占

示例

/* Get the length of the data in "my_packet." */
status = nx_packet_length_get(my_packet, &my_length);

/* If status is NX_SUCCESS, data length is in "my_length". */

另请参阅

  • nx_packet_allocate、nx_packet_copy、nx_packet_data_append,
  • nx_packet_data_extract_offset、nx_packet_data_retrieve,
  • nx_packet_pool_create、nx_packet_pool_delete,
  • nx_packet_pool_info_get、nx_packet_release,
  • nx_packet_transmit_release

nx_packet_pool_create

在指定的内存区域创建数据包池

原型

UINT nx_packet_pool_create(
    NX_PACKET_POOL *pool_ptr,
    CHAR *name,
    ULONG payload_size,
    VOID *memory_ptr,
    ULONG memory_size);

说明

此服务用于在用户提供的内存区域中创建所指定数据包大小的数据包池。

参数

  • pool_ptr:指向数据包池控制块的指针。
  • name:指向数据包池的应用程序名称的指针。
  • payload_size:池中每个数据包的字节数。 此值必须至少为 40 个字节,并且还必须可以被 4 整除。
  • memory_ptr:指向要放置数据包池的内存区域的指针。 此指针应该在 ULONG 边界上对齐。
  • memory_size:池内存区域的大小。

返回值

  • NX_SUCCESS:(0x00) 创建数据包池成功。
  • NX_PTR_ERROR:(0x07) 池指针或内存指针无效。
  • NX_SIZE_ERROR:(0x09) 块大小或内存大小无效。
  • NX_CALLER_ERROR:(0x11) 此服务的调用方无效。

允许调用自

初始化、线程

可以抢占

示例

/* Create a packet pool of 32000 bytes starting at physical
    address 0x10000000. */
status = nx_packet_pool_create(&pool_0, "Default Pool", 128,
    (void *) 0x10000000, 32000);

/* If status is NX_SUCCESS, the packet pool has been successfully
    created. */

另请参阅

  • nx_packet_allocate、nx_packet_copy、nx_packet_data_append,
  • nx_packet_data_extract_offset、nx_packet_data_retrieve,
  • nx_packet_length_get、nx_packet_pool_delete、nx_packet_pool_info_get,
  • nx_packet_release、nx_packet_transmit_release

nx_packet_pool_delete

删除先前创建的数据包池

原型

UINT nx_packet_pool_delete(NX_PACKET_POOL *pool_ptr);

说明

此服务用于删除先前创建的数据包池。 NetX 会检查该数据包池中的数据包上当前是否有任何挂起的线程,并清除挂起。

参数

  • pool_ptr:数据包池控制块指针。

返回值

  • NX_SUCCESS:(0x00) 删除数据包池成功。
  • NX_PTR_ERROR:(0x07) 池指针无效。
  • NX_CALLER_ERROR:(0x11) 此服务的调用方无效。

允许调用自

线程数

可以抢占

示例

/* Delete a previously created packet pool. */
status = nx_packet_pool_delete(&pool_0);

/* If status is NX_SUCCESS, the packet pool has been successfully
    deleted. */

另请参阅

  • nx_packet_allocate、nx_packet_copy、nx_packet_data_append,
  • nx_packet_data_extract_offset、nx_packet_data_retrieve,
  • nx_packet_length_get、nx_packet_pool_create,
  • nx_packet_pool_info_get、nx_packet_release,
  • nx_packet_transmit_release

nx_packet_pool_info_get

检索数据包池的相关信息

原型

UINT nx_packet_pool_info_get(
    NX_PACKET_POOL *pool_ptr,
    ULONG *total_packets,
    ULONG *free_packets,
    ULONG *empty_pool_requests,
    ULONG *empty_pool_suspensions,
    ULONG *invalid_packet_releases);

说明

此服务用于检索所指定数据包池的相关信息。

如果目标指针为 NX_NULL,则不会将该特定信息返回给调用方

参数

  • pool_ptr:指向先前创建的数据包池的指针。
  • total_packets:此指针指向池中数据包总数的目标。
  • free_packets:此指针指向当前可用数据包总数的目标。
  • empty_pool_requests:此指针指向该池为空时分配请求总数的目标。
  • empty_pool_suspensions:此指针指向空池挂起总数的目标。
  • invalid_packet_releases:此指针指向无效数据包释放总数的目标。

返回值

  • NX_SUCCESS:(0x00) 检索数据包池信息成功。
  • NX_PTR_ERROR:(0x07) IP 指针无效。
  • NX_CALLER_ERROR (0x11) 此服务的调用方无效。

允许调用自

初始化、线程和计时器

可以抢占

示例

/* Retrieve packet pool information. */
status = nx_packet_pool_info_get(&pool_0,
    &total_packets,
    &free_packets,
    &empty_pool_requests,
    &empty_pool_suspensions,
    &invalid_packet_releases);

/* If status is NX_SUCCESS, packet pool information was
    retrieved. */

另请参阅

  • nx_packet_allocate、nx_packet_copy、nx_packet_data_append,
  • nx_packet_data_extract_offset、nx_packet_data_retrieve,
  • nx_packet_length_get、nx_packet_pool_create、nx_packet_pool_delete
  • nx_packet_release、nx_packet_transmit_release

nx_packet_release

释放先前分配的数据包

原型

UINT nx_packet_release(NX_PACKET *packet_ptr);

说明

此服务用于释放数据包,包括链接到指定数据包的任何其他数据包。 如有其他线程在分配数据包时遭到止,则该线程会获得该数据包并继续执行。

应用程序必须防止多次释放同一数据包,否则会导致不可预知的结果。

参数

  • packet_ptr:数据包指针。

返回值

  • NX_SUCCESS:(0x00) 释放数据包成功。
  • NX_PTR_ERROR:(0x07) 数据包指针无效。
  • NX_UNDERFLOW:(0x02) 预置指针小于有效负载开始位置。
  • NX_OVERFLOW:(0x03) 追加指针大于有效负载结束位置。

允许调用自

初始化、线程、计时器和 ISR(应用程序网络驱动程序)

可以抢占

示例

/* Release a previously allocated packet. */
status = nx_packet_release(packet_ptr);

/* If status is NX_SUCCESS, the packet has been returned to the
    packet pool it was allocated from. */

另请参阅

  • nx_packet_allocate、nx_packet_copy、nx_packet_data_append,
  • nx_packet_data_extract_offset、nx_packet_data_retrieve,
  • nx_packet_length_get、nx_packet_pool_create、nx_packet_pool_delete,
  • nx_packet_pool_info_get、nx_packet_transmit_release

nx_packet_transmit_release

释放已传输的数据包

原型

UINT nx_packet_transmit_release(NX_PACKET *packet_ptr);

说明

对于非 TCP 数据包,此服务可释放已传输的数据包,包括链接到指定数据包的任何其他数据包。 如有其他线程在分配数据包时遭到止,则该线程会获得该数据包并继续执行。 对于已传输的 TCP 数据包,该数据包会标记为已传输,但直到该数据包获确认后才会释放。 通常,在传输数据包之后,会从应用程序的网络驱动程序中调用此服务。

在调用此服务之前,网络驱动程序应删除物理介质标头,并调整数据包的长度。

参数

  • packet_ptr:数据包指针。

返回值

  • NX_SUCCESS:(0x00) 释放传输数据包成功。
  • NX_PTR_ERROR:(0x07) 数据包指针无效。
  • NX_UNDERFLOW:(0x02) 预置指针小于有效负载开始位置。
  • NX_OVERFLOW:(0x03) 追加指针大于有效负载结束位置。

允许调用自

初始化、线程、计时器、应用程序网络驱动程序(包括 ISR)

可以抢占

示例

/* Release a previously allocated packet that was just transmitted
    from the application network driver. */
status = nx_packet_transmit_release(packet_ptr);

/* If status is NX_SUCCESS, the transmitted packet has been
    returned to the packet pool it was allocated from. */

另请参阅

  • nx_packet_allocate、nx_packet_copy、nx_packet_data_append,
  • nx_packet_data_extract_offset、nx_packet_data_retrieve,
  • nx_packet_length_get、nx_packet_pool_create、nx_packet_pool_delete,
  • nx_packet_pool_info_get、nx_packet_release

nx_rarp_disable

禁用反向地址解析协议 (RARP)

原型

UINT nx_rarp_disable(NX_IP *ip_ptr);

说明

此服务用于对特定的 IP 实例禁用 NetX 的 RARP 组件。 对于多宿主系统,此服务会在所有接口上禁用 RARP。

参数

  • ip_ptr:指向以前所创建 IP 实例的指针。

返回值

  • NX_SUCCESS:(0x00) 禁用 RARP 成功。
  • NX_NOT_ENABLED:(0x14) RARP 未启用。
  • NX_PTR_ERROR:(0x07) IP 指针无效。
  • NX_CALLER_ERROR (0x11) 此服务的调用方无效。

允许调用自

初始化、线程

可以抢占

示例

/* Disable RARP on the previously created IP instance. */
status = nx_rarp_disable(&ip_0);

/* If status is NX_SUCCESS, RARP is disabled. */

另请参阅

  • nx_rarp_enable、nx_rarp_info_get

nx_rarp_enable

启用反向地址解析协议 (RARP)

原型

UINT nx_rarp_enable(NX_IP *ip_ptr);

说明

此服务用于对特定的 IP 实例启用 NetX 的 RARP 组件。 RARP 组件会通过所有已附加的网络接口搜索零 IP 地址。 零 IP 地址表示该接口尚未获分配 IP 地址。 RARP 会尝试通过在该接口上启用 RARP 进程来解析 IP 地址。

参数

  • ip_ptr:指向以前所创建 IP 实例的指针。

返回值

  • NX_SUCCESS:(0x00) 启用 RARP 成功。
  • NX_IP_ADDRESS_ERROR:(0x21) IP 地址已有效。
  • NX_ALREADY_ENABLED:(0x15) RARP 已启用。
  • NX_PTR_ERROR:(0x07) IP 指针无效。
  • NX_CALLER_ERROR:(0x11) 此服务的调用方无效。

允许调用自

初始化、线程、计时器

可以抢占

示例

/* Enable RARP on the previously created IP instance. */
status = nx_rarp_enable(&ip_0);

/* If status is NX_SUCCESS, RARP is enabled and is attempting to
    resolve this IP instance’s address by querying the network. */

另请参阅

  • nx_rarp_disable、nx_rarp_info_get

nx_rarp_info_get

检索 RARP 活动的相关信息

原型

UINT nx_rarp_info_get(
    NX_IP *ip_ptr,
    ULONG *rarp_requests_sent,
    ULONG *rarp_responses_received,
    ULONG *rarp_invalid_messages);

说明

此服务检索所指定 IP 实例的 RARP 活动相关信息。

如果目标指针为 NX_NULL,则不会将该特定信息返回给调用方

参数

  • ip_ptr:指向以前所创建 IP 实例的指针。
  • rarp_requests_sent:此指针指向已发送的 RARP 请求总数的目标。
  • rarp_responses_received:此指针指向已收到的 RARP 响应总数的目标。
  • rarp_invalid_messages:此指针指向无效消息总数的目标。

返回值

  • NX_SUCCESS:(0x00) 检索 RARP 信息成功。
  • NX_PTR_ERROR:(0x07) IP 指针无效。
  • NX_NOT_ENABLED (0x14) 尚未启用此组件。
  • NX_CALLER_ERROR:(0x11) 此服务的调用方无效。

允许调用自

初始化、线程

可以抢占

示例

/* Retrieve RARP information from previously created IP
    Instance 0. */
status = nx_rarp_info_get(&ip_0,
    &rarp_requests_sent,
    &rarp_responses_received,
    &rarp_invalid_messages);

/* If status is NX_SUCCESS, RARP information was retrieved. */

另请参阅

  • nx_rarp_disable、nx_rarp_enable

nx_system_initialize

初始化 NetX 系统

原型

VOID nx_system_initialize(VOID);

说明

此服务用于初始化基本的 NetX 系统资源以备使用。 应用程序应在初始化期间和进行任何其他 NetX 调用之前调用此服务。

参数

返回值

允许来自

初始化、线程、计时器、ISR

可以抢占

示例

/* Initialize NetX for operation. */
nx_system_initialize();

/* At this point, NetX is ready for IP creation and all subsequent
    network operations. */

另请参阅

  • nx_ip_address_change_notify、nx_ip_address_get、nx_ip_address_set,
  • nx_ip_create、nx_ip_delete、nx_ip_driver_direct_command,
  • nx_ip_driver_interface_direct_command、nx_ip_forwarding_disable,
  • nx_ip_forwarding_enable、nx_ip_fragment_disable,
  • nx_ip_fragment_enable、x_ip_info_get、x_ip_status_check

nx_tcp_client_socket_bind

将客户端 TCP 套接字与 TCP 端口绑定

原型

UINT nx_tcp_client_socket_bind(
    NX_TCP_SOCKET *socket_ptr,
    UINT port, ULONG wait_option);

说明

此服务用于将先前创建的 TCP 客户端套接字与指定的 TCP 端口绑定。 有效 TCP 套接字范围为 0 到 0xFFFF。 如果指定的 TCP 端口不可用,则此服务会根据提供的等待选项挂起。

参数

  • socket_ptr:此指针指向先前创建的 TCP 套接字实例。
  • port:要绑定的端口号(1 到 0xFFFF)。 如果端口号为 NX_ANY_PORT (0x0000),则 IP 实例会搜索下一个可用端口并将其用于绑定。
  • wait_option:定义该端口已与另一套接字绑定时此服务的行为方式。 等待选项的定义如下:
    • NX_NO_WAIT (0x00000000)
    • NX_WAIT_FOREVER (0xFFFFFFFF)
    • 以时钟周期为单位的超时值(0x00000001 到 0xFFFFFFFE)

返回值

  • NX_SUCCESS:(0x00) 绑定套接字成功。
  • NX_ALREADY_BOUND:(0x22) 此套接字已与另一 TCP 端口绑定。
  • NX_PORT_UNAVAILABLE:(0x23) 端口已与其他套接字绑定。
  • NX_NO_FREE_PORTS (0x45) 没有可用的端口。
  • NX_WAIT_ABORTED (0x1A) 已通过调用 tx_thread_wait_abort 中止所请求的挂起。
  • NX_INVALID_PORT (0x46) 端口无效。
  • NX_PTR_ERROR:(0x07) 套接字指针无效。
  • NX_CALLER_ERROR (0x11) 此服务的调用方无效。
  • NX_NOT_ENABLED (0x14) 尚未启用此组件。

允许调用自

线程数

可以抢占

示例

/* Bind a previously created client socket to port 12 and wait for 7
    timer ticks for the bind to complete. */
status = nx_tcp_client_socket_bind(&client_socket, 12, 7);

/* If status is NX_SUCCESS, the previously created client_socket is
    bound to port 12 on the associated IP instance. */

另请参阅

  • nx_tcp_client_socket_connect、x_tcp_client_socket_port_get,
  • nx_tcp_client_socket_unbind、nx_tcp_enable、nx_tcp_free_port_find,
  • nx_tcp_info_get、nx_tcp_server_socket_accept,
  • nx_tcp_server_socket_listen、nx_tcp_server_socket_relisten,
  • nx_tcp_server_socket_unaccept、nx_tcp_server_socket_unlisten,
  • nx_tcp_socket_bytes_available、nx_tcp_socket_create,
  • nx_tcp_socket_delete、nx_tcp_socket_disconnect,
  • nx_tcp_socket_info_get、nx_tcp_socket_receive,
  • nx_tcp_socket_receive_queue_max_set、nx_tcp_socket_send,
  • nx_tcp_socket_state_wait

nx_tcp_client_socket_connect

连接客户端 TCP 套接字

原型

UINT nx_tcp_client_socket_connect(
    NX_TCP_SOCKET *socket_ptr,
    ULONG server_ip,
    UINT server_port,
    ULONG wait_option);

说明

此服务用于将先前创建并绑定的 TCP 客户端套接字连接到指定的服务器端口。 有效的 TCP 服务器端口介于 0 到 0xFFFF 之间。 该连接无法立即完成时,此服务会根据提供的等待选项挂起。

参数

  • socket_ptr:此指针指向先前创建的 TCP 套接字实例。
  • server_ip:服务器的 IP 地址。
  • server_port:要连接到的服务器端口号(1 到 0xFFFF)。
  • wait_option:定义建立该连接时此服务的行为方式。 等待选项的定义如下:
    • NX_NO_WAIT (0x00000000)
    • NX_WAIT_FOREVER (0xFFFFFFFF)
    • 以时钟周期为单位的超时值(0x00000001 到 0xFFFFFFFE)

返回值

  • NX_SUCCESS:(0x00) 连接套接字成功。
  • NX_NOT_BOUND:(0x24) 套接字未绑定。
  • NX_NOT_CLOSED:(0x35) 套接字未处于关闭状态。
  • NX_IN_PROGRESS:(0x37) 未指定等待,连接尝试正在进行中。
  • NX_INVALID_INTERFACE:(0x4C) 提供了无效的接口。
  • NX_WAIT_ABORTED:(0x1A) 已通过调用 tx_thread_wait_abort 中止所请求的挂起。
  • NX_IP_ADDRESS_ERROR:(0x21) 服务器 IP 地址无效。
  • NX_INVALID_PORT (0x46) 端口无效。
  • NX_PTR_ERROR:(0x07) 套接字指针无效。
  • NX_CALLER_ERROR:(0x11) 此服务的调用方无效。
  • NX_NOT_ENABLED (0x14) 尚未启用此组件。

允许调用自

线程数

可以抢占

示例

/* Initiate a TCP connection from a previously created and bound
    client socket. The connection requested in this example is to
    port 12 on the server with the IP address of 1.2.3.5. This
    service will wait 300 timer ticks for the connection to take
    place before giving up. */
status = nx_tcp_client_socket_connect(&client_socket,
    IP_ADDRESS(1,2,3,5), 12, 300);

/* If status is NX_SUCCESS, the previously created and bound
    client_socket is connected to port 12 on IP 1.2.3.5. */

另请参阅

  • nx_tcp_client_socket_bind、x_tcp_client_socket_port_get,
  • nx_tcp_client_socket_unbind、nx_tcp_enable、nx_tcp_free_port_find,
  • nx_tcp_info_get、nx_tcp_server_socket_accept,
  • nx_tcp_server_socket_listen、nx_tcp_server_socket_relisten,
  • nx_tcp_server_socket_unaccept、nx_tcp_server_socket_unlisten,
  • nx_tcp_socket_bytes_available、nx_tcp_socket_create,
  • nx_tcp_socket_delete、nx_tcp_socket_disconnect,
  • nx_tcp_socket_info_get、_tcp_socket_receive
  • nx_tcp_socket_receive_queue_max_set、nx_tcp_socket_send,
  • nx_tcp_socket_state_wait

nx_tcp_client_socket_port_get

获取与客户端 TCP 套接字绑定的端口号

原型

UINT nx_tcp_client_socket_port_get(
    NX_TCP_SOCKET *socket_ptr,
    UINT *port_ptr);

说明

此服务会检索与套接字关联的端口号;如果在绑定套接字时指定了 NX_ANY_PORT,它对查找 NetX 分配的端口非常有用。

参数

  • socket_ptr:此指针指向先前创建的 TCP 套接字实例。
  • port_ptr:此指针指向返回端口号的目标。 有效端口号为 1 到 0xFFFF。

返回值

  • * NX_SUCCESS:(0x00) 绑定套接字成功
  • * NX_NOT_BOUND:(0x24) 此套接字未与任何端口绑定
  • NX_PTR_ERROR:(0x07) 套接字指针或端口返回指针无效。
  • NX_CALLER_ERROR (0x11) 此服务的调用方无效。
  • NX_NOT_ENABLED (0x14) 尚未启用此组件。

允许调用自

线程数

可以抢占

示例

/* Get the port number of previously created and bound client
    socket. */
status = nx_tcp_client_socket_port_get(&client_socket, &port);

/* If status is NX_SUCCESS, the port variable contains the port this
    socket is bound to. */

另请参阅

  • nx_tcp_client_socket_bind、nx_tcp_client_socket_connect,
  • nx_tcp_client_socket_unbind、nx_tcp_enable、nx_tcp_free_port_find,
  • nx_tcp_info_get、nx_tcp_server_socket_accept,
  • nx_tcp_server_socket_listen、nx_tcp_server_socket_relisten,
  • nx_tcp_server_socket_unaccept、nx_tcp_server_socket_unlisten,
  • nx_tcp_socket_bytes_available、nx_tcp_socket_create,
  • nx_tcp_socket_delete、nx_tcp_socket_disconnect,
  • nx_tcp_socket_info_get、nx_tcp_socket_receive,
  • nx_tcp_socket_receive_queue_max_set、nx_tcp_socket_send,
  • nx_tcp_socket_state_wait

nx_tcp_client_socket_unbind

取消 TCP 客户端套接字与 TCP 端口之间的绑定

原型

UINT nx_tcp_client_socket_unbind(NX_TCP_SOCKET *socket_ptr);

说明

此服务用于解除 TCP 客户端套接字与 TCP 端口之间的绑定。 如有其他线程在等待将其他套接字与同一端口号绑定,则第一个挂起的线程会与该端口绑定。

参数

  • socket_ptr:此指针指向先前创建的 TCP 套接字实例。

返回值

  • NX_SUCCESS:(0x00) 取消绑定套接字成功。
  • NX_NOT_BOUND:(0x24) 套接字未与任何端口绑定。
  • NX_NOT_CLOSED:(0x35) 套接字尚未断开连接。
  • NX_PTR_ERROR:(0x07) 套接字指针无效。
  • NX_CALLER_ERROR (0x11) 此服务的调用方无效。
  • NX_NOT_ENABLED (0x14) 尚未启用此组件。

允许调用自

线程数

可以抢占

示例

/* Unbind a previously created and bound client TCP socket. */
status = nx_tcp_client_socket_unbind(&client_socket);

/* If status is NX_SUCCESS, the client socket is no longer
    bound. */

另请参阅

  • nx_tcp_client_socket_bind、nx_tcp_client_socket_connect,
  • nx_tcp_client_socket_port_get、x_tcp_enable、x_tcp_free_port_find,
  • nx_tcp_info_get、nx_tcp_server_socket_accept,
  • nx_tcp_server_socket_listen、nx_tcp_server_socket_relisten,
  • nx_tcp_server_socket_unaccept、nx_tcp_server_socket_unlisten,
  • nx_tcp_socket_bytes_available、nx_tcp_socket_create,
  • nx_tcp_socket_delete、nx_tcp_socket_disconnect,
  • nx_tcp_socket_info_get、nx_tcp_socket_receive,
  • nx_tcp_socket_receive_queue_max_set、nx_tcp_socket_send,
  • nx_tcp_socket_state_wait

nx_tcp_enable

启用 NetX 的 TCP 组件

原型

UINT nx_tcp_enable(NX_IP *ip_ptr);

说明

此服务用于启用 NetX 的传输控制协议 (TCP) 组件。 启用后,应用程序可建立 TCP 连接。

参数

  • ip_ptr:指向以前所创建 IP 实例的指针。

返回值

  • NX_SUCCESS:(0x00) 启用 TCP 成功。
  • NX_ALREADY_ENABLED:(0x15) TCP 已启用。
  • NX_PTR_ERROR:(0x07) IP 指针无效。
  • NX_CALLER_ERROR (0x11) 此服务的调用方无效。

允许调用自

初始化、线程、计时器

可以抢占

示例

/* Enable TCP on a previously created IP instance ip_0. */
status = nx_tcp_enable(&ip_0);

/* If status is NX_SUCCESS, TCP is enabled on the IP instance. */

另请参阅

  • nx_tcp_client_socket_bind、nx_tcp_client_socket_connect,
  • nx_tcp_client_socket_port_get、nx_tcp_client_socket_unbind,
  • nx_tcp_free_port_find、nx_tcp_info_get、nx_tcp_server_socket_accept,
  • nx_tcp_server_socket_listen、nx_tcp_server_socket_relisten,
  • nx_tcp_server_socket_unaccept、nx_tcp_server_socket_unlisten,
  • nx_tcp_socket_bytes_available、nx_tcp_socket_create,
  • nx_tcp_socket_delete、nx_tcp_socket_disconnect,
  • nx_tcp_socket_info_get、nx_tcp_socket_receive,
  • nx_tcp_socket_receive_queue_max_set、nx_tcp_socket_send,
  • nx_tcp_socket_state_wait

nx_tcp_free_port_find

查找下一个可用的 TCP 端口

原型

UINT nx_tcp_free_port_find(
    NX_IP *ip_ptr,
    UINT port, UINT *free_port_ptr);

说明

此服务尝试从应用程序提供的端口开始查找可用的未绑定 TCP 端口。 如果搜索恰好达到最大端口值 0xFFFF,搜索逻辑会从头开始。 如果搜索成功,则会在 free_port_ptr 所指向的变量中返回可用端口。

可以从另一个线程调用此服务,并返回相同的端口。 若要防止出现这种争用情况,应用程序可能希望将此服务和实际的客户端套接字绑定置于互斥体的保护之下。

参数

  • ip_ptr:指向以前所创建 IP 实例的指针。
  • port:充当搜索起点的端口号(1 到 0xFFFF)。
  • free_port_ptr:指向目标可用端口返回值的指针。

返回值

  • NX_SUCCESS:(0x00) 查找可用端口成功。
  • NX_NO_FREE_PORTS:(0x45) 找不到可用的端口。
  • NX_PTR_ERROR:(0x07) IP 指针无效。
  • NX_CALLER_ERROR:(0x11) 此服务的调用方无效。
  • NX_NOT_ENABLED (0x14) 尚未启用此组件。
  • NX_INVALID_PORT:(0x46) 指定的端口号无效。

允许调用自

线程数

可以抢占

示例

/* Locate a free TCP port, starting at port 12, on a previously
    created IP instance. */
status = nx_tcp_free_port_find(&ip_0, 12, &free_port);

/* If status is NX_SUCCESS, "free_port" contains the next free port
    on the IP instance. */

另请参阅

  • nx_tcp_client_socket_bind、nx_tcp_client_socket_connect,
  • nx_tcp_client_socket_port_get、nx_tcp_client_socket_unbind,
  • nx_tcp_enable、nx_tcp_info_get、nx_tcp_server_socket_accept,
  • nx_tcp_server_socket_listen、nx_tcp_server_socket_relisten,
  • nx_tcp_server_socket_unaccept、nx_tcp_server_socket_unlisten,
  • nx_tcp_socket_bytes_available、nx_tcp_socket_create,
  • nx_tcp_socket_delete、nx_tcp_socket_disconnect,
  • nx_tcp_socket_info_get、nx_tcp_socket_receive,
  • nx_tcp_socket_receive_queue_max_set、nx_tcp_socket_send,
  • nx_tcp_socket_state_wait

nx_tcp_info_get

检索 TCP 活动的相关信息

原型

UINT nx_tcp_info_get(
    NX_IP *ip_ptr,
    ULONG *tcp_packets_sent,
    ULONG *tcp_bytes_sent,
    ULONG *tcp_packets_received,
    ULONG *tcp_bytes_received,
    ULONG *tcp_invalid_packets,
    ULONG *tcp_receive_packets_dropped,
    ULONG *tcp_checksum_errors,
    ULONG *tcp_connections,
    ULONG *tcp_disconnections,
    ULONG *tcp_connections_dropped,
    ULONG *tcp_retransmit_packets);

说明

此服务检索所指定 IP 实例的 TCP 活动相关信息。

如果目标指针为 NX_NULL,则不会将该特定信息返回给调用方

参数

  • ip_ptr:指向以前所创建 IP 实例的指针。
  • tcp_packets_sent:此指针指向已发送的 TCP 数据包总数的目标。
  • tcp_bytes_sent:此指针指向已发送的 TCP 总字节数的目标。
  • tcp_packets_received:此指针指向已接收的 TCP 数据包总数的目标。
  • tcp_bytes_received:此指针指向已接收的 TCP 总字节数的目标。
  • tcp_invalid_packets:此指针指向无效 TCP 数据包总数的目标。
  • tcp_receive_packets_dropped:此指针指向已丢弃的 TCP 接收数据包总数的目标。
  • tcp_checksum_errors:此指针指向有校验和错误的 TCP 数据包总数的目标。
  • tcp_connections:此指针指向 TCP 连接总数的目标。
  • tcp_disconnections:此指针指向 TCP 断开连接总数的目标。
  • tcp_connections_dropped:此指针指向已丢弃的 TCP 连接总数的目标。
  • tcp_retransmit_packets:此指针指向重新传输的 TCP 数据包总数的目标。

返回值

  • NX_SUCCESS:(0x00) 检索 TCP 信息成功。
  • NX_PTR_ERROR:(0x07) IP 指针无效。
  • NX_CALLER_ERROR (0x11) 此服务的调用方无效。
  • NX_NOT_ENABLED (0x14) 尚未启用此组件。

允许调用自

初始化、线程

可以抢占

示例

/* Retrieve TCP information from previously created IP Instance ip_0. */
status = nx_tcp_info_get(&ip_0,
    &tcp_packets_sent,
    &tcp_bytes_sent,
    &tcp_packets_received,
    &tcp_bytes_received,
    &tcp_invalid_packets,
    &tcp_receive_packets_dropped,
    &tcp_checksum_errors,
    &tcp_connections,
    &tcp_disconnections
    &tcp_connections_dropped,
    &tcp_retransmit_packets);

/* If status is NX_SUCCESS, TCP information was retrieved. */

另请参阅

  • nx_tcp_client_socket_bind、nx_tcp_client_socket_connect,
  • nx_tcp_client_socket_port_get、nx_tcp_client_socket_unbind,
  • nx_tcp_enable、nx_tcp_free_port_find、nx_tcp_server_socket_accept,
  • nx_tcp_server_socket_listen、nx_tcp_server_socket_relisten,
  • nx_tcp_server_socket_unaccept、nx_tcp_server_socket_unlisten,
  • nx_tcp_socket_bytes_available、nx_tcp_socket_create,
  • nx_tcp_socket_delete、nx_tcp_socket_disconnect,
  • nx_tcp_socket_info_get、nx_tcp_socket_receive,
  • nx_tcp_socket_receive_queue_max_set、nx_tcp_socket_send,
  • nx_tcp_socket_state_wait

nx_tcp_server_socket_accept

接受 TCP 连接

原型

UINT nx_tcp_server_socket_accept(
    NX_TCP_SOCKET *socket_ptr, 
    ULONG wait_option);

说明

此服务用于接受(或准备接受)针对先前设置进行侦听的端口的 TCP 客户端套接字连接请求。 在应用程序调用侦听或重新侦听服务之后,或者在客户端连接实际存在时调用侦听回调例程之后,可以立即调用此服务。 如果无法立即建立连接,此服务会根据提供的等待选项挂起。

不再需要该连接之后,应用程序必须调用 nx_tcp_server_socket_unaccept,以删除服务器套接字与服务器端口的绑定

*应用程序回调例程是从 IP 的帮助程序线程中调用的。

参数

  • socket_ptr:指向 TCP 服务器套接字控制块的指针。
  • wait_option:定义建立该连接时此服务的行为方式。 等待选项的定义如下:
    • NX_NO_WAIT (0x00000000)
    • NX_WAIT_FOREVER (0xFFFFFFFF)
    • 以时钟周期为单位的超时值(0x00000001 到 0xFFFFFFFE)

返回值

  • NX_SUCCESS:(0x00) 接受 TCP 服务器套接字(被动连接)成功。
  • NX_NOT_LISTEN_STATE:(0x36) 提供的服务器套接字未处于侦听状态。
  • NX_IN_PROGRESS (0x37) 未指定等待,正在尝试连接。
  • NX_WAIT_ABORTED (0x1A) 已通过调用 tx_thread_wait_abort 中止所请求的挂起。
  • NX_PTR_ERROR (0x07) 套接字指针错误。
  • NX_CALLER_ERROR (0x11) 此服务的调用方无效。
  • NX_NOT_ENABLED (0x14) 尚未启用此组件。

允许调用自

初始化、线程

可以抢占

示例

NX_PACKET_POOL my_pool;
NX_IP my_ip;
NX_TCP_SOCKET server_socket;
void port_12_connect_request(NX_TCP_SOCKET *socket_ptr, UINT port)
{
    /* Simply set the semaphore to wake up the server thread. */
    tx_semaphore_put(&port_12_semaphore);
}

void port_12_disconnect_request(NX_TCP_SOCKET *socket_ptr)
{
    /* The client has initiated a disconnect on this socket. This
    example doesn't use this callback. */
}

void port_12_server_thread_entry(ULONG id)
{
    NX_PACKET *my_packet;
    UINT status, i;
    /* Assuming that:
        "port_12_semaphore" has already been created with an
        initial count of 0 "my_ip" has already been created and the
        link is enabled "my_pool" packet pool has already been
        created */

    /* Create the server socket. */
    nx_tcp_socket_create(&my_ip, &server_socket,
        "Port 12 Server Socket",
        NX_IP_NORMAL, NX_FRAGMENT_OKAY,
        NX_IP_TIME_TO_LIVE, 100,
        NX_NULL, port_12_disconnect_request);

    /* Setup server listening on port 12. */
    nx_tcp_server_socket_listen(&my_ip, 12, &server_socket, 5,
        port_12_connect_request);

    /* Loop to process 5 server connections, sending
        "Hello_and_Goodbye" to each client and then disconnecting.*/
    for (i = 0; i < 5; i++)
    {
        /* Get the semaphore that indicates a client connection
            request is present. */
        tx_semaphore_get(&port_12_semaphore, TX_WAIT_FOREVER);

        /* Wait for 200 ticks for the client socket connection to
            complete.*/
        status = nx_tcp_server_socket_accept(&server_socket, 200);

        /* Check for a successful connection. */
        if (status == NX_SUCCESS)
        {
            /* Allocate a packet for the "Hello_and_Goodbye"
                message */
            nx_packet_allocate(&my_pool, &my_packet, NX_TCP_PACKET,
                NX_WAIT_FOREVER);

            /* Place "Hello_and_Goodbye" in the packet. */
            nx_packet_data_append(my_packet, "Hello_and_Goodbye",
                sizeof("Hello_and_Goodbye"),
                &my_pool, NX_WAIT_FOREVER);

            /* Send "Hello_and_Goodbye" to client. */
            nx_tcp_socket_send(&server_socket, my_packet, 200);

            /* Check for an error. */
            if (status)
            {
                /* Error, release the packet. */
                nx_packet_release(my_packet);
            }

            /* Now disconnect the server socket from the client. */
            nx_tcp_socket_disconnect(&server_socket, 200);
        }

        /* Unaccept the server socket. Note that unaccept is called
            even if disconnect or accept fails. */
        nx_tcp_server_socket_unaccept(&server_socket);

        /* Setup server socket for listening with this socket
            again. */
        nx_tcp_server_socket_relisten(&my_ip, 12, &server_socket);
    }

    /* We are now done so unlisten on server port 12. */
    nx_tcp_server_socket_unlisten(&my_ip, 12);

    /* Delete the server socket. */
    nx_tcp_socket_delete(&server_socket);
}

另请参阅

  • nx_tcp_client_socket_bind、nx_tcp_client_socket_connect,
  • nx_tcp_client_socket_port_get、nx_tcp_client_socket_unbind,
  • nx_tcp_enable、nx_tcp_free_port_find、nx_tcp_info_get,
  • nx_tcp_server_socket_listen、nx_tcp_server_socket_relisten,
  • nx_tcp_server_socket_unaccept、nx_tcp_server_socket_unlisten,
  • nx_tcp_socket_bytes_available、nx_tcp_socket_create,
  • nx_tcp_socket_delete、nx_tcp_socket_disconnect,
  • nx_tcp_socket_info_get、nx_tcp_socket_receive,
  • nx_tcp_socket_receive_queue_max_set、nx_tcp_socket_send,
  • nx_tcp_socket_state_wait

nx_tcp_server_socket_listen

允许侦听 TCP 端口上的客户端连接

原型

UINT nx_tcp_server_socket_listen(
    NX_IP *ip_ptr, 
    UINT port,
    NX_TCP_SOCKET *socket_ptr,
    UINT listen_queue_size,
    VOID (*listen_callback)(NX_TCP_SOCKET *socket_ptr, UINT port));

说明

此服务用于允许侦听所指定 TCP 端口上的客户端连接请求。 接收到客户端连接请求时,提供的服务器套接字就会与指定的端口绑定,并调用所提供的侦听回调函数。

侦听回调例程的处理完全由应用程序决定, 其中可能包含唤醒应用程序线程的逻辑,以便随后执行接受操作。 如果应用程序已有线程在接受此套接字的处理时挂起,则可能不需要侦听回调例程。

如果应用程序希望在同一端口上处理其他客户端连接,则必须使用可用的套接字(处于关闭状态的套接字)调用 nx_tcp_server_socket_relisten,以建立下一个连接。 在调用重新侦听服务之前,其他客户端连接会进行排队。 超过最大队列深度时,就会丢弃最早的连接请求,以将新连接请求排入队列。 最大队列深度由此服务指定。

应用程序回调例程是从内部 IP 帮助器线程中调用的。

参数

  • ip_ptr:指向以前所创建 IP 实例的指针。
  • port:要侦听的端口号(1 到 0xFFFF)。
  • socket_ptr:此指针指向用于连接的套接字。
  • listen_queue_size:可排入队列的客户端连接请求数。
  • listen_callback:接收到连接时要调用的应用程序函数。 如果指定了 NULL,则会禁用侦听回调功能。

返回值

  • NX_SUCCESS:(0x00) 启用 TCP 端口侦听成功。
  • NX_MAX_LISTEN (0x33) 没有更多的侦听请求结构可供使用。 nx_api.h 中的常量 NX_MAX_LISTEN_REQUESTS 定义了活动侦听请求数上限。
  • NX_NOT_CLOSED (0x35) 提供的服务器套接字未处于关闭状态。
  • NX_ALREADY_BOUND:(0x22) 提供的服务器套接字已与某个端口绑定。
  • NX_DUPLICATE_LISTEN:(0x34) 此端口已有活动的侦听请求。
  • NX_INVALID_PORT:(0x46) 指定了无效的端口。
  • NX_PTR_ERROR:(0x07) IP 或套接字指针无效。
  • NX_CALLER_ERROR:(0x11) 此服务的调用方无效。
  • NX_NOT_ENABLED (0x14) 尚未启用此组件。

允许调用自

线程数

可以抢占

示例

NX_PACKET_POOL my_pool;
NX_IP my_ip;
NX_TCP_SOCKET server_socket;

void port_12_connect_request(NX_TCP_SOCKET *socket_ptr, UINT port)
{
    /* Simply set the semaphore to wake up the server thread.*/
    tx_semaphore_put(&port_12_semaphore);
}

void port_12_disconnect_request(NX_TCP_SOCKET *socket_ptr)
{
    /* The client has initiated a disconnect on this socket.
        This example doesn't use this callback. */
}

void port_12_server_thread_entry(ULONG id)
{
    NX_PACKET *my_packet;
    UINT status, i;

    /* Assuming that:
        "port_12_semaphore" has already been created with an
        initial count of 0 "my_ip" has already been created
        and the link is enabled "my_pool" packet pool has already
        been created.
    */

    /* Create the server socket. */
    nx_tcp_socket_create(&my_ip, &server_socket, "Port 12 Server
        Socket",
        NX_IP_NORMAL, NX_FRAGMENT_OKAY,
        NX_IP_TIME_TO_LIVE, 100,
        NX_NULL, port_12_disconnect_request);

    /* Setup server listening on port 12. */
    nx_tcp_server_socket_listen(&my_ip, 12, &server_socket, 5,
        port_12_connect_request);

    /* Loop to process 5 server connections, sending
        "Hello_and_Goodbye" to
        each client and then disconnecting. */
    for (i = 0; i < 5; i++)
    {
        /* Get the semaphore that indicates a client connection
            request is present. */
        tx_semaphore_get(&port_12_semaphore, TX_WAIT_FOREVER);

    /* Wait for 200 ticks for the client socket connection
        to complete. */
    status = nx_tcp_server_socket_accept(&server_socket, 200);

    /* Check for a successful connection. */
    if (status == NX_SUCCESS)
    {
        /* Allocate a packet for the "Hello_and_Goodbye"
            message. */
        nx_packet_allocate(&my_pool, &my_packet, NX_TCP_PACKET,
            NX_WAIT_FOREVER);

        /* Place "Hello_and_Goodbye" in the packet. */
        nx_packet_data_append(my_packet, "Hello_and_Goodbye",
            sizeof("Hello_and_Goodbye"),
            &my_pool,
            NX_WAIT_FOREVER);

        /* Send "Hello_and_Goodbye" to client. */
        nx_tcp_socket_send(&server_socket, my_packet, 200);

        /* Check for an error. */
        if (status)
        {
            /* Error, release the packet. */
            nx_packet_release(my_packet);
        }
        /* Now disconnect the server socket from the client. */
        nx_tcp_socket_disconnect(&server_socket, 200);
    }

    /* Unaccept the server socket. Note that unaccept is called
        even if disconnect or accept fails. */
    nx_tcp_server_socket_unaccept(&server_socket);

    /* Setup server socket for listening with this socket
    again. */
    nx_tcp_server_socket_relisten(&my_ip, 12, &server_socket);
}

/* We are now done so unlisten on server port 12. */
nx_tcp_server_socket_unlisten(&my_ip, 12);

/* Delete the server socket. */
nx_tcp_socket_delete(&server_socket);

另请参阅

  • nx_tcp_client_socket_bind、nx_tcp_client_socket_connect,
  • nx_tcp_client_socket_port_get、nx_tcp_client_socket_unbind,
  • nx_tcp_enable、nx_tcp_free_port_find、nx_tcp_info_get,
  • nx_tcp_server_socket_accept、nx_tcp_server_socket_relisten,
  • nx_tcp_server_socket_unaccept、nx_tcp_server_socket_unlisten,
  • nx_tcp_socket_bytes_available、nx_tcp_socket_create,
  • nx_tcp_socket_delete、nx_tcp_socket_disconnect,
  • nx_tcp_socket_info_get、nx_tcp_socket_receive,
  • nx_tcp_socket_receive_queue_max_set、nx_tcp_socket_send,
  • nx_tcp_socket_state_wait

nx_tcp_server_socket_relisten

重新侦听 TCP 端口上的客户端连接

原型

UINT nx_tcp_server_socket_relisten(
    NX_IP *ip_ptr, 
    UINT port,
    NX_TCP_SOCKET *socket_ptr);

说明

在先前已设置侦听的端口上接收到连接之后,就会调用此服务。 此服务的主要目的是,提供新的服务器套接字来用于下一个客户端连接。 如果已有连接请求在排队,调用此服务期间会立即处理该连接。

存在这个新服务器套接字的连接时,也会调用原始侦听请求所指定的回调例程。

参数

  • ip_ptr:指向以前所创建 IP 实例的指针。
  • port:要重新侦听的端口号(1 到 0xFFFF)。
  • socket_ptr:要用于下一客户端连接的套接字。

返回值

  • NX_SUCCESS:(0x00) 重新侦听 TCP 端口成功。
  • NX_NOT_CLOSED:(0x35) 提供的服务器套接字未处于关闭状态。
  • NX_ALREADY_BOUND:(0x22) 提供的服务器套接字已与某个端口绑定。
  • NX_INVALID_RELISTEN:(0x47) 此端口已有一个有效的套接字指针,或者指定的端口没有活动的侦听请求。
  • NX_CONNECTION_PENDING:(0x48) 与 NX_SUCCESS 相同,只不过存在已排队的连接请求,并且已在此调用期间处理该请求。
  • NX_INVALID_PORT:(0x46) 指定了无效的端口。
  • NX_PTR_ERROR:(0x07) IP 或侦听回调指针无效。
  • NX_CALLER_ERROR (0x11) 此服务的调用方无效。
  • NX_NOT_ENABLED (0x14) 尚未启用此组件。

允许调用自

线程数

可以抢占

示例

NX_PACKET_POOL my_pool;
NX_IP my_ip;
NX_TCP_SOCKET server_socket;

void port_12_connect_request(NX_TCP_SOCKET *socket_ptr, UINT port)
{
    /* Simply set the semaphore to wake up the server thread.*/
    tx_semaphore_put(&port_12_semaphore);
    }

void port_12_disconnect_request(NX_TCP_SOCKET *socket_ptr)
{
    /* The client has initiated a disconnect on this socket. This
    example doesn't use this callback. */
}

void port_12_server_thread_entry(ULONG id)
{
    NX_PACKET *my_packet;
    UINT status, i;

    /* Assuming that:
    "port_12_semaphore" has already been created with an initial
        count of 0.
        "my_ip" has already been created and the link is enabled.
        "my_pool" packet pool has already been created. */

    /* Create the server socket. */
    nx_tcp_socket_create(&my_ip, &server_socket,
        "Port 12 Server Socket",
        NX_IP_NORMAL, NX_FRAGMENT_OKAY,
        NX_IP_TIME_TO_LIVE, 100,
        NX_NULL,
        port_12_disconnect_request);

    /* Setup server listening on port 12. */
    nx_tcp_server_socket_listen(&my_ip, 12, &server_socket, 5,
        port_12_connect_request);
    /* Loop to process 5 server connections, sending
        "Hello_and_Goodbye" to each client then disconnecting. */
    for (i = 0; i < 5; i++)
    {
        /* Get the semaphore that indicates a client connection
        request is present. */
        tx_semaphore_get(&port_12_semaphore, TX_WAIT_FOREVER);

        /* Wait for 200 ticks for the client socket connection to
        complete. */
        status = nx_tcp_server_socket_accept(&server_socket, 200);

        /* Check for a successful connection. */
        if (status == NX_SUCCESS)
        {
            /* Allocate a packet for the "Hello_and_Goodbye"
            message. */
            nx_packet_allocate(&my_pool, &my_packet, NX_TCP_PACKET,
                NX_WAIT_FOREVER);

            /* Place "Hello_and_Goodbye" in the packet. */
            nx_packet_data_append(my_packet, "Hello_and_Goodbye",
                sizeof("Hello_and_Goodbye"),
                &my_pool, NX_WAIT_FOREVER);

            /* Send "Hello_and_Goodbye" to client. */
            nx_tcp_socket_send(&server_socket, my_packet, 200);

            /* Check for an error. */
            if (status)
            {
                /* Error, release the packet. */
                nx_packet_release(my_packet);
            }

            /* Now disconnect the server socket from the client. */
            nx_tcp_socket_disconnect(&server_socket, 200);
        }

        /* Unaccept the server socket. Note that unaccept is
        called even if disconnect or accept fails. */
        nx_tcp_server_socket_unaccept(&server_socket);

        /* Setup server socket for listening with this socket
        again. */
        nx_tcp_server_socket_relisten(&my_ip, 12, &server_socket);
    }
    /* We are now done so unlisten on server port 12. */
    nx_tcp_server_socket_unlisten(&my_ip, 12);

    /* Delete the server socket. */
    nx_tcp_socket_delete(&server_socket);
}

另请参阅

  • nx_tcp_client_socket_bind、nx_tcp_client_socket_connect,
  • nx_tcp_client_socket_port_get、nx_tcp_client_socket_unbind,
  • nx_tcp_enable、nx_tcp_free_port_find、nx_tcp_info_get,
  • nx_tcp_server_socket_accept、nx_tcp_server_socket_listen,
  • nx_tcp_server_socket_unaccept、nx_tcp_server_socket_unlisten,
  • nx_tcp_socket_bytes_available、nx_tcp_socket_create,
  • nx_tcp_socket_delete、nx_tcp_socket_disconnect,
  • nx_tcp_socket_info_get、nx_tcp_socket_receive,
  • nx_tcp_socket_receive_queue_max_set、nx_tcp_socket_send,
  • nx_tcp_socket_state_wait

nx_tcp_server_socket_unaccept

删除套接字与侦听端口的关联

原型

UINT nx_tcp_server_socket_unaccept(NX_TCP_SOCKET *socket_ptr);

说明

此服务用于删除此服务器套接字与所指定服务器端口之间的关联。 在断开连接之后,或者在不成功的接受调用之后,应用程序必须调用此服务。

参数

  • socket_ptr:此指针指向先前设置的服务器套接字实例。

返回值

  • NX_SUCCESS:(0x00) 取消接受服务器套接字成功。
  • NX_NOT_LISTEN_STATE:(0x36) 服务器套接字处于不正确的状态,可能未断开连接。
  • NX_PTR_ERROR (0x07) 套接字指针无效。
  • NX_CALLER_ERROR:(0x11) 此服务的调用方无效。
  • NX_NOT_ENABLED (0x14) 尚未启用此组件。

允许调用自

线程数

可以抢占

示例

NX_PACKET_POOL my_pool;
NX_IP my_ip;
NX_TCP_SOCKET server_socket;

void port_12_connect_request(NX_TCP_SOCKET *socket_ptr, UINT port)
{
    /* Simply set the semaphore to wake up the server thread. */
    tx_semaphore_put(&port_12_semaphore);
}

void port_12_disconnect_request(NX_TCP_SOCKET *socket_ptr)
{
    /* The client has initiated a disconnect on this socket. This example
    doesn't use this callback. */
}

void port_12_server_thread_entry(ULONG id)
{
    NX_PACKET *my_packet;
    UINT status, i;

    /* Assuming that:
        "port_12_semaphore" has already been created with an initial count
        of 0 "my_ip" has already been created and the link is enabled
        "my_pool" packet pool has already been created
        */

    /* Create the server socket. */
    nx_tcp_socket_create(&my_ip, &server_socket,
        "Port 12 Server Socket",NX_IP_NORMAL, NX_FRAGMENT_OKAY,
        NX_IP_TIME_TO_LIVE, 100,NX_NULL,
        port_12_disconnect_request);

    /* Setup server listening on port 12. */
    nx_tcp_server_socket_listen(&my_ip, 12, &server_socket, 5,
        port_12_connect_request);

    /* Loop to process 5 server connections, sending "Hello_and_Goodbye"
        to each client and then disconnecting. */
    for (i = 0; i < 5; i++)
    {
        /* Get the semaphore that indicates a client connection request
            is present. */
        tx_semaphore_get(&port_12_semaphore, TX_WAIT_FOREVER);

        /* Wait for 200 ticks for the client socket connection to
            complete.*/
        status = nx_tcp_server_socket_accept(&server_socket, 200);

        /* Check for a successful connection. */
        if (status == NX_SUCCESS)
        {
            /* Allocate a packet for the "Hello_and_Goodbye" message. */
            nx_packet_allocate(&my_pool, &my_packet, NX_TCP_PACKET,
                NX_WAIT_FOREVER);

            /* Place "Hello_and_Goodbye" in the packet. */
            nx_packet_data_append(my_packet,
                "Hello_and_Goodbye",sizeof("Hello_and_Goodbye"),
                &my_pool, NX_WAIT_FOREVER);

            /* Send "Hello_and_Goodbye" to client. */
            nx_tcp_socket_send(&server_socket, my_packet, 200);

            /* Check for an error. */
            if (status)
            {
                /* Error, release the packet. */
                nx_packet_release(my_packet);
            }

            /* Now disconnect the server socket from the client. */
            nx_tcp_socket_disconnect(&server_socket, 200);
        }

        /* Unaccept the server socket. Note that unaccept is called even
            if disconnect or accept fails. */
        nx_tcp_server_socket_unaccept(&server_socket);

        /* Setup server socket for listening with this socket again. */
        nx_tcp_server_socket_relisten(&my_ip, 12, &server_socket);
    }
    /* We are now done so unlisten on server port 12. */
    nx_tcp_server_socket_unlisten(&my_ip, 12);

    /* Delete the server socket. */
    nx_tcp_socket_delete(&server_socket);
}

另请参阅

  • nx_tcp_client_socket_bind、nx_tcp_client_socket_connect,
  • nx_tcp_client_socket_port_get、nx_tcp_client_socket_unbind、nx_tcp_enable,
  • nx_tcp_free_port_find、nx_tcp_info_get、nx_tcp_server_socket_accept,
  • nx_tcp_server_socket_listen、nx_tcp_server_socket_relisten,
  • nx_tcp_server_socket_unlisten、nx_tcp_socket_bytes_available,
  • nx_tcp_socket_create、nx_tcp_socket_delete、nx_tcp_socket_disconnect,
  • nx_tcp_socket_info_get、nx_tcp_socket_receive,
  • nx_tcp_socket_receive_queue_max_set、nx_tcp_socket_send,
  • nx_tcp_socket_state_wait

nx_tcp_server_socket_unlisten

禁止侦听 TCP 端口上的客户端连接

原型

UINT nx_tcp_server_socket_unlisten(NX_IP *ip_ptr, UINT port);

说明

此服务用于禁止侦听所指定 TCP 端口上的客户端连接请求。

参数

  • ip_ptr:指向以前所创建 IP 实例的指针。
  • port:要禁止侦听的端口号(0 到 0xFFFF)。

返回值

  • NX_SUCCESS:(0x00) 禁用 TCP 侦听成功。
  • NX_ENTRY_NOT_FOUND:(0x16) 指定的端口未启用侦听。
  • NX_INVALID_PORT:(0x46) 指定了无效的端口。
  • NX_PTR_ERROR:(0x07) IP 指针无效。
  • NX_CALLER_ERROR:(0x11) 此服务的调用方无效。
  • NX_NOT_ENABLED (0x14) 尚未启用此组件。

允许调用自

线程数

可以抢占

示例

NX_PACKET_POOL my_pool;
NX_IP my_ip;
NX_TCP_SOCKET server_socket;

void port_12_connect_request(NX_TCP_SOCKET *socket_ptr, UINT port)
{
    /* Simply set the semaphore to wake up the server thread. */
    tx_semaphore_put(&port_12_semaphore);
}

void port_12_disconnect_request(NX_TCP_SOCKET *socket_ptr)
{
    /* The client has initiated a disconnect on this socket. This example
    doesn't use this callback.*/
}

void port_12_server_thread_entry(ULONG id)
{
    NX_PACKET *my_packet;
    UINT status, i;

    /* Assuming that:
        "port_12_semaphore" has already been created with an initial count
        of 0 "my_ip" has already been created and the link is enabled
        "my_pool" packet pool has already been created
    */

    /* Create the server socket. */
    nx_tcp_socket_create(&my_ip, &server_socket, "Port 12 Server Socket",
        NX_IP_NORMAL, NX_FRAGMENT_OKAY,
        NX_IP_TIME_TO_LIVE, 100,
        NX_NULL, port_12_disconnect_request);

    /* Setup server listening on port 12. */
    nx_tcp_server_socket_listen(&my_ip, 12, &server_socket, 5,
        port_12_connect_request);

    /* Loop to process 5 server connections, sending "Hello_and_Goodbye" to
        each client and then disconnecting. */
    for (i = 0; i < 5; i++)
    {
        /* Get the semaphore that indicates a client connection request is
            present. */
        tx_semaphore_get(&port_12_semaphore, TX_WAIT_FOREVER);

        /* Wait for 200 ticks for the client socket connection to complete.*/
        status = nx_tcp_server_socket_accept(&server_socket, 200);

        /* Check for a successful connection. */
        if (status == NX_SUCCESS)
        {
            /* Allocate a packet for the "Hello_and_Goodbye" message. */
            nx_packet_allocate(&my_pool, &my_packet, NX_TCP_PACKET,
                NX_WAIT_FOREVER);

            /* Place "Hello_and_Goodbye" in the packet. */
            nx_packet_data_append(my_packet, "Hello_and_Goodbye",
                sizeof("Hello_and_Goodbye"), &my_pool,
                NX_WAIT_FOREVER);

            /* Send "Hello_and_Goodbye" to client. */
            nx_tcp_socket_send(&server_socket, my_packet, 200);

            /* Check for an error. */
            if (status)
            {
                /* Error, release the packet. */
                nx_packet_release(my_packet);
            }
            /* Now disconnect the server socket from the client. */
            nx_tcp_socket_disconnect(&server_socket, 200);
        }
        /* Unaccept the server socket. Note that unaccept is called even if
        disconnect or accept fails. */
        nx_tcp_server_socket_unaccept(&server_socket);

        /* Setup server socket for listening with this socket again. */
        nx_tcp_server_socket_relisten(&my_ip, 12, &server_socket);
    }
    /* We are now done so unlisten on server port 12. */
    nx_tcp_server_socket_unlisten(&my_ip, 12);

    /* Delete the server socket. */
    nx_tcp_socket_delete(&server_socket);
}

另请参阅

  • nx_tcp_client_socket_bind、nx_tcp_client_socket_connect,
  • nx_tcp_client_socket_port_get、nx_tcp_client_socket_unbind,
  • nx_tcp_enable、nx_tcp_free_port_find、nx_tcp_info_get,
  • nx_tcp_server_socket_accept、nx_tcp_server_socket_listen,
  • nx_tcp_server_socket_relisten、nx_tcp_server_socket_unaccept,
  • nx_tcp_socket_bytes_available、nx_tcp_socket_create,
  • nx_tcp_socket_delete、nx_tcp_socket_disconnect,
  • nx_tcp_socket_info_get、nx_tcp_socket_receive,
  • nx_tcp_socket_receive_queue_max_set、nx_tcp_socket_send,
  • nx_tcp_socket_state_wait

nx_tcp_socket_bytes_available

检索可供检索的字节数

原型

UINT nx_tcp_socket_bytes_available(
    NX_TCP_SOCKET *socket_ptr,
    ULONG *bytes_available);

说明

此服务用于获取指定的 TCP 套接字可供检索的字节数。 请注意,必须已连接该 TCP 套接字。

参数

  • socket_ptr:此指针指向先前创建并连接的 TCP 套接字。
  • bytes_available:此指针指向可用字节数的目标。

返回值

  • NX_SUCCESS:(0x00) 服务执行成功。 可供读取的字节数会返回给调用方。
  • NX_NOT_CONNECTED:(0x38) 套接字未处于已连接状态。
  • NX_PTR_ERROR:(0x07) 指针无效。
  • NX_NOT_ENABLED:(0x14) TCP 未启用。
  • NX_CALLER_ERROR:(0x11) 此服务的调用方无效。

允许调用自

线程数

可以抢占

示例

/* Get the bytes available for retrieval on the specified socket. */
status = nx_tcp_socket_bytes_available(&my_socket,
    &bytes_available);

/* Is status = NX_SUCCESS, the available bytes is returned in
    bytes_available. */

另请参阅

  • nx_tcp_client_socket_bind、nx_tcp_client_socket_connect,
  • nx_tcp_client_socket_port_get、nx_tcp_client_socket_unbind,
  • nx_tcp_enable、nx_tcp_free_port_find、nx_tcp_info_get,
  • nx_tcp_server_socket_accept、nx_tcp_server_socket_listen,
  • nx_tcp_server_socket_relisten、nx_tcp_server_socket_unaccept,
  • nx_tcp_server_socket_unlisten、nx_tcp_socket_create,
  • nx_tcp_socket_delete、nx_tcp_socket_disconnect,
  • nx_tcp_socket_info_get、nx_tcp_socket_receive,
  • nx_tcp_socket_receive_queue_max_set、nx_tcp_socket_send,
  • nx_tcp_socket_state_wait

nx_tcp_socket_create

创建 TCP 客户端或服务器套接字

原型

UINT nx_tcp_socket_create(
    NX_IP *ip_ptr, 
    NX_TCP_SOCKET *socket_ptr,
    CHAR *name, ULONG type_of_service, 
    ULONG fragment,
    UINT time_to_live, 
    ULONG window_size,
    VOID (*urgent_data_callback)(NX_TCP_SOCKET *socket_ptr),
    VOID (*disconnect_callback)(NX_TCP_SOCKET *socket_ptr));

说明

此服务用于为指定的 IP 实例创建 TCP 客户端或服务器套接字。

应用程序回调例程是从与此 IP 实例关联的线程中调用的。

参数

  • ip_ptr:指向以前所创建 IP 实例的指针。
  • socket_ptr:指向新的 TCP 套接字控制块的指针。
  • name:此 TCP 套接字的应用程序名称。
  • type_of_service:定义用于传输的服务类型,合法值如下所示:
    • NX_IP_NORMAL (0x00000000)
    • NX_IP_MIN_DELAY (0x00100000)
    • NX_IP_MAX_DATA (0x00080000)
    • NX_IP_MAX_RELIABLE (0x00040000)
    • NX_IP_MIN_COST (0x00020000)
  • fragment:指定是否允许进行 IP 分段。 如果指定 NX_FRAGMENT_OKAY (0x0),则允许进行 IP 分段。 如果指定 NX_DONT_FRAGMENT (0x4000),则会禁止进行 IP 分段。
  • time_to_live:指定一个 8 位的值,用于定义此数据包在被丢弃之前可通过的路由器数目。 默认值由 NX_IP_TIME_TO_LIVE 指定。
  • window_size:定义此套接字的接收队列中允许的最大字节数
  • urgent_data_callback:在接收流中每次检测到紧急数据时都会调用的应用程序函数。 如果此值为 NX_NULL,则会忽略紧急数据。
  • disconnect_callback:在连接另一端的套接字每次发出断开连接时都会调用的应用程序函数。 如果此值为 NX_NULL,则会禁用断开连接回调函数。

返回值

  • NX_SUCCESS:(0x00) 创建 TCP 客户端套接字成功。
  • NX_OPTION_ERROR:(0x0A) 服务类型、分段、窗口大小或生存时间选项无效。
  • NX_PTR_ERROR:(0x07) IP 或套接字指针无效。
  • NX_CALLER_ERROR:(0x11) 此服务的调用方无效。
  • NX_NOT_ENABLED (0x14) 尚未启用此组件。

允许调用自

初始化和线程

可以抢占

示例

/* Create a TCP client socket on the previously created IP instance,
    with normal delivery, IP fragmentation enabled, 0x80 time to
    live, a 200-byte receive window, no urgent callback routine, and
    the "client_disconnect" routine to handle disconnection initiated
    from the other end of the connection. */
status = nx_tcp_socket_create(&ip_0, &client_socket,
    "Client Socket",
    NX_IP_NORMAL, NX_FRAGMENT_OKAY,
    0x80, 200, NX_NULL
    client_disconnect);

/* If status is NX_SUCCESS, the client socket is created and ready
    to be bound. */

另请参阅

  • nx_tcp_client_socket_bind、nx_tcp_client_socket_connect,
  • nx_tcp_client_socket_port_get、nx_tcp_client_socket_unbind,
  • nx_tcp_enable、nx_tcp_free_port_find、nx_tcp_info_get,
  • nx_tcp_server_socket_accept、nx_tcp_server_socket_listen,
  • nx_tcp_server_socket_relisten、nx_tcp_server_socket_unaccept,
  • nx_tcp_server_socket_unlisten、nx_tcp_socket_bytes_available,
  • nx_tcp_socket_delete、nx_tcp_socket_disconnect,
  • nx_tcp_socket_info_get、nx_tcp_socket_receive,
  • nx_tcp_socket_receive_queue_max_set、nx_tcp_socket_send,
  • nx_tcp_socket_state_wait

nx_tcp_socket_delete

删除 TCP 套接字

原型

UINT nx_tcp_socket_delete(NX_TCP_SOCKET *socket_ptr);

说明

此服务用于删除先前创建的 TCP 套接字。 如果该套接字仍处于绑定或连接状态,则此服务会返回错误代码。

参数

  • socket_ptr:先前创建的 TCP 套接字

返回值

  • NX_SUCCESS:(0x00) 删除套接字成功。
  • NX_NOT_CREATED:(0x27) 套接字尚未创建。
  • NX_STILL_BOUND:(0x42) 套接字仍处于绑定状态。
  • NX_PTR_ERROR:(0x07) 套接字指针无效。
  • NX_CALLER_ERROR (0x11) 此服务的调用方无效。
  • NX_NOT_ENABLED (0x14) 尚未启用此组件。

允许调用自

线程数

可以抢占

示例

/* Delete a previously created TCP client socket. */
status = nx_tcp_socket_delete(&client_socket);

/* If status is NX_SUCCESS, the client socket is deleted. */

另请参阅

  • nx_tcp_client_socket_bind、nx_tcp_client_socket_connect,
  • nx_tcp_client_socket_port_get、nx_tcp_client_socket_unbind,
  • nx_tcp_enable、nx_tcp_free_port_find、nx_tcp_info_get,
  • nx_tcp_server_socket_accept、nx_tcp_server_socket_listen,
  • nx_tcp_server_socket_relisten、nx_tcp_server_socket_unaccept,
  • nx_tcp_server_socket_unlisten、nx_tcp_socket_bytes_available,
  • nx_tcp_socket_create、nx_tcp_socket_disconnect,
  • nx_tcp_socket_info_get、nx_tcp_socket_receive,
  • nx_tcp_socket_receive_queue_max_set、nx_tcp_socket_send,
  • nx_tcp_socket_state_wait

nx_tcp_socket_disconnect

断开客户端和服务器套接字连接

原型

UINT nx_tcp_socket_disconnect(
    NX_TCP_SOCKET *socket_ptr,
    ULONG wait_option);

说明

此服务用于断开已建立的客户端或服务器套接字连接。 在服务器套接字断开连接后应该有一个取消接受请求,而断开连接的客户端套接字会处于准备好接受其他连接请求的状态。 如果断开连接过程无法立即完成,则该服务会根据提供的等待选项挂起。

参数

  • socket_ptr:此指针指向先前连接的客户端或服务器套接字实例。
  • wait_option:定义正在断开连接时此服务的行为方式。 等待选项的定义如下:
    • NX_NO_WAIT (0x00000000)
    • NX_WAIT_FOREVER (0xFFFFFFFF)
    • 以时钟周期为单位的超时值(0x00000001 到 0xFFFFFFFE)

返回值

  • NX_SUCCESS:(0x00) 断开套接字连接成功。
  • NX_NOT_CONNECTED:(0x38) 指定的套接字未连接。
  • NX_IN_PROGRESS:(0x37) 断开连接正在进行,未指定等待。
  • NX_WAIT_ABORTED:(0x1A) 已通过调用 tx_thread_wait_abort 中止所请求的挂起。
  • NX_PTR_ERROR:(0x07) 套接字指针无效。
  • NX_CALLER_ERROR (0x11) 此服务的调用方无效。
  • NX_NOT_ENABLED (0x14) 尚未启用此组件。

允许调用自

线程数

可以抢占

示例

/* Disconnect from a previously established connection and wait a
    maximum of 400 timer ticks. */
status = nx_tcp_socket_disconnect(&client_socket, 400);

/* If status is NX_SUCCESS, the previously connected socket (either
    as a result of the client socket connect or the server accept) is
    disconnected. */

另请参阅

  • nx_tcp_client_socket_bind、nx_tcp_client_socket_connect,
  • nx_tcp_client_socket_port_get、nx_tcp_client_socket_unbind,
  • nx_tcp_enable、nx_tcp_free_port_find、nx_tcp_info_get,
  • nx_tcp_server_socket_accept、nx_tcp_server_socket_listen,
  • nx_tcp_server_socket_relisten、nx_tcp_server_socket_unaccept,
  • nx_tcp_server_socket_unlisten、nx_tcp_socket_bytes_available,
  • nx_tcp_socket_create、nx_tcp_socket_delete、nx_tcp_socket_info_get,
  • nx_tcp_socket_receive、nx_tcp_socket_receive_queue_max_set,
  • nx_tcp_socket_send、nx_tcp_socket_state_wait

nx_tcp_socket_disconnect_complete_notify

安装 TCP 断开连接完成通知回调函数

原型

UINT nx_tcp_socket_disconnect_complete_notify(
    NX_TCP_SOCKET *socket_ptr,
    VOID (*tcp_disconnect_complete_notify)
    (NX_TCP_SOCKET *socket_ptr));

说明

此服务用于注册一个回调函数,套接字断开连接操作完成后就会调用该函数。 如果 NetX 是在定义了 NX_ENABLE_EXTENDED_NOTIFY_SUPPORT 选项的情况下生成的,则该 TCP 套接字断开连接完成回调函数可供使用。

参数

  • socket_ptr:此指针指向先前连接的客户端或服务器套接字实例。
  • tcp_disconnect_complete_notify:要安装的回调函数。

返回值

  • NX_SUCCESS (0x00) 已成功注册回调函数。
  • NX_NOT_SUPPORTED (0x4B) 扩展通知功能未生成到 NetX 库中
  • NX_PTR_ERROR (0x07) 套接字指针无效。
  • NX_CALLER_ERROR (0x11) 此服务的调用方无效。
  • NX_NOT_ENABLED:(0x14) TCP 功能未启用。

允许调用自

初始化、线程

可以抢占

示例

/* Install the disconnect complete notify callback function. */
status = nx_tcp_socket_disconnect_complete_notify(&client_socket,
    callback);

另请参阅

  • nx_tcp_enable、nx_tcp_socket_create、nx_tcp_socket_establish_notify,
  • nx_tcp_socket_mss_get、nx_tcp_socket_mss_peer_get,
  • nx_tcp_socket_mss_set、nx_tcp_socket_peer_info_get,
  • nx_tcp_socket_receive_notify、nx_tcp_socket_timed_wait_callback,
  • nx_tcp_socket_transmit_configure,
  • nx_tcp_socket_window_update_notify_set

nx_tcp_socket_establish_notify

设置 TCP 建立通知回调函数

原型

UINT nx_tcp_socket_establish_notify(
    NX_TCP_SOCKET *socket_ptr,
    VOID (*tcp_establish_notify)(NX_TCP_SOCKET *socket_ptr));

说明

此服务用于注册一个回调函数,TCP 套接字建立连接后会调用该函数。 如果 NetX 是在定义了 NX_ENABLE_EXTENDED_NOTIFY_SUPPORT 选项的情况下生成的,则 TCP 套接字建立回调函数可用。

参数

  • socket_ptr:此指针指向先前连接的客户端或服务器套接字实例。
  • tcp_establish_notify:建立 TCP 连接后调用的回调函数。

返回值

  • NX_SUCCESS (0x00) 成功设置通知函数。
  • NX_NOT_SUPPORTED (0x4B) 扩展通知功能未生成到 NetX 库中
  • NX_PTR_ERROR (0x07) 套接字指针无效。
  • NX_CALLER_ERROR (0x11) 此服务的调用方无效。
  • NX_NOT_ENABLED:(0x14) 应用程序尚未启用 TCP。

允许调用自

线程数

可以抢占

示例

/* Set the function pointer "callback" as the notify function NetX
will call when the connection is in the established state. */
status = nx_tcp_socket_establish_notify(&client_socket, callback);

另请参阅

  • nx_tcp_enable、nx_tcp_socket_create,
  • nx_tcp_socket_disconnect_complete_notify、nx_tcp_socket_mss_get,
  • nx_tcp_socket_mss_peer_get、nx_tcp_socket_mss_set,
  • nx_tcp_socket_peer_info_get、nx_tcp_socket_receive_notify,
  • nx_tcp_socket_timed_wait_callback、nx_tcp_socket_transmit_configure,
  • nx_tcp_socket_window_update_notify_set

nx_tcp_socket_info_get

检索 TCP 套接字活动的相关信息

原型

UINT nx_tcp_socket_info_get(
    NX_TCP_SOCKET *socket_ptr,
    ULONG *tcp_packets_sent,
    ULONG *tcp_bytes_sent,
    ULONG *tcp_packets_received,
    ULONG *tcp_bytes_received,
    ULONG *tcp_retransmit_packets,
    ULONG *tcp_packets_queued,
    ULONG *tcp_checksum_errors,
    ULONG *tcp_socket_state,
    ULONG *tcp_transmit_queue_depth,
    ULONG *tcp_transmit_window,
    ULONG *tcp_receive_window);

说明

此服务检索所指定 TCP 套接字实例的 TCP 套接字活动相关信息。

如果目标指针为 NX_NULL,则不会将该特定信息返回给调用方

参数

  • socket_ptr:此指针指向先前创建的 TCP 套接字实例。
  • tcp_packets_sent:此指针指向在套接字上发送的 TCP 数据包总数的目标。
  • tcp_bytes_sent:此指针指向在套接字上发送的 TCP 总字节数的目标。
  • tcp_packets_received:此指针指向在套接字上接收的 TCP 数据包总数的目标。
  • tcp_bytes_received:此指针指向在套接字上接收的 TCP 总字节数的目标。
  • tcp_retransmit_packets:此指针指向重新传输的 TCP 数据包总数的目标。
  • tcp_packets_queued:此指针指向在套接字上排队的 TCP 数据包总数的目标。
  • tcp_checksum_errors:此指针指向套接字上有校验和错误的 TCP 数据包总数的目标。
  • tcp_socket_state:此指针指向套接字当前状态的目标。
  • tcp_transmit_queue_depth:此指针指向仍在排队等待 ACK 的传输数据包总数的目标。
  • tcp_transmit_window:此指针指向当前传输窗口大小的目标。
  • tcp_receive_window:此指针指向当前接收窗口大小的目标。

返回值

  • NX_SUCCESS:(0x00) 检索 TCP 套接字信息成功。
  • NX_PTR_ERROR (0x07) 套接字指针无效。
  • NX_CALLER_ERROR:(0x11) 此服务的调用方无效。
  • NX_NOT_ENABLED (0x14) 尚未启用此组件。

返回值

/* Retrieve TCP socket information from previously created socket_0.*/
status = nx_tcp_socket_info_get(&socket_0,
    &tcp_packets_sent,
    &tcp_bytes_sent,
    &tcp_packets_received,
    &tcp_bytes_received,
    &tcp_retransmit_packets,
    &tcp_packets_queued,
    &tcp_checksum_errors,
    &tcp_socket_state,
    &tcp_transmit_queue_depth,
    &tcp_transmit_window,
    &tcp_receive_window);

/* If status is NX_SUCCESS, TCP socket information was retrieved. */

允许调用自

初始化、线程

可以抢占

示例

/* Retrieve TCP socket information from previously created socket_0.*/
status = nx_tcp_socket_info_get(&socket_0,
    &tcp_packets_sent,
    &tcp_bytes_sent,
    &tcp_packets_received,
    &tcp_bytes_received,
    &tcp_retransmit_packets,
    &tcp_packets_queued,
    &tcp_checksum_errors,
    &tcp_socket_state,
    &tcp_transmit_queue_depth,
    &tcp_transmit_window,
    &tcp_receive_window);

/* If status is NX_SUCCESS, TCP socket information was retrieved. */

另请参阅

  • nx_tcp_client_socket_bind、nx_tcp_client_socket_connect,
  • nx_tcp_client_socket_port_get、nx_tcp_client_socket_unbind,
  • nx_tcp_enable、nx_tcp_free_port_find、nx_tcp_info_get,
  • nx_tcp_server_socket_accept、nx_tcp_server_socket_listen,
  • nx_tcp_server_socket_relisten、nx_tcp_server_socket_unaccept,
  • nx_tcp_server_socket_unlisten、nx_tcp_socket_bytes_available,
  • nx_tcp_socket_create、nx_tcp_socket_delete、nx_tcp_socket_disconnect,
  • nx_tcp_socket_receive、nx_tcp_socket_receive_queue_max_set,
  • nx_tcp_socket_send、nx_tcp_socket_state_wait

nx_tcp_socket_mss_get

获取套接字的 MSS

原型

UINT nx_tcp_socket_mss_get(
    NX_TCP_SOCKET *socket_ptr, 
    ULONG *mss);

说明

此服务用于检索所指定套接字的本地最大段大小 (MSS)。

参数

  • socket_ptr:此指针指向先前创建的套接字。
  • mss:用于返回 MSS 的目标。

返回值

  • NX_SUCCESS:(0x00) 获取 MSS 成功。
  • NX_PTR_ERROR:(0x07) 套接字指针或 MSS 目标指针无效。
  • NX_NOT_ENABLED:(0x14) TCP 未启用。
  • NX_CALLER_ERROR:(0x11) 调用方不是线程或初始化。

允许调用自

初始化和线程

可以抢占

示例

/* Get the MSS for the socket "my_socket". */
status = nx_tcp_socket_mss_get(&my_socket, &mss_value);

/* If status is NX_SUCCESS, the "mss_value" variable contains the
    socket's current MSS value. */

另请参阅

  • nx_tcp_enable、nx_tcp_socket_create,
  • nx_tcp_socket_disconnect_complete_notify,
  • nx_tcp_socket_establish_notify、nx_tcp_socket_mss_peer_get,
  • nx_tcp_socket_mss_set、nx_tcp_socket_peer_info_get,
  • nx_tcp_socket_receive_notify、nx_tcp_socket_timed_wait_callback,
  • nx_tcp_socket_transmit_configure,
  • nx_tcp_socket_window_update_notify_set

nx_tcp_socket_mss_peer_get

获取对等 TCP 套接字的 MSS

原型

UINT nx_tcp_socket_mss_peer_get(
    NX_TCP_SOCKET *socket_ptr, 
    ULONG *mss);

说明

此服务用于检索对等套接字所播发的最大段大小 (MSS)。

参数

  • socket_ptr:此指针指向先前创建并连接的套接字。
  • mss:用于返回 MSS 的目标。

返回值

  • NX_SUCCESS:(0x00) 获取对等 MSS 成功。
  • NX_PTR_ERROR:(0x07) 套接字指针或 MSS 目标指针无效。
  • NX_NOT_ENABLED:(0x14) TCP 未启用。
  • NX_CALLER_ERROR:(0x11) 调用方不是线程或初始化。

允许调用自

线程数

可以抢占

示例

/* Get the MSS of the connected peer to the socket "my_socket". */
status = nx_tcp_socket_mss_peer_get(&my_socket, &mss_value);

/* If status is NX_SUCCESS, the "mss_value" variable contains the
    socket peer’s advertised MSS value. */

另请参阅

  • nx_tcp_enable、nx_tcp_socket_create,
  • nx_tcp_socket_disconnect_complete_notify,
  • nx_tcp_socket_establish_notify、nx_tcp_socket_mss_get,
  • nx_tcp_socket_mss_set、nx_tcp_socket_peer_info_get,
  • nx_tcp_socket_receive_notify、nx_tcp_socket_timed_wait_callback,
  • nx_tcp_socket_transmit_configure,
  • nx_tcp_socket_window_update_notify_set

nx_tcp_socket_mss_set

设置套接字的 MSS

原型

UINT nx_tcp_socket_mss_set(
    NX_TCP_SOCKET *socket_ptr, 
    ULONG mss);

说明

此服务用于设置所指定套接字的最大段大小 (MSS)。 请注意,MSS 值必须小于网络接口 IP MTU,从而为 IP 和 TCP 标头留出空间。

应该在 TCP 套接字开始连接过程之前使用此服务。 如果在建立 TCP 连接后使用此服务,则新值不会对该连接产生任何影响。

参数

  • socket_ptr:此指针指向先前创建的套接字。
  • mss:要设置的 MSS 值。

返回值

  • NX_SUCCESS:(0x00) 设置 MSS 成功。
  • NX_SIZE_ERROR:(0x09) 指定的 MSS 值太大。
  • NX_NOT_CONNECTED:(0x38) 尚未建立 TCP 连接
  • NX_PTR_ERROR (0x07) 套接字指针无效。
  • NX_NOT_ENABLED:(0x14) TCP 未启用。
  • NX_CALLER_ERROR:(0x11) 调用方不是线程或初始化。

允许调用自

初始化和线程

可以抢占

示例

/* Set the MSS of the socket "my_socket" to 1000 bytes. */
status = nx_tcp_socket_mss_set(&my_socket, 1000);

/* If status is NX_SUCCESS, the MSS of "my_socket" is 1000 bytes. */

另请参阅

  • nx_tcp_enable、nx_tcp_socket_create,
  • nx_tcp_socket_disconnect_complete_notify,
  • nx_tcp_socket_establish_notify、nx_tcp_socket_mss_get,
  • nx_tcp_socket_mss_peer_get、nx_tcp_socket_peer_info_get,
  • nx_tcp_socket_receive_notify、nx_tcp_socket_timed_wait_callback,
  • nx_tcp_socket_transmit_configure,
  • nx_tcp_socket_window_update_notify_set

nx_tcp_socket_peer_info_get

检索对等 TCP 套接字的相关信息

原型

UINT nx_tcp_socket_peer_info_get(
    NX_TCP_SOCKET *socket_ptr,
    ULONG *peer_ip_address, 
    ULONG *peer_port);

说明

此服务用于通过 IP 网络检索已连接的 TCP 套接字的对等 IP 地址和端口信息。

参数

  • socket_ptr:指向先前创建的 TCP 套接字的指针。
  • peer_ip_address:此指针指向对等 IP 地址的目标,以主机字节顺序表示。
  • peer_port:此指针指向对等端口号的目标,以主机字节顺序表示。

返回值

  • NX_SUCCESS:(0x00) 服务执行成功。 对等 IP 地址和端口号会返回给调用方。
  • NX_NOT_CONNECTED:(0x38) 套接字未处于已连接状态。
  • NX_PTR_ERROR:(0x07) 指针无效。
  • NX_NOT_ENABLED:(0x14) TCP 未启用。
  • NX_CALLER_ERROR (0x11) 此服务的调用方无效。

允许调用自

线程数

可以抢占

示例

/* Obtain peer IP address and port on the specified TCP socket. */
status = nx_tcp_socket_peer_info_get(&my_socket, &peer_ip_address,
    &peer_port);

/* If status = NX_SUCCESS, the data was successfully obtained. */

另请参阅

  • nx_tcp_enable、nx_tcp_socket_create,
  • nx_tcp_socket_disconnect_complete_notify,
  • nx_tcp_socket_establish_notify、nx_tcp_socket_mss_get,
  • nx_tcp_socket_mss_peer_get、nx_tcp_socket_mss_set,
  • nx_tcp_socket_receive_notify、nx_tcp_socket_timed_wait_callback,
  • nx_tcp_socket_transmit_configure,
  • nx_tcp_socket_window_update_notify_set

nx_tcp_socket_receive

从 TCP 套接字接收数据

原型

UINT nx_tcp_socket_receive(
    NX_TCP_SOCKET *socket_ptr,
    NX_PACKET **packet_ptr, 
    ULONG wait_option);

说明

此服务用于从指定的套接字接收 TCP 数据。 如果指定的套接字上没有数据在排队,调用方会根据提供的等待选项挂起。

如果返回了 NX_SUCCESS,则应用程序负责在不再需要所收到的数据包时将其释放。

参数

  • socket_ptr:此指针指向先前创建的 TCP 套接字实例。
  • packet_ptr:此指针指向 TCP 数据包指针。
  • wait_option:定义此套接字上当前没有数据排队时此服务的行为方式。 等待选项的定义如下:
    • NX_NO_WAIT (0x00000000)
    • NX_WAIT_FOREVER (0xFFFFFFFF)
    • 以时钟周期为单位的超时值(0x00000001 到 0xFFFFFFFE)

返回值

  • NX_SUCCESS:(0x00) 接收套接字数据成功。
  • NX_NOT_BOUND:(0x24) 套接字尚未绑定。
  • NX_NO_PACKET:(0x01) 未收到任何数据。
  • NX_WAIT_ABORTED:(0x1A) 已通过调用 tx_thread_wait_abort 中止所请求的挂起。
  • NX_NOT_CONNECTED:(0x38) 该套接字不再处于已连接状态。
  • NX_PTR_ERROR:(0x07) 套接字指针或返回数据包指针无效。
  • NX_CALLER_ERROR (0x11) 此服务的调用方无效。
  • NX_NOT_ENABLED (0x14) 尚未启用此组件。

允许调用自

线程数

可以抢占

示例

/* 从先前创建并连接的 TCP 客户端套接字接收数据包。 如果无数据包可用,请等待 200 个计时器时钟周期,然后放弃。 */ status = nx_tcp_socket_receive(&client_socket, &packet_ptr, 200);

/* 如果状态为 NX_SUCCESS,则“packet_ptr”指向接收到的数据包。 */

另请参阅

  • nx_tcp_client_socket_bind、nx_tcp_client_socket_connect,
  • nx_tcp_client_socket_port_get、nx_tcp_client_socket_unbind,
  • nx_tcp_enable、nx_tcp_free_port_find、nx_tcp_info_get,
  • nx_tcp_server_socket_accept、nx_tcp_server_socket_listen,
  • nx_tcp_server_socket_relisten、nx_tcp_server_socket_unaccept,
  • nx_tcp_server_socket_unlisten、nx_tcp_socket_bytes_available,
  • nx_tcp_socket_create、nx_tcp_socket_delete、nx_tcp_socket_disconnect,
  • nx_tcp_socket_info_get、nx_tcp_socket_receive_queue_max_set,
  • nx_tcp_socket_send、nx_tcp_socket_state_wait

nx_tcp_socket_receive_notify

在收到数据包时通知应用程序

原型

UINT nx_tcp_socket_receive_notify(
    NX_TCP_SOCKET *socket_ptr,
    VOID (*tcp_receive_notify) (NX_TCP_SOCKET *socket_ptr));

说明

此服务使用应用程序所指定的回调函数来配置接收通知函数指针。 每当在套接字上收到一个或多个数据包时,就会调用该回调函数。 如果提供了 NX_NULL 指针,则会禁用通知功能。

参数

  • socket_ptr:此指针指向 TCP 套接字。
  • tcp_receive_notify:在套接字上收到一个或多个数据包时调用的应用程序回调函数指针。

返回值

  • NX_SUCCESS:(0x00) 套接字接收通知成功。
  • NX_PTR_ERROR (0x07) 套接字指针无效。
  • NX_CALLER_ERROR (0x11) 此服务的调用方无效。
  • NX_NOT_ENABLED:(0x14) TCP 功能未启用。

允许调用自

初始化、线程

可以抢占

示例

/* Setup a receive packet callback function for the "client_socket"
socket. */
status = nx_tcp_socket_receive_notify(&client_socket,
    my_receive_notify);

/* If status is NX_SUCCESS, NetX will call the function named
    "my_receive_notify" whenever one or more packets are received for
    "client_socket". */

另请参阅

  • nx_tcp_enable、nx_tcp_socket_create,
  • nx_tcp_socket_disconnect_complete_notify,
  • nx_tcp_socket_establish_notify、nx_tcp_socket_mss_get,
  • nx_tcp_socket_mss_peer_get、nx_tcp_socket_mss_set,
  • nx_tcp_socket_peer_info_get、nx_tcp_socket_timed_wait_callback,
  • nx_tcp_socket_transmit_configure,
  • nx_tcp_socket_window_update_notify_set

nx_tcp_socket_send

通过 TCP 套接字发送数据

原型

UINT nx_tcp_socket_send(
    NX_TCP_SOCKET *socket_ptr,
    NX_PACKET *packet_ptr, 
    ULONG wait_option);

说明

此服务用于通过先前连接的 TCP 套接字发送 TCP 数据。 如果接收方最近一次播发的窗口大小低于此请求,则此服务可以根据指定的等待选项挂起。 此服务可保证不会将大于 MSS 的数据包数据发送到 IP 层。

除非返回了错误,否则应用程序不应在此调用后释放该数据包。 这样做会导致不可预知的结果,因为网络驱动程序也会在传输后尝试释放该数据包。

参数

  • socket_ptr:此指针指向先前连接的 TCP 套接字实例。
  • packet_ptr:TCP 数据包指针。
  • wait_option:定义当请求大于接收方窗口大小时此服务的行为方式。 等待选项的定义如下:
    • NX_NO_WAIT (0x00000000)
    • NX_WAIT_FOREVER (0xFFFFFFFF)
    • 以时钟周期为单位的超时值(0x00000001 到 0xFFFFFFFE)

返回值

  • NX_SUCCESS:(0x00) 套接字发送成功。
  • NX_NOT_BOUND:(0x24) 套接字未与任何端口绑定。
  • NX_NO_INTERFACE_ADDRESS:(0x50) 找不到合适的传出接口。
  • NX_NOT_CONNECTED:(0x38) 套接字不再处于已连接状态。
  • NX_WINDOW_OVERFLOW:(0x39) 请求大于接收方所播发的窗口大小(以字节为单位)。
  • NX_WAIT_ABORTED:(0x1A) 已通过调用 tx_thread_wait_abort 中止所请求的挂起。
  • NX_INVALID_PACKET:(0x12) 数据包未分配。
  • NX_TX_QUEUE_DEPTH:(0x49) 已达到最大传输队列深度。
  • NX_OVERFLOW:(0x03) 数据包追加指针无效。
  • NX_PTR_ERROR (0x07) 套接字指针无效。
  • NX_CALLER_ERROR:(0x11) 此服务的调用方无效。
  • NX_NOT_ENABLED (0x14) 尚未启用此组件。
  • NX_UNDERFLOW:(0x02) 数据包前置指针无效。

允许调用自

线程数

可以抢占

示例

/* Send a packet out on the previously created and connected TCP
    socket. If the receive window on the other side of the connection
    is less than the packet size, wait 200 timer ticks before giving up. */
status = nx_tcp_socket_send(&client_socket, packet_ptr, 200);

/* If status is NX_SUCCESS, the packet has been sent! */

另请参阅

  • nx_tcp_client_socket_bind、nx_tcp_client_socket_connect,
  • nx_tcp_client_socket_port_get、nx_tcp_client_socket_unbind,
  • nx_tcp_enable、nx_tcp_free_port_find、nx_tcp_info_get,
  • nx_tcp_server_socket_accept、nx_tcp_server_socket_listen,
  • nx_tcp_server_socket_relisten、nx_tcp_server_socket_unaccept,
  • nx_tcp_server_socket_unlisten、nx_tcp_socket_bytes_available,
  • nx_tcp_socket_create、nx_tcp_socket_delete、nx_tcp_socket_disconnect,
  • nx_tcp_socket_info_get、nx_tcp_socket_receive,
  • nx_tcp_socket_receive_queue_max_set、nx_tcp_socket_state_wait

nx_tcp_socket_state_wait

等待 TCP 套接字进入特定状态

原型

UINT nx_tcp_socket_state_wait(
    NX_TCP_SOCKET *socket_ptr,
    UINT desired_state, 
    ULONG wait_option);

说明

此服务用于等待套接字进入所需状态。 如果该套接字未处于所需状态,则此服务会根据提供的等待选项挂起。

参数

  • socket_ptr:此指针指向先前连接的 TCP 套接字实例。
  • desired_state:所需的 TCP 状态。 有效的 TCP 套接字状态定义如下:
    • NX_TCP_CLOSED (0x01)
    • NX_TCP_LISTEN_STATE (0x02)
    • NX_TCP_SYN_SENT (0x03)
    • NX_TCP_SYN_RECEIVED (0x04)
    • NX_TCP_ESTABLISHED (0x05)
    • NX_TCP_CLOSE_WAIT (0x06)
    • NX_TCP_FIN_WAIT_1 (0x07)
    • NX_TCP_FIN_WAIT_2 (0x08)
    • NX_TCP_CLOSING (0x09)
    • NX_TCP_TIMED_WAIT (0x0A)
    • NX_TCP_LAST_ACK (0x0B)
  • wait_option:定义所请求的状态不存在时此服务的行为方式。 等待选项的定义如下:
    • NX_NO_WAIT (0x00000000)
    • NX_WAIT_FOREVER (0xFFFFFFFF)
    • 以时钟周期为单位的超时值(0x00000001 到 0xFFFFFFFE)

返回值

  • NX_SUCCESS:(0x00) 等待状态成功。
  • NX_PTR_ERROR (0x07) 套接字指针无效。
  • NX_NOT_SUCCESSFUL:(0x43) 状态在指定的等待时间内不存在。
  • NX_WAIT_ABORTED:(0x1A) 已通过调用 tx_thread_wait_abort 中止所请求的挂起。
  • NX_CALLER_ERROR (0x11) 此服务的调用方无效。
  • NX_NOT_ENABLED (0x14) 尚未启用此组件。
  • NX_OPTION_ERROR:(0x0A) 所需的套接字状态无效。

允许调用自

线程数

可以抢占

示例

/* Wait 300 timer ticks for the previously created socket to enter
    the established state in the TCP state machine. */
status = nx_tcp_socket_state_wait(&client_socket,
    NX_TCP_ESTABLISHED, 300);

/* If status is NX_SUCCESS, the socket is now in the established
    state! */

另请参阅

  • nx_tcp_client_socket_bind、nx_tcp_client_socket_connect,
  • nx_tcp_client_socket_port_get、nx_tcp_client_socket_unbind,
  • nx_tcp_enable、nx_tcp_free_port_find、nx_tcp_info_get,
  • nx_tcp_server_socket_accept、nx_tcp_server_socket_listen,
  • nx_tcp_server_socket_relisten、nx_tcp_server_socket_unaccept,
  • nx_tcp_server_socket_unlisten、nx_tcp_socket_bytes_available,
  • nx_tcp_socket_create、nx_tcp_socket_delete、nx_tcp_socket_disconnect,
  • nx_tcp_socket_info_get、nx_tcp_socket_receive,
  • nx_tcp_socket_receive_queue_max_set、nx_tcp_socket_send

nx_tcp_socket_timed_wait_callback

安装用于定时等待状态的回调

原型

UINT nx_tcp_socket_timed_wait_callback(
    NX_TCP_SOCKET *socket_ptr,
    VOID (*tcp_timed_wait_callback) (NX_TCP_SOCKET *socket_ptr));

说明

此服务用于注册一个回调函数,当 TCP 套接字处于定时等待状态时,会调用该函数。 若要使用此服务,必须在定义了 NX_ENABLE_EXTENDED_NOTIFY 选项的情况下生成 NetX 库。

参数

  • socket_ptr:此指针指向先前连接的客户端或服务器套接字实例。
  • tcp_timed_wait_callback:定时等待回调函数

返回值

  • NX_SUCCESS (0x00) 成功注册回调函数套接字
  • NX_NOT_SUPPORTED (0x4B) NetX 库是在未启用扩展通知功能的情况下生成的。
  • NX_PTR_ERROR (0x07) 套接字指针无效。
  • NX_CALLER_ERROR:(0x11) 此服务的调用方无效。
  • NX_NOT_ENABLED:(0x14) TCP 功能未启用。

允许调用自

初始化、线程

可以抢占

示例

/* Install the timed wait callback function */
nx_tcp_socket_timed_wait_callback(&client_socket, callback);

另请参阅

  • nx_tcp_enable、nx_tcp_socket_create,
  • nx_tcp_socket_disconnect_complete_notify,
  • nx_tcp_socket_establish_notify、nx_tcp_socket_mss_get,
  • nx_tcp_socket_mss_peer_get、nx_tcp_socket_mss_set,
  • nx_tcp_socket_peer_info_get、nx_tcp_socket_receive_notify,
  • nx_tcp_socket_transmit_configure,
  • nx_tcp_socket_window_update_notify_set

nx_tcp_socket_transmit_configure

配置套接字的传输参数

原型

UINT nx_tcp_socket_transmit_configure(
    NX_TCP_SOCKET *socket_ptr,
    ULONG max_queue_depth,
    ULONG timeout,
    ULONG max_retries,
    ULONG timeout_shift);

说明

此服务用于配置所指定 TCP 套接字的各种传输参数。

参数

  • socket_ptr:此指针指向 TCP 套接字。
  • max_queue_depth:允许排队等待传输的数据包最大数量。
  • timeout:在重新发送数据包之前等待 ACK 的 ThreadX 计时器时钟周期数。
  • max_retries:允许的最大重试次数。
  • timeout_shift:用于更改每次后续重试超时时间的值。 值为 0 表示连续重试之间的超时时间相同。 值为 1 表示重试之间的超时时间加倍。

返回值

  • NX_SUCCESS:(0x00) 配置传输套接字成功。
  • NX_PTR_ERROR (0x07) 套接字指针无效。
  • NX_OPTION_ERROR:(0x0a) 队列深度选项无效。
  • NX_CALLER_ERROR:(0x11) 此服务的调用方无效。
  • NX_NOT_ENABLED:(0x14) TCP 功能未启用。

允许调用自

初始化、线程

可以抢占

示例

/* Configure the "client_socket" for a maximum transmit queue depth
    of 12, 100 tick timeouts, a maximum of 20 retries, and a timeout
    double on each successive retry. */
status = nx_tcp_socket_transmit_configure(&client_socket,
    12,100,20, 1);

/* If status is NX_SUCCESS, the socket’s transmit retry has been
    configured. */

另请参阅

  • nx_tcp_enable、nx_tcp_socket_create,
  • nx_tcp_socket_disconnect_complete_notify,
  • nx_tcp_socket_establish_notify、nx_tcp_socket_mss_get,
  • nx_tcp_socket_mss_peer_get、nx_tcp_socket_mss_set,
  • nx_tcp_socket_peer_info_get、nx_tcp_socket_receive_notify,
  • nx_tcp_socket_timed_wait_callback,
  • nx_tcp_socket_window_update_notify_set

nx_tcp_socket_window_update_notify_set

将窗口大小更新告知应用程序

原型

UINT nx_tcp_socket_window_update_notify_set(
    NX_TCP_SOCKET
    *socket_ptr,
    VOID (*tcp_window_update_notify)
    (NX_TCP_SOCKET *socket_ptr));

说明

此服务用于安装套接字窗口更新回调例程。 每当指定的套接字收到指出远程主机窗口大小增加的数据包时,就会自动调用该例程。

参数

  • socket_ptr:指向先前创建的 TCP 套接字的指针。
  • tcp_window_update_notify:要在窗口大小更改时调用的回调例程。 值为 NULL 表示禁用窗口更改更新。

返回值

  • NX_SUCCESS:(0x00) 回调例程已安装在该套接字上。
  • NX_CALLER_ERROR:(0x11) 此服务的调用方无效。
  • NX_PTR_ERROR:(0x07) 指针无效。
  • NX_NOT_ENABLED:(0x14) TCP 功能未启用。

允许调用自

初始化、线程

可以抢占

示例

/* Set the function pointer to the windows update callback after creating the
socket. */
status = nx_tcp_socket_window_update_notify_set(&data_socket,
    my_windows_update_callback);

/* Define the window callback function in the host application. */
void my_windows_update_callback(NX_TCP_SCOCKET *data_socket)
{
    /* Process update on increase TCP transmit socket window size. */
    return;
}

另请参阅

  • nx_tcp_enable、nx_tcp_socket_create,
  • nx_tcp_socket_disconnect_complete_notify,
  • nx_tcp_socket_establish_notify、nx_tcp_socket_mss_get,
  • nx_tcp_socket_mss_peer_get、nx_tcp_socket_mss_set,
  • nx_tcp_socket_peer_info_get、nx_tcp_socket_receive_notify,
  • nx_tcp_socket_timed_wait_callback、nx_tcp_socket_transmit_configure

nx_udp_enable

启用 NetX 的 UDP 组件

原型

UINT nx_udp_enable(NX_IP *ip_ptr);

说明

此服务用于启用 NetX 的用户数据报协议 (UDP) 组件。 启用后,应用程序可发送和接收 UDP 数据报。

参数

  • ip_ptr:指向以前所创建 IP 实例的指针。

返回值

  • NX_SUCCESS:(0x00) 启用 UDP 成功。
  • NX_PTR_ERROR:(0x07) IP 指针无效。
  • NX_CALLER_ERROR (0x11) 此服务的调用方无效。
  • NX_ALREADY_ENABLED:(0x15) 此组件已启用。

允许调用自

初始化、线程、计时器

可以抢占

示例

/* Enable UDP on the previously created IP instance. */
status = nx_udp_enable(&ip_0);

/* If status is NX_SUCCESS, UDP is now enabled on the specified IP
    instance. */

另请参阅

  • nx_udp_free_port_find、nx_udp_info_get、nx_udp_packet_info_extract,
  • nx_udp_socket_bind、nx_udp_socket_bytes_available,
  • nx_udp_socket_checksum_disable、nx_udp_socket_checksum_enable,
  • nx_udp_socket_create、nx_udp_socket_delete、nx_udp_socket_info_get,
  • nx_udp_socket_port_get、nx_udp_socket_receive,
  • nx_udp_socket_receive_notify、nx_udp_socket_send,
  • nx_udp_socket_interface_send、nx_udp_socket_unbind,
  • nx_udp_source_extract

nx_udp_free_port_find

查找下一个可用的 UDP 端口

原型

UINT nx_udp_free_port_find(
    NX_IP *ip_ptr, 
    UINT port,
    UINT *free_port_ptr);

说明

此服务从应用程序提供的端口号开始查找可用的未绑定 UDP 端口。 搜索达到最大端口值 0xFFFF 时,搜索逻辑会从头开始。 如果搜索成功,则会在 free_port_ptr 所指向的变量中返回可用端口。

可以从另一个线程调用此服务,并返回相同的端口。 若要防止出现这种争用情况,应用程序可能希望将此服务和实际的套接字绑定置于互斥体的保护之下。

参数

  • ip_ptr:指向以前所创建 IP 实例的指针。
  • port:充当搜索起点的端口号(1 到 0xFFFF)。
  • free_port_ptr:此指针指向目标可用端口返回变量。

返回值

  • NX_SUCCESS:(0x00) 查找可用端口成功。
  • NX_NO_FREE_PORTS:(0x45) 找不到可用的端口。
  • NX_PTR_ERROR:(0x07) IP 指针无效。
  • NX_CALLER_ERROR (0x11) 此服务的调用方无效。
  • NX_NOT_ENABLED (0x14) 尚未启用此组件。
  • NX_INVALID_PORT:(0x46) 指定的端口号无效。

允许调用自

线程数

可以抢占

示例

/* Locate a free UDP port, starting at port 12, on a previously
    created IP instance. */
status = nx_udp_free_port_find(&ip_0, 12, &free_port);

/* If status is NX_SUCCESS pointer, "free_port" identifies the next
    free UDP port on the IP instance. */

另请参阅

  • nx_udp_enable、nx_udp_info_get、nx_udp_packet_info_extract,
  • nx_udp_socket_bind、nx_udp_socket_bytes_available,
  • nx_udp_socket_checksum_disable、nx_udp_socket_checksum_enable,
  • nx_udp_socket_create、nx_udp_socket_delete、nx_udp_socket_info_get,
  • nx_udp_socket_port_get、nx_udp_socket_receive,
  • nx_udp_socket_receive_notify、nx_udp_socket_send,
  • nx_udp_socket_interface_send、nx_udp_socket_unbind,
  • nx_udp_source_extract

nx_udp_info_get

检索 UDP 活动的相关信息

原型

UINT nx_udp_info_get(
    NX_IP *ip_ptr,
    ULONG *udp_packets_sent,
    ULONG *udp_bytes_sent,
    ULONG *udp_packets_received,
    ULONG *udp_bytes_received,
    ULONG *udp_invalid_packets,
    ULONG *udp_receive_packets_dropped,
    ULONG *udp_checksum_errors);

说明

此服务检索所指定 IP 实例的 UDP 活动相关信息。

如果目标指针为 NX_NULL,则不会将该特定信息返回给调用方

参数

  • ip_ptr:指向以前所创建 IP 实例的指针。
  • udp_packets_sent:此指针指向已发送的 UDP 数据包总数的目标。
  • udp_bytes_sent:此指针指向已发送的 UDP 总字节数的目标。
  • udp_packets_received:此指针指向已接收的 UDP 数据包总数的目标。
  • udp_bytes_received:此指针指向已接收的 UDP 总字节数的目标。
  • udp_invalid_packets:此指针指向无效 UDP 数据包总数的目标。
  • udp_receive_packets_dropped:此指针指向已丢弃的 UDP 接收数据包总数的目标。
  • udp_checksum_errors:此指针指向有校验和错误的 UDP 数据包总数的目标。

返回值

  • NX_SUCCESS:(0x00) 检索 UDP 信息成功。
  • NX_PTR_ERROR:(0x07) IP 指针无效。
  • NX_CALLER_ERROR (0x11) 此服务的调用方无效。
  • NX_NOT_ENABLED (0x14) 尚未启用此组件。

允许调用自

初始化、线程和计时器

可以抢占

示例

/* Retrieve UDP information from previously created IP Instance ip_0. */
status = nx_udp_info_get(&ip_0, &udp_packets_sent,
    &udp_bytes_sent,
    &udp_packets_received,
    &udp_bytes_received,
    &udp_invalid_packets,
    &udp_receive_packets_dropped,
    &udp_checksum_errors);

/* If status is NX_SUCCESS, UDP information was retrieved. */

另请参阅

  • nx_udp_enable、nx_udp_free_port_find、nx_udp_packet_info_extract,
  • nx_udp_socket_bind、nx_udp_socket_bytes_available,
  • nx_udp_socket_checksum_disable、nx_udp_socket_checksum_enable,
  • nx_udp_socket_create、nx_udp_socket_delete、nx_udp_socket_info_get,
  • nx_udp_socket_port_get、nx_udp_socket_receive,
  • nx_udp_socket_receive_notify、nx_udp_socket_send,
  • nx_udp_socket_interface_send、nx_udp_socket_unbind,
  • nx_udp_source_extract

nx_udp_packet_info_extract

从 UDP 数据包提取网络参数

原型

UINT nx_udp_packet_info_extract(
    NX_PACKET *packet_ptr,
    ULONG *ip_address,
    UINT *protocol,
    UINT *port,
    UINT *interface_index);

说明

此服务用于从传入接口上收到的数据包提取网络参数,例如 IP 地址、对等端口号和协议类型(此服务始终返回 UDP 类型)。

参数

  • packet_ptr:指向数据包的指针。
  • ip_address:指向发送方 IP 地址的指针。
  • protocol:指向协议 (UDP) 的指针。
  • port:指向发送方端口号的指针。
  • interface_index:指向接收接口索引的指针。

返回值

  • NX_SUCCESS (0x00) 已成功提取数据包接口数据。
  • NX_INVALID_PACKET (0x12) 数据包不含 IP 帧。
  • NX_PTR_ERROR (0x07) 指针输入无效
  • NX_CALLER_ERROR:(0x11) 此服务的调用方无效。

允许调用自

线程数

可以抢占

示例

/* Extract network data from UDP packet interface.*/
status = nx_udp_packet_info_extract( packet_ptr, &ip_address,
    &protocol, &port,
    &interface_index);

/* If status is NX_SUCCESS packet data was successfully retrieved. */

另请参阅

  • nx_udp_enable、nx_udp_free_port_find、nx_udp_info_get,
  • nx_udp_socket_bind、nx_udp_socket_bytes_available,
  • nx_udp_socket_checksum_disable、nx_udp_socket_checksum_enable,
  • nx_udp_socket_create、nx_udp_socket_delete、nx_udp_socket_info_get,
  • nx_udp_socket_port_get、nx_udp_socket_receive,
  • nx_udp_socket_receive_notify、nx_udp_socket_send,
  • nx_udp_socket_interface_send、nx_udp_socket_unbind,
  • nx_udp_source_extract

nx_udp_socket_bind

将 UDP 套接字与 UDP 端口绑定

原型

UINT nx_udp_socket_bind(
    NX_UDP_SOCKET *socket_ptr, 
    UINT port,
    ULONG wait_option);

说明

此服务用于将先前创建的 UDP 套接字与指定的 UDP 端口绑定。 有效 UDP 套接字范围为 0 到 0xFFFF。 如果请求的端口号已与其他套接字绑定,则此服务会按指定的时间长度,等待该套接字与该端口号取消绑定。

参数

  • socket_ptr:此指针指向先前创建的 UDP 套接字实例。
  • port:要绑定到的端口号(1 到 0xFFFF)。 如果端口号为 NX_ANY_PORT (0x0000),则 IP 实例会搜索下一个可用端口并将其用于绑定。
  • wait_option:定义该端口已与另一套接字绑定时此服务的行为方式。 等待选项的定义如下:
    • NX_NO_WAIT (0x00000000)
    • NX_WAIT_FOREVER (0xFFFFFFFF)
    • 以时钟周期为单位的超时值(0x00000001 到 0xFFFFFFFE)

返回值

  • NX_SUCCESS:(0x00) 绑定套接字成功。
  • NX_ALREADY_BOUND:(0x22) 此套接字已与另一端口绑定。
  • NX_PORT_UNAVAILABLE:(0x23) 端口已与其他套接字绑定。
  • NX_NO_FREE_PORTS:(0x45) 没有可用的端口。
  • NX_WAIT_ABORTED:(0x1A) 已通过调用 tx_thread_wait_abort 中止所请求的挂起。
  • NX_INVALID_PORT:(0x46) 指定了无效的端口。
  • NX_PTR_ERROR (0x07) 套接字指针无效。
  • NX_CALLER_ERROR (0x11) 此服务的调用方无效。
  • NX_NOT_ENABLED (0x14) 尚未启用此组件。

允许调用自

线程数

可以抢占

示例

/* Bind the previously created UDP socket to port 12 on the
    previously created IP instance. If the port is already bound,
    wait for 300 timer ticks before giving up. */
status = nx_udp_socket_bind(&udp_socket, 12, 300);

/* If status is NX_SUCCESS, the UDP socket is now bound to
    port 12.*/

另请参阅

  • nx_udp_enable、nx_udp_free_port_find、nx_udp_info_get,
  • nx_udp_packet_info_extract、nx_udp_socket_bytes_available,
  • nx_udp_socket_checksum_disable、nx_udp_socket_checksum_enable,
  • nx_udp_socket_create、nx_udp_socket_delete、nx_udp_socket_info_get,
  • nx_udp_socket_port_get、nx_udp_socket_receive,
  • nx_udp_socket_receive_notify、nx_udp_socket_send,
  • nx_udp_socket_interface_send、nx_udp_socket_unbind,
  • nx_udp_source_extract

nx_udp_socket_bytes_available

检索可供检索的字节数

原型

UINT nx_udp_socket_bytes_available(
    NX_UDP_SOCKET *socket_ptr,
    ULONG *bytes_available);

说明

此服务用于检索所指定 UDP 套接字中可供接收的字节数。

参数

  • socket_ptr:此指针指向先前创建的 UDP 套接字。
  • bytes_available:此指针指向可用字节数的目标。

返回值

  • NX_SUCCESS:(0x00) 检索可用字节数成功。
  • NX_NOT_SUCCESSFUL:(0x43) 套接字未与任何端口绑定。
  • NX_PTR_ERROR:(0x07) 指针无效。
  • NX_NOT_ENABLED:(0x14) UDP 功能未启用。
  • NX_CALLER_ERROR (0x11) 此服务的调用方无效。

允许调用自

线程数

可以抢占

示例

/* Get the bytes available for retrieval from the UDP socket. */
status = nx_udp_socket_bytes_available(&my_socket, &bytes_available);

/* If status == NX_SUCCESS, the number of bytes was successfully
    retrieved.*/

另请参阅

  • nx_udp_enable、nx_udp_free_port_find、nx_udp_info_get,
  • nx_udp_packet_info_extract、nx_udp_socket_bind,
  • nx_udp_socket_checksum_disable、nx_udp_socket_checksum_enable,
  • nx_udp_socket_create、nx_udp_socket_delete、nx_udp_socket_info_get,
  • nx_udp_socket_port_get、nx_udp_socket_receive,
  • nx_udp_socket_receive_notify、nx_udp_socket_send,
  • nx_udp_socket_interface_send、nx_udp_socket_unbind,
  • nx_udp_source_extract

nx_udp_socket_checksum_disable

对 UDP 套接字禁用校验和

原型

UINT nx_udp_socket_checksum_disable(NX_UDP_SOCKET *socket_ptr);

说明

此服务禁用所指定 UDP 套接字上用于发送和接收数据包的校验和逻辑。 禁用校验和逻辑后,对于所有通过此套接字发送的数据包,系统都会将零值加载到 UDP 标头的校验和字段中。 通过将 UDP 标头中的校验和值设置为零值,可告知接收方未计算该数据包的校验和。

另请注意,如果接收和发送 UDP 数据包时分别定义了 NX_DISABLE_UDP_RX_CHECKSUM 和 NX_DISABLE_UDP_TX_CHECKSUM,则这不起作用 。

参数

  • socket_ptr:此指针指向先前创建的 UDP 套接字实例。

返回值

  • NX_SUCCESS:(0x00) 禁用套接字校验和成功。
  • NX_NOT_BOUND:(0x24) 套接字未绑定。
  • NX_PTR_ERROR (0x07) 套接字指针无效。
  • NX_CALLER_ERROR:(0x11) 此服务的调用方无效。
  • NX_NOT_ENABLED (0x14) 尚未启用此组件。

允许调用自

初始化、线程、计时器

可以抢占

示例

/* Disable the UDP checksum logic for packets sent on this socket. */
status = nx_udp_socket_checksum_disable(&udp_socket);

/* If status is NX_SUCCESS, outgoing packets will not have a checksum
    calculated. */

另请参阅

  • nx_udp_enable、nx_udp_free_port_find、nx_udp_info_get,
  • nx_udp_packet_info_extract、nx_udp_socket_bind,
  • nx_udp_socket_bytes_available、nx_udp_socket_checksum_disable,
  • nx_udp_socket_create、nx_udp_socket_delete、nx_udp_socket_info_get,
  • nx_udp_socket_port_get、nx_udp_socket_receive,
  • nx_udp_socket_receive_notify、nx_udp_socket_send,
  • nx_udp_socket_interface_send、nx_udp_socket_unbind,
  • nx_udp_source_extract

nx_udp_socket_checksum_enable

对 UDP 套接字启用校验和

原型

UINT nx_udp_socket_checksum_enable(NX_UDP_SOCKET *socket_ptr);

说明

此服务启用所指定 UDP 套接字上用于发送和接收数据包的校验和逻辑。 校验和涵盖整个 UDP 数据区域以及一个伪 IP 标头。

另请注意,如果接收和发送 UDP 数据包时分别定义了 NX_DISABLE_UDP_RX_CHECKSUM 和 NX_DISABLE_UDP_TX_CHECKSUM,则这不起作用 。

参数

  • socket_ptr:此指针指向先前创建的 UDP 套接字实例。

返回值

  • NX_SUCCESS:(0x00) 启用套接字校验和成功。
  • NX_NOT_BOUND:(0x24) 套接字未绑定。
  • NX_PTR_ERROR:(0x07) 套接字指针无效。
  • NX_CALLER_ERROR:(0x11) 此服务的调用方无效。
  • NX_NOT_ENABLED (0x14) 尚未启用此组件。

允许调用自

初始化、线程、计时器

可以抢占

示例

/* Enable the UDP checksum logic for packets sent on this socket. */
status = nx_udp_socket_checksum_enable(&udp_socket);

/* If status is NX_SUCCESS, outgoing packets will have a checksum
    calculated. */

另请参阅

  • nx_udp_enable、nx_udp_free_port_find、nx_udp_info_get,
  • nx_udp_packet_info_extract、nx_udp_socket_bind,
  • nx_udp_socket_bytes_available、nx_udp_socket_checksum_disable,
  • nx_udp_socket_create、nx_udp_socket_delete、nx_udp_socket_info_get,
  • nx_udp_socket_port_get、nx_udp_socket_receive,
  • nx_udp_socket_receive_notify、nx_udp_socket_send,
  • nx_udp_socket_interface_send、nx_udp_socket_unbind,
  • nx_udp_source_extract

nx_udp_socket_create

创建 UDP 套接字。

原型

UINT nx_udp_socket_create(
    NX_IP *ip_ptr,
    NX_UDP_SOCKET *socket_ptr, CHAR *name,
    ULONG type_of_service, ULONG fragment,
    UINT time_to_live, ULONG queue_maximum);

说明

此服务用于为指定的 IP 实例创建 UDP 套接字。

参数

  • ip_ptr:指向以前所创建 IP 实例的指针。
  • socket_ptr:指向新的 UDP 套接字控制块的指针。
  • name:此 UDP 套接字的应用程序名称。
  • type_of_service:定义用于传输的服务类型,合法值如下所示:
    • NX_IP_NORMAL (0x00000000)
    • NX_IP_MIN_DELAY (0x00100000)
    • NX_IP_MAX_DATA (0x00080000)
    • NX_IP_MAX_RELIABLE (0x00040000)
    • NX_IP_MIN_COST (0x00020000)
  • fragment:指定是否允许进行 IP 分段。 如果指定 NX_FRAGMENT_OKAY (0x0),则允许进行 IP 分段。 如果指定 NX_DONT_FRAGMENT (0x4000),则会禁止进行 IP 分段。
  • time_to_live:指定一个 8 位的值,用于定义此数据包在被丢弃之前可通过的路由器数目。 默认值由 NX_IP_TIME_TO_LIVE 指定。
  • queue_maximum:定义可为该套接字排队的 UDP 数据报最大数目。 达到队列限制后,接收到每个新数据包时,都会释放最早的 UDP 数据包。

返回值

  • NX_SUCCESS:(0x00) 创建 UDP 套接字成功。
  • NX_OPTION_ERROR:(0x0A) 服务类型、分段或生存时间选项无效。
  • NX_PTR_ERROR:(0x07) IP 或套接字指针无效。
  • NX_CALLER_ERROR (0x11) 此服务的调用方无效。
  • NX_NOT_ENABLED (0x14) 尚未启用此组件。

允许调用自

初始化和线程

可以抢占

示例

/* Create a UDP socket with a maximum receive queue of 30 packets.*/
status = nx_udp_socket_create(&ip_0, &udp_socket, "Sample UDP Socket",
    NX_IP_NORMAL, NX_FRAGMENT_OKAY, 0x80, 30);

/* If status is NX_SUCCESS, the new UDP socket has been created and
    is ready for binding. */

另请参阅

  • nx_udp_enable、nx_udp_free_port_find、nx_udp_info_get,
  • nx_udp_packet_info_extract、nx_udp_socket_bind,
  • nx_udp_socket_bytes_available、nx_udp_socket_checksum_disable,
  • nx_udp_socket_checksum_enable、nx_udp_socket_delete,
  • nx_udp_socket_info_get、nx_udp_socket_port_get,
  • nx_udp_socket_receive、nx_udp_socket_receive_notify,
  • nx_udp_socket_send、nx_udp_socket_interface_send,
  • nx_udp_socket_unbind、nx_udp_source_extract

nx_udp_socket_delete

删除 UDP 套接字

原型

UINT nx_udp_socket_delete(NX_UDP_SOCKET *socket_ptr);

说明

此服务用于删除先前创建的 UDP 套接字。 如果该套接字已与某一端口绑定,则必须先取消绑定。

参数

  • socket_ptr:此指针指向先前创建的 UDP 套接字实例。

返回值

  • NX_SUCCESS:(0x00) 删除套接字成功。
  • NX_STILL_BOUND:(0x42) 套接字仍处于绑定状态。
  • NX_PTR_ERROR (0x07) 套接字指针无效。
  • NX_CALLER_ERROR:(0x11) 此服务的调用方无效。
  • NX_NOT_ENABLED (0x14) 尚未启用此组件。

允许调用自

线程数

可以抢占

示例

/* Delete a previously created UDP socket. */
status = nx_udp_socket_delete(&udp_socket);

/* If status is NX_SUCCESS, the previously created UDP socket has
    been deleted. */

另请参阅

  • nx_udp_enable、nx_udp_free_port_find、nx_udp_info_get,
  • nx_udp_packet_info_extract、nx_udp_socket_bind,
  • nx_udp_socket_bytes_available、nx_udp_socket_checksum_disable,
  • nx_udp_socket_checksum_enable、nx_udp_socket_create,
  • nx_udp_socket_info_get、nx_udp_socket_port_get,
  • nx_udp_socket_receive、nx_udp_socket_receive_notify,
  • nx_udp_socket_send、nx_udp_socket_interface_send,
  • nx_udp_socket_unbind、nx_udp_source_extract

nx_udp_socket_info_get

检索 UDP 套接字活动的相关信息

原型

UINT nx_udp_socket_info_get(
    NX_UDP_SOCKET *socket_ptr,
    ULONG *udp_packets_sent,
    ULONG *udp_bytes_sent,
    ULONG *udp_packets_received,
    ULONG *udp_bytes_received,
    ULONG *udp_packets_queued,
    ULONG *udp_receive_packets_dropped,
    ULONG *udp_checksum_errors);

说明

此服务检索所指定 UDP 套接字实例的 UDP 套接字活动相关信息。

如果目标指针为 NX_NULL,则不会将该特定信息返回给调用方

参数

  • socket_ptr:此指针指向先前创建的 UDP 套接字实例。
  • udp_packets_sent:此指针指向在套接字上发送的 UDP 数据包总数的目标。
  • udp_bytes_sent:此指针指向在套接字上发送的 UDP 总字节数的目标。
  • udp_packets_received:此指针指向在套接字上接收的 UDP 数据包总数的目标。
  • udp_bytes_received:此指针指向在套接字上接收的 UDP 总字节数的目标。
  • udp_packets_queued:此指针指向在套接字上排队的 UDP 数据包总数的目标。
  • udp_receive_packets_dropped:此指针指向该套接字上因超过队列大小而被丢弃的 UDP 接收数据包总数的目标。
  • udp_checksum_errors:此指针指向套接字上有校验和错误的 UDP 数据包总数的目标。

返回值

  • NX_SUCCESS:(0x00) 检索 UDP 套接字信息成功。
  • NX_PTR_ERROR:(0x07) 套接字指针无效。
  • NX_CALLER_ERROR:(0x11) 此服务的调用方无效。
  • NX_NOT_ENABLED (0x14) 尚未启用此组件。

允许调用自

初始化、线程和计时器

可以抢占

示例

/* Retrieve UDP socket information from socket 0.*/
status = nx_udp_socket_info_get(&socket_0,
    &udp_packets_sent,
    &udp_bytes_sent,
    &udp_packets_received,
    &udp_bytes_received,
    &udp_queued_packets,
    &udp_receive_packets_dropped,
    &udp_checksum_errors);

/* If status is NX_SUCCESS, UDP socket information was retrieved.*/

另请参阅

  • nx_udp_enable、nx_udp_free_port_find、nx_udp_info_get,
  • nx_udp_packet_info_extract、nx_udp_socket_bind,
  • nx_udp_socket_bytes_available、nx_udp_socket_checksum_disable,
  • nx_udp_socket_checksum_enable、nx_udp_socket_create,
  • nx_udp_socket_delete、nx_udp_socket_port_get,
  • nx_udp_socket_receive、nx_udp_socket_receive_notify,
  • nx_udp_socket_send、nx_udp_socket_interface_send,
  • nx_udp_socket_unbind、nx_udp_source_extract

nx_udp_socket_port_get

选取与 UDP 套接字绑定的端口号

原型

UINT nx_udp_socket_port_get(NX_UDP_SOCKET *socket_ptr, UINT *port_ptr);

说明

此服务会检索与套接字关联的端口号;如果在绑定套接字时指定了 NX_ANY_PORT,它对查找 NetX 分配的端口非常有用。

参数

  • socket_ptr:此指针指向先前创建的 UDP 套接字实例。
  • port_ptr:此指针指向返回端口号的目标。 有效的端口号为 1- 0xFFFF。

返回值

  • NX_SUCCESS:(0x00) 绑定套接字成功。
  • NX_NOT_BOUND:(0x24) 此套接字未与任何端口绑定。
  • NX_PTR_ERROR:(0x07) 套接字指针或端口返回指针无效。
  • NX_CALLER_ERROR:(0x11) 此服务的调用方无效。
  • NX_NOT_ENABLED (0x14) 尚未启用此组件。

允许调用自

线程数

可以抢占

示例

/* Get the port number of created and bound UDP socket. */
status = nx_udp_socket_port_get(&udp_socket, &port);

/* If status is NX_SUCCESS, the port variable contains the port this
    socket is bound to. */

另请参阅

  • nx_udp_enable、nx_udp_free_port_find、nx_udp_info_get,
  • nx_udp_packet_info_extract、nx_udp_socket_bind,
  • nx_udp_socket_bytes_available、nx_udp_socket_checksum_disable,
  • nx_udp_socket_checksum_enable、nx_udp_socket_create,
  • nx_udp_socket_delete、nx_udp_socket_info_get,
  • nx_udp_socket_receive、nx_udp_socket_receive_notify,
  • nx_udp_socket_send、nx_udp_socket_interface_send,
  • nx_udp_socket_unbind、nx_udp_source_extract

nx_udp_socket_receive

从 UDP 套接字接收数据报

原型

UINT nx_udp_socket_receive(
    NX_UDP_SOCKET *socket_ptr,
    NX_PACKET **packet_ptr, 
    ULONG wait_option);

说明

此服务用于从指定的套接字接收 UDP 数据报。 如果指定的套接字上数据报在排队,调用方会根据提供的等待选项挂起。

如果返回了 NX_SUCCESS,则应用程序负责在不再需要所收到的数据包时将其释放。

参数

  • socket_ptr:此指针指向先前创建的 UDP 套接字实例。
  • packet_ptr:此指针指向 UDP 数据报数据包指针。
  • wait_option:定义此套接字上当前数据报在排队时此服务的行为方式。 等待选项的定义如下:
    • NX_NO_WAIT (0x00000000)
    • NX_WAIT_FOREVER (0xFFFFFFFF)
    • 以时钟周期为单位的超时值(0x00000001 到 0xFFFFFFFE)

允许调用自

线程数

可以抢占

示例

/* Receive a packet from a previously created and bound UDP socket.
    If no packets are currently available, wait for 500 timer ticks
    before giving up. */
status = nx_udp_socket_receive(&udp_socket, &packet_ptr, 500);

/* If status is NX_SUCCESS, the received UDP packet is pointed to by
    packet_ptr. */

另请参阅

  • nx_udp_enable、nx_udp_free_port_find、nx_udp_info_get,
  • nx_udp_packet_info_extract、nx_udp_socket_bind,
  • nx_udp_socket_bytes_available、nx_udp_socket_checksum_disable,
  • nx_udp_socket_checksum_enable、nx_udp_socket_create,
  • nx_udp_socket_delete、nx_udp_socket_info_get,
  • nx_udp_socket_port_get、nx_udp_socket_receive_notify,
  • nx_udp_socket_send、nx_udp_socket_interface_send,
  • nx_udp_socket_unbind、nx_udp_source_extract

nx_udp_socket_receive_notify

在收到每个数据包时通知应用程序

原型

UINT nx_udp_socket_receive_notify(
    NX_UDP_SOCKET *socket_ptr,
    VOID (*udp_receive_notify)
    (NX_UDP_SOCKET *socket_ptr));

说明

此服务用于将接收通知函数指针设置为应用程序所指定的回调函数。 然后,每当在该套接字上收到数据包时,就会调用该回调函数。 如果提供了 NX_NULL 指针,则会禁用接收通知功能。

参数

  • socket_ptr:此指针指向 UDP 套接字。
  • udp_receive_notify:在套接字上收到数据包时调用的应用程序回调函数指针。

允许来自

初始化、线程、计时器和 ISR

可以抢占

示例

/* Setup a receive packet callback function for the "udp_socket"
socket. */
status = nx_udp_socket_receive_notify(&udp_socket,
    my_receive_notify);

/* If status is NX_SUCCESS, NetX will call the function named
    "my_receive_notify" whenever a packet is received for
    "udp_socket". */

另请参阅

  • nx_udp_enable、nx_udp_free_port_find、nx_udp_info_get,
  • nx_udp_packet_info_extract、nx_udp_socket_bind,
  • nx_udp_socket_bytes_available、nx_udp_socket_checksum_disable,
  • nx_udp_socket_checksum_enable、nx_udp_socket_create,
  • nx_udp_socket_delete、nx_udp_socket_info_get,
  • nx_udp_socket_port_get、nx_udp_socket_receive、nx_udp_socket_send,
  • nx_udp_socket_interface_send、nx_udp_socket_unbind,
  • nx_udp_source_extract

nx_udp_socket_send

发送 UDP 数据报

原型

UINT nx_udp_socket_send(
    NX_UDP_SOCKET *socket_ptr,
    NX_PACKET *packet_ptr,
    ULONG ip_address,
    UINT port);

说明

此服务通过先前创建并绑定的 UDP 套接字发送 UDP 数据报。 NetX 会根据目标 IP 地址查找合适的本地 IP 地址作为源地址。 若要指定特定的接口和源 IP 地址,应用程序应使用 nx_udp_socket_interface_send 服务

请注意,无论是否已成功发送 UDP 数据报,此服务都会立即返回。

该套接字必须已与某个本地端口绑定。

警告

除非返回了错误,否则应用程序不应在此调用后释放该数据包。 这样做会导致不可预知的结果,因为网络驱动程序也会在传输后尝试释放该数据包。

参数

  • socket_ptr:此指针指向先前创建的 UDP 套接字实例
  • packet_ptr:UDP 数据报数据包指针
  • ip_address:目标 IP 地址
  • port:有效的目标端口号介于 1 与 0xFFFF 之间,以主机字节顺序表示

返回值

  • NX_SUCCESS:(0x00) UDP 套接字发送成功
  • NX_NOT_BOUND:(0x24) 套接字未与任何端口绑定
  • NX_NO_INTERFACE_ADDRESS:(0x50) 找不到合适的传出接口。
  • NX_IP_ADDRESS_ERROR:(0x21) 服务器 IP 地址无效
  • NX_UNDERFLOW:(0x02) 没有足够的空间容纳数据包中的 UDP 标头
  • NX_OVERFLOW:(0x03) 数据包追加指针无效
  • NX_PTR_ERROR:(0x07) 套接字指针无效
  • NX_CALLER_ERROR:(0x11) 此服务的调用方无效
  • NX_NOT_ENABLED:(0x14) UDP 尚未启用
  • NX_INVALID_PORT:(0x46) 端口号不在有效范围内

允许调用自

线程数

可以抢占

示例

ULONG server_address;

/* Set the UDP Client IP address. */
server_address = IP_ADDRESS(1,2,3,5);

/* Send a packet to the UDP server at server_address on port 12. */
status = nx_udp_socket_send(&client_socket, packet_ptr,
    server_address, 12);

/* If status == NX_SUCCESS, the application successfully transmitted
    the packet out the UDP socket to its peer. */

另请参阅

  • nx_udp_enable、nx_udp_free_port_find、nx_udp_info_get,
  • nx_udp_packet_info_extract、nx_udp_socket_bind,
  • nx_udp_socket_bytes_available、nx_udp_socket_checksum_disable,
  • nx_udp_socket_checksum_enable、nx_udp_socket_create,
  • nx_udp_socket_delete、nx_udp_socket_info_get,
  • nx_udp_socket_port_get、nx_udp_socket_receive,
  • nx_udp_socket_receive_notify、nx_udp_socket_interface_send,
  • nx_udp_socket_unbind、nx_udp_source_extract

nx_udp_socket_interface_send

通过 UDP 套接字发送数据报。

原型

UINT nx_udp_socket_interface_send(
    NX_UDP_SOCKET *socket_ptr,
    NX_PACKET *packet_ptr,
    ULONG ip_address,
    UINT port,
    UINT address_index);

说明

此服务以指定的 IP 地址作为源地址,通过网络接口使用先前创建并绑定的 UDP 套接字发送 UDP 数据报。 请注意,无论是否已成功发送 UDP 数据报,此服务都会立即返回。

警告

除非返回了错误,否则应用程序不应在此调用后释放该数据包。 这样做会导致不可预知的结果,因为网络驱动程序也会在传输后尝试释放该数据包。

参数

  • socket_ptr:要在其上传出数据包的套接字。
  • packet_ptr:指向要传输的数据包的指针。
  • ip_address:用于发送数据包的 IP 地址。
  • port:目标端口。
  • address_index:与用于发送数据包的接口相关联的地址索引。

返回值

  • NX_SUCCESS:(0x00) 发送数据包成功。
  • NX_NOT_BOUND:(0x24) 套接字未与任何端口绑定。
  • NX_IP_ADDRESS_ERROR:(0x21) IP 地址无效。
  • NX_NOT_ENABLED:(0x14) UDP 处理未启用。
  • NX_PTR_ERROR:(0x07) 指针无效。
  • NX_OVERFLOW:(0x03) 数据包追加指针无效。
  • NX_UNDERFLOW:(0x02) 数据包前置指针无效。
  • NX_CALLER_ERROR (0x11) 此服务的调用方无效。
  • NX_INVALID_INTERFACE:(0x4C) 地址索引无效。
  • NX_INVALID_PORT:(0x46) 端口号超出最大端口号。

允许调用自

线程数

可以抢占

示例

#define ADDRESS_INDEX 1

/* Send packet out on port 80 to the specified destination IP on the
interface at index 1 in the IP task interface list. */
status = nx_udp_packet_interface_send(socket_ptr, packet_ptr,
    destination_ip, 80,
    ADDRESS_INDEX);

/* If status is NX_SUCCESS packet was successfully transmitted. */

另请参阅

  • nx_udp_enable、nx_udp_free_port_find、nx_udp_info_get,
  • nx_udp_packet_info_extract、nx_udp_socket_bind,
  • nx_udp_socket_bytes_available、nx_udp_socket_checksum_disable,
  • nx_udp_socket_checksum_enable、nx_udp_socket_create,
  • nx_udp_socket_delete、nx_udp_socket_info_get,
  • nx_udp_socket_port_get、nx_udp_socket_receive,
  • nx_udp_socket_receive_notify、nx_udp_socket_send,
  • nx_udp_socket_unbind

nx_udp_socket_unbind

取消 UDP 套接字与 UDP 端口的绑定。

原型

UINT nx_udp_socket_unbind(NX_UDP_SOCKET *socket_ptr);

说明

此服务用于解除 UDP 套接字与 UDP 端口之间的绑定。 在取消绑定操作过程中,将会释放全部存储在接收队列中的已接收数据包。

如有其他线程在等待将其他套接字与该取消绑定的端口绑定,则第一个挂起的线程会与新取消绑定的端口绑定。

参数

  • socket_ptr:此指针指向先前创建的 UDP 套接字实例。

返回值

  • NX_SUCCESS:(0x00) 取消绑定套接字成功。
  • NX_NOT_BOUND:(0x24) 套接字未与任何端口绑定。
  • NX_PTR_ERROR (0x07) 套接字指针无效。
  • NX_CALLER_ERROR (0x11) 此服务的调用方无效。
  • NX_NOT_ENABLED (0x14) 尚未启用此组件。

允许调用自

线程数

可以抢占

示例

/* Unbind the previously bound UDP socket. */
status = nx_udp_socket_unbind(&udp_socket);

/* If status is NX_SUCCESS, the previously bound socket is now
    unbound. */

另请参阅

  • nx_udp_enable、nx_udp_free_port_find、nx_udp_info_get,
  • nx_udp_packet_info_extract、nx_udp_socket_bind,
  • nx_udp_socket_bytes_available、nx_udp_socket_checksum_disable,
  • nx_udp_socket_checksum_enable、nx_udp_socket_create,
  • nx_udp_socket_delete、nx_udp_socket_info_get,
  • nx_udp_socket_port_get、nx_udp_socket_receive,
  • nx_udp_socket_receive_notify、nx_udp_socket_send,
  • nx_udp_socket_interface_send、nx_udp_source_extract

nx_udp_source_extract

从 UDP 数据报提取 IP 和发送端口

原型

UINT nx_udp_source_extract(
    NX_PACKET *packet_ptr,
    ULONG *ip_address, UINT *port);

说明

此服务用于从提供的 UDP 数据报的 IP 和 UDP 标头中提取发送方的 IP 和端口号。

参数

  • packet_ptr:UDP 数据报数据包指针。
  • ip_address:指向返回 IP 地址变量的有效指针。
  • port:指向返回端口变量的有效指针。

返回值

  • NX_SUCCESS:(0x00) 提取源 IP/端口成功。
  • NX_INVALID_PACKET:(0x12) 提供的数据包无效。
  • NX_PTR_ERROR:(0x07) 数据包或者 IP 或端口目标无效。

允许调用自

初始化、线程、计时器、ISR

可以抢占

示例

/* Extract the IP and port information from the sender of the UPD
    packet. */
status = nx_udp_source_extract(packet_ptr, &sender_ip_address,
    &sender_port);

/* If status is NX_SUCCESS, the sender IP and port information has
    been stored in sender_ip_address and sender_port respectively.*/

另请参阅

  • nx_udp_enable、nx_udp_free_port_find、nx_udp_info_get,
  • nx_udp_packet_info_extract、nx_udp_socket_bind,
  • nx_udp_socket_bytes_available、nx_udp_socket_checksum_disable,
  • nx_udp_socket_checksum_enable、nx_udp_socket_create,
  • nx_udp_socket_delete、nx_udp_socket_info_get,
  • nx_udp_socket_port_get、nx_udp_socket_receive,
  • nx_udp_socket_receive_notify、nx_udp_socket_send,
  • nx_udp_socket_interface_send、nx_udp_socket_unbind