Chapter 4 - Description of Azure RTOS NetX Services

This chapter contains a description of all Azure RTOS NetX services in alphabetic order. Service names are designed so all similar services are grouped together. For example, all ARP services are found at the beginning of this chapter.

Note

Note that a BSD-Compatible Socket API is available for legacy application code that cannot take full advantage of the high-performance NetX API. Refer to Appendix D for more information on the BSD-Compatible Socket API.

In the "Return Values" section of each description, values in BOLD are not affected by the NX_DISABLE_ERROR_CHECKING option used to disable the API error checking, while values in non-bold are completely disabled. The "Allowed From" sections indicate from which each NetX service can be called.

nx_arp_dynamic_entries_invalidate

Invalidate all dynamic entries in the ARP cache

Prototype

UINT nx_arp_dynamic_entries_invalidate(NX_IP *ip_ptr);

Description

This service invalidates all dynamic ARP entries currently in the ARP cache.

Parameters

  • ip_ptr: Pointer to previously created IP instance.

Return Values

  • NX_SUCCESS (0x00) Successful ARP cache invalidate.
  • NX_NOT_ENABLED (0x14) ARP is not enabled.
  • NX_PTR_ERROR (0x07) Invalid IP address.
  • NX_CALLER_ERROR (0x11) Caller is not a thread.

Allowed From

Threads

Preemption Possible

No

Example

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

See Also

  • 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

Set dynamic ARP entry

Prototype

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

Description

This service allocates a dynamic entry from the ARP cache and sets up the specified IP to physical address mapping. If a zero physical address is specified, an actual ARP request is sent to the network in order to have the physical address resolved. Also note that this entry will be removed if ARP aging is active or if the ARP cache is exhausted and this is the least recently used ARP entry.

Parameters

  • ip_ptr: Pointer to previously created IP instance.
  • ip_address: IP address to map.
  • physical_msw: Top 16 bits (47-32) of the physical address.
  • physical_lsw: Lower 32 bits (31-0) of the physical address.

Return Values

  • NX_SUCCESS (0x00) Successful ARP dynamic entry set.
  • NX_NO_MORE_ENTRIES (0x17) No more ARP entries are available in the ARP cache.
  • NX_IP_ADDRESS_ERROR (0x21) Invalid IP address.
  • NX_PTR_ERROR (0x07) Invalid IP instance pointer.
  • NX_NOT_ENABLED (0x14) This component has not been enabled.
  • NX_CALLER_ERROR (0x11) Invalid caller of this service.

Allowed From

Threads

Preemption Possible

No

Example

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

See Also

  • 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

Enables Address Resolution Protocol (ARP).

Prototype

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

Description

This service initializes the ARP component of NetX for the specific IP instance. ARP initialization includes setting up the ARP cache and various ARP processing routines necessary for sending and receiving ARP messages.

Parameters

  • ip_ptr: Pointer to previously created IP instance.
  • arp_cache_memory: Pointer to memory area to place ARP cache.
  • arp_cache_size: Each ARP entry is 52 bytes, the total number of ARP entries is, therefore, the size divided by 52.

Return Values

  • NX_SUCCESS (0x00) Successful ARP enable.
  • NX_PTR_ERROR (0x07) Invalid IP or cache memory pointer.
  • NX_SIZE_ERROR (0x09) User supplied ARP cache memory is too small.
  • NX_CALLER_ERROR (0x11) Invalid caller of this service.
  • NX_ALREADY_ENABLED (0x15) This component has already been enabled.

Allowed From

Initialization, threads

Preemption Possible

No

Example

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

See Also

  • 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

Send gratuitous ARP request

Prototype

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

Description

This service goes through all the physical interfaces to transmit gratuitous ARP requests as long as the interface IP address is valid. If an ARP response is subsequently received, the supplied response handler is called to process the response to the gratuitous ARP.

Parameters

  • ip_ptr: Pointer to previously created IP instance.
  • response_handler: Pointer to response handling function. If NX_NULL is supplied, responses are ignored.

Return Values

  • NX_SUCCESS (0x00) Successful gratuitous ARP send.
  • NX_NO_PACKET (0x01) No packet available.
  • NX_NOT_ENABLED (0x14) ARP is not enabled.
  • NX_IP_ADDRESS_ERROR (0x21) Current IP address is invalid.
  • NX_PTR_ERROR (0x07) Invalid IP pointer.
  • NX_CALLER_ERROR (0x11) Caller is not a thread.

Allowed From

Threads

Preemption Possible

No

Example

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

See Also

  • 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

Locate physical hardware address given an IP address

Prototype

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

Description

This service attempts to find a physical hardware address in the ARP cache that is associated with the supplied IP address.

Parameters

  • ip_ptr: Pointer to previously created IP instance.
  • ip_address: IP address to search for.
  • physical_msw: Pointer to the variable for returning the top 16 bits (47-32) of the physical address.
  • physical_lsw: Pointer to the variable for returning the lower 32 bits (31-0) of the physical address.

Return Values

  • NX_SUCCESS (0x00) Successful ARP hardware address find.
  • NX_ENTRY_NOT_FOUND (0x16) Mapping was not found in the ARP cache.
  • NX_IP_ADDRESS_ERROR (0x21) Invalid IP address.
  • NX_PTR_ERROR (0x07) Invalid IP or memory pointer.
  • NX_CALLER_ERROR (0x11) Invalid caller of this service.
  • NX_NOT_ENABLED (0x14) This component has not been enabled.

Allowed From

Threads

Preemption Possible

No

Example

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

See Also

  • 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

Retrieve information about ARP activities

Prototype

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);

Description

This service retrieves information about ARP activities for the associated IP instance.

If a destination pointer is NX_NULL, that particular information is not returned to the caller.

Parameters

  • ip_ptr: Pointer to previously created IP instance.
  • arp_requests_sent: Pointer to destination for the total ARP requests sent from this IP instance.
  • arp_requests_received: Pointer to destination for the total ARP requests received from the network.
  • arp_responses_sent: Pointer to destination for the total ARP responses sent from this IP instance.
  • arp_responses_received: Pointer to the destination for the total ARP responses received from the network.
  • arp_dynamic_entries: Pointer to the destination for the current number of dynamic ARP entries.
  • arp_static_entries: Pointer to the destination for the current number of static ARP entries.
  • arp_aged_entries: Pointer to the destination of the total number of ARP entries that have aged and became invalid.
  • arp_invalid_messages: Pointer to the destination of the total invalid ARP messages received.

Return Values

  • NX_SUCCESS (0x00) Successful ARP information retrieval.
  • NX_PTR_ERROR (0x07) Invalid IP pointer.
  • NX_CALLER_ERROR (0x11) Invalid caller of this service.
  • NX_NOT_ENABLED (0x14) This component has not been enabled.

Allowed From

Threads

Preemption Possible

No

Example

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

See Also

  • 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

Locate IP address given a physical address

Prototype

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

Description

This service attempts to find an IP address in the ARP cache that is associated with the supplied physical address.

Parameters

  • ip_ptr: Pointer to previously created IP instance.
  • ip_address: Pointer to return IP address, if one is found that has been mapped.
  • physical_msw: Top 16 bits (47-32) of the physical address to search for.
  • physical_lsw: Lower 32 bits (31-0) of the physical address to search for.

Return Values

  • NX_SUCCESS (0x00) Successful ARP IP address find
  • NX_ENTRY_NOT_FOUND (0x16) Mapping was not found in the ARP cache.
  • NX_PTR_ERROR (0x07) Invalid IP or memory pointer.
  • NX_CALLER_ERROR (0x11) Invalid caller of this service.
  • NX_NOT_ENABLED (0x14) This component has not been enabled.
  • NX_INVALID_PARAMETERS (0x4D) Physical_msw and physical_lsw are both 0.

Allowed From

Threads

Preemption Possible

No

Example

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

See Also

  • 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

Delete all static ARP entries

Prototype

UINT nx_arp_static_entries_delete(NX_IP *ip_ptr);

Description

This service deletes all static entries in the ARP cache.

Parameters

  • ip_ptr: Pointer to previously created IP instance.

Return Values

  • NX_SUCCESS (0x00) Static entries are deleted.
  • NX_PTR_ERROR (0x07) Invalid ip_ptr pointer.
  • NX_CALLER_ERROR (0x11) Invalid caller of this service.
  • NX_NOT_ENABLED (0x14) This component has not been enabled.

Allowed From

Initialization, threads

Preemption Possible

No

Example

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

See Also

  • 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

Create static IP to hardware mapping in ARP cache

Prototype

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

Description

This service creates a static IP-to-physical address mapping in the ARP cache for the specified IP instance. Static ARP entries are not subject to ARP periodic updates.

Parameters

  • ip_ptr: Pointer to previously created IP instance.
  • ip_address: IP address to map.
  • physical_msw: Top 16 bits (47-32) of the physical address to map.
  • physical_lsw: Lower 32 bits (31-0) of the physical address to map.

Return Values

  • NX_SUCCESS (0x00) Successful ARP static entry create.
  • NX_NO_MORE_ENTRIES (0x17) No more ARP entries are available in the ARP cache.
  • NX_IP_ADDRESS_ERROR (0x21) Invalid IP address.
  • NX_PTR_ERROR (0x07) Invalid IP pointer.
  • NX_CALLER_ERROR (0x11) Invalid caller of this service.
  • NX_NOT_ENABLED (0x14) This component has not been enabled.
  • NX_INVALID_PARAMETERS (0x4D) Physical_msw and physical_lsw are both 0.

Allowed From

Initialization, threads

Preemption Possible

No

Example

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

See Also

  • 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

Delete static IP to hardware mapping in ARP cache

Prototype

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

Description

This service finds and deletes a previously created static IP-to-physical address mapping in the ARP cache for the specified IP instance.

Parameters

  • ip_ptr: Pointer to previously created IP instance.
  • ip_address: IP address that was mapped statically.
  • physical_msw: Top 16 bits (47 - 32) of the physical address that was mapped statically.
  • physical_lsw: Lower 32 bits (31 - 0) of the physical address that was mapped statically.

Return Values

  • NX_SUCCESS (0x00) Successful ARP static entry delete.
  • NX_ENTRY_NOT_FOUND (0x16) Static ARP entry was not found in the ARP cache.
  • NX_PTR_ERROR (0x07) Invalid IP pointer.
  • NX_CALLER_ERROR (0x11) Invalid caller of this service.
  • NX_NOT_ENABLED (0x14) This component has not been enabled.
  • NX_IP_ADDRESS_ERROR (0x21) Invalid IP address.
  • NX_INVALID_PARAMETERS (0x4D) Physical_msw and physical_lsw are both 0.

Allowed From

Threads

Preemption Possible

No

Example

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

See Also

  • 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

Enable Internet Control Message Protocol (ICMP)

Prototype

UINT nx_icmp_enable(NX_IP *ip_ptr);

Description

This service enables the ICMP component for the specified IP instance. The ICMP component is responsible for handling Internet error messages and ping requests and replies.

Parameters

  • ip_ptr: Pointer to previously created IP instance.

Return Values

  • NX_SUCCESS (0x00) Successful ICMP enable.
  • NX_ALREADY_ENABLED (0x15) ICMP is already enabled.
  • NX_PTR_ERROR (0x07) Invalid IP pointer.
  • NX_CALLER_ERROR (0x11) Invalid caller of this service.

Allowed From

Initialization, threads

Preemption Possible

No

Example

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

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

See Also

  • nx_icmp_info_get, nx_icmp_ping

nx_icmp_info_get

Retrieve information about ICMP activities

Prototype

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);

Description

This service retrieves information about ICMP activities for the specified IP instance.

If a destination pointer is NX_NULL, that particular information is not returned to the caller.

Parameters

  • ip_ptr: Pointer to previously created IP instance.
  • pings_sent: Pointer to destination for the total number of pings sent.
  • ping_timeouts: Pointer to destination for the total number of ping timeouts.
  • ping_threads_suspended: Pointer to destination of the total number of threads suspended on ping requests.
  • ping_responses_received: Pointer to estination of the total number of ping responses received.
  • icmp_checksum_errors: Pointer to destination of the total number of ICMP checksum errors.
  • icmp_unhandled_messages: Pointer to estination of the total number of un-handled ICMP messages.

Return Values

  • NX_SUCCESS (0x00) Successful ICMP information retrieval.
  • NX_CALLER_ERROR (0x11) Invalid caller of this service.
  • NX_PTR_ERROR (0x07) Invalid IP pointer.
  • NX_NOT_ENABLED (0x14) This component has not been enabled.

Allowed From

Initialization, threads

Preemption Possible

No

Example

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

See Also

  • nx_icmp_enable, nx_icmp_ping

nx_icmp_ping

Send ping request to specified IP address

Prototype

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

Description

This service sends a ping request to the specified IP address and waits for the specified amount of time for a ping response message. If no response is received, an error is returned. Otherwise, the entire response message is returned in the variable pointed to by response_ptr.

If NX_SUCCESS is returned, the application is responsible for releasing the received packet after it is no longer needed.

Parameters

  • ip_ptr: Pointer to previously created IP instance.

  • ip_address: IP address, in host byte order, to ping. data Pointer to data area for ping message.

  • data_size: Number of bytes in the ping data

  • response_ptr: Pointer to packet pointer to return the ping response message in.

  • wait_option: Defines how long to wait for a ping response. wait options are defined as follows:

    • NX_NO_WAIT (0x00000000)
    • NX_WAIT_FOREVER (0xFFFFFFFF)
    • timeout value in ticks (0x00000001 through 0xFFFFFFFE)

Return Values

  • NX_SUCCESS (0x00) Successful ping. Response message pointer was placed in the variable pointed to by response_ptr.
  • NX_NO_PACKET (0x01) Unable to allocate a ping request packet.
  • NX_OVERFLOW (0x03) Specified data area exceeds the default packet size for this IP instance.
  • NX_NO_RESPONSE (0x29) Requested IP did not respond.
  • NX_WAIT_ABORTED (0x1A) Requested suspension was aborted by a call to tx_thread_wait_abort.
  • NX_IP_ADDRESS_ERROR (0x21) Invalid IP address.
  • NX_PTR_ERROR (0x07) Invalid IP or response pointer.
  • NX_CALLER_ERROR (0x11) Invalid caller of this service.
  • NX_NOT_ENABLED (0x14) This component has not been enabled.

Allowed From

Threads

Preemption Possible

No

Example

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

See Also

  • nx_icmp_enable, nx_icmp_info_get

nx_igmp_enable

Enable Internet Group Management Protocol (IGMP)

Prototype

UINT nx_igmp_enable(NX_IP *ip_ptr);

Description

This service enables the IGMP component on the specified IP instance. The IGMP component is responsible for providing support for IP multicast group management operations.

Parameters

  • ip_ptr: Pointer to previously created IP instance.

Return Values

  • NX_SUCCESS (0x00) Successful IGMP enable.
  • NX_PTR_ERROR (0x07) Invalid IP pointer.
  • NX_CALLER_ERROR (0x11) Invalid caller of this service.
  • NX_ALREADY_ENABLED (0x15) This component has already been enabled.

Allowed From

Initialization, threads

Preemption Possible

No

Example

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

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

See Also

  • 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

Retrieve information about IGMP activities

Prototype

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);

Description

This service retrieves information about IGMP activities for the specified IP instance.

If a destination pointer is NX_NULL, that particular information is not returned to the caller.

Parameters

  • ip_ptr: Pointer to previously created IP instance.
  • igmp_reports_sent: Pointer to destination for the total number of ICMP reports sent.
  • igmp_queries_received: Pointer to destination for the total number of queries received by multicast router.
  • igmp_checksum_errors: Pointer to destination of the total number of IGMP checksum errors on receive packets.
  • current_groups_joined: Pointer to destination of the current number of groups joined through this IP instance.

Return Values

  • NX_SUCCESS (0x00) Successful IGMP information retrieval.
  • NX_PTR_ERROR (0x07) Invalid IP pointer.
  • NX_CALLER_ERROR (0x11) Invalid caller of this service.
  • NX_NOT_ENABLED (0x14) This component has not been enabled.

Allowed From

Initialization, threads

Preemption Possible

No

Example

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

See Also

  • 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

Disable IGMP loopback

Prototype

UINT nx_igmp_loopback_disable(NX_IP *ip_ptr);

Description

This service disables IGMP loopback for all subsequent multicast groups joined.

Parameters

  • ip_ptr: Pointer to previously created IP instance.

Return Values

  • NX_SUCCESS (0x00) Successful IGMP loopback disable.
  • NX_NOT_ENABLED (0x14) IGMP is not enabled.
  • NX_PTR_ERROR (0x07) Invalid IP pointer.
  • NX_CALLER_ERROR (0x11) Caller is not a thread or initialization.

Allowed From

Initialization, threads

Preemption Possible

No

Example

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

See Also

  • 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

Enable IGMP loopback

Prototype

UINT nx_igmp_loopback_enable(NX_IP *ip_ptr);

Description

This service enables IGMP loopback for all subsequent multicast groups joined.

Parameters

  • ip_ptr: Pointer to previously created IP instance.

Return Values

  • NX_SUCCESS (0x00) Successful IGMP loopback disable.
  • NX_NOT_ENABLED (0x14) IGMP is not enabled.
  • NX_PTR_ERROR (0x07) Invalid IP pointer.
  • NX_CALLER_ERROR (0x11) Caller is not a thread or initialization.

Allowed From

Initialization, threads

Preemption Possible

No

Example

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

See Also

  • 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

Join IP instance to specified multicast group via an interface

Prototype

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

Description

This service joins an IP instance to the specified multicast group via a specified network interface. An internal counter is maintained to keep track of the number of times the same group has been joined. After joining the multicast group, the IGMP component will allow reception of IP packets with this group address via the specified network interface and also report to routers that this IP is a member of this multicast group. The IGMP membership join, report, and leave messages are also sent via the specified network interface.

Parameters

  • ip_ptr: Pointer to previously created IP instance.
  • group_address: Class D IP multicast group address to join in host byte order.
  • interface_index: Index of the Interface attached to the NetX instance.

Return Values

  • NX_SUCCESS (0x00) Successful multicast group join.
  • NX_NO_MORE_ENTRIES (0x17) No more multicast groups can be joined, maximum exceeded.
  • NX_PTR_ERROR (0x07) Invalid IP pointer.
  • NX_INVALID_INTERFACE (0x4C) Device index points to an invalid network interface.
  • NX_IP_ADDRESS_ERROR (0x21) Multicast group address provided is not a valid class D address.
  • NX_CALLER_ERROR (0x11) Invalid caller of this service.
  • NX_NOT_ENABLED (0x14) IP multicast support is not enabled.

Allowed From

Threads

Preemption Possible

No

Example

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

See Also

  • 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

Join IP instance to specified multicast group

Prototype

UINT nx_igmp_multicast_join(
    NX_IP *ip_ptr, 
    ULONG group_address);

Description

This service joins an IP instance to the specified multicast group. An internal counter is maintained to keep track of the number of times the same group has been joined. The driver is commanded to send an IGMP report if this is the first join request out on the network indicating the host's intention to join the group. After joining, the IGMP component will allow reception of IP packets with this group address and report to routers that this IP is a member of this multicast group.

Note

To join a multicast group on a non-primary device, use the service nx_igmp_multicast_interface_join.

Parameters

  • ip_ptr: Pointer to previously created IP instance.
  • group_address: Class D IP multicast group address to join.

Return Values

  • NX_SUCCESS (0x00) Successful multicast group join.
  • NX_NO_MORE_ENTRIES (0x17) No more multicast groups can be joined, maximum exceeded.
  • NX_INVALID_INTERFACE (0x4C) Device index points to an invalid network interface.
  • NX_IP_ADDRESS_ERROR (0x21) Invalid IP group address.
  • NX_PTR_ERROR (0x07) Invalid IP pointer.
  • NX_CALLER_ERROR (0x11) Invalid caller of this service.
  • NX_NOT_ENABLED (0x14) This component has not been enabled.

Allowed From

Threads

Preemption Possible

No

Example

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

See Also

  • 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

Cause IP instance to leave specified multicast group

Prototype

UINT nx_igmp_multicast_leave(
    NX_IP *ip_ptr, 
    ULONG group_address);

Description

This service causes an IP instance to leave the specified multicast group, if the number of leave requests matches the number of join requests. Otherwise, the internal join count is simply decremented.

Parameters

  • ip_ptr: Pointer to previously created IP instance.
  • group_address: Multicast group to leave.

Return Values

  • NX_SUCCESS (0x00) Successful multicast group join.
  • NX_ENTRY_NOT_FOUND (0x16) Previous join request was not found.
  • NX_INVALID_INTERFACE (0x4C) Device index points to an invalid network interface.
  • NX_IP_ADDRESS_ERROR (0x21) Invalid IP group address.
  • NX_PTR_ERROR (0x07) Invalid IP pointer.
  • NX_CALLER_ERROR (0x11) Invalid caller of this service.
  • NX_NOT_ENABLED (0x14) This component has not been enabled.

Allowed From

Threads

Preemption Possible

No

Example

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

See Also

  • 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

Notify application if IP address changes

Prototype

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

Description

This service registers an application notification function that is called whenever the IP address is changed.

Parameters

  • ip_ptr: Pointer to previously created IP instance.
  • change_notify: Pointer to IP change notification function. If this parameter is NX_NULL, IP address change notification is disabled.
  • additional_info: Pointer to optional additional information that is also supplied to the notification function when the IP address is changed.

Return Values

  • *NX_SUCCESS: (0x00) Successful IP address change notification.
  • NX_PTR_ERROR (0x07) Invalid IP pointer.
  • NX_CALLER_ERROR (0x11) Invalid caller of this service.

Allowed From

Initialization, threads

Preemption Possible

No

Example

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

See Also

  • 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

Retrieve IP address and network mask

Prototype

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

Description

This service retrieves IP address and its subnet mask of the primary network interface.

To obtain information of the secondary device, use the service nx_ip_interface_address_get.

Parameters

  • ip_ptr: Pointer to previously created IP instance.
  • ip_address: Pointer to destination for IP address.
  • network_mask: Pointer to destination for network mask.

Return Values

  • NX_SUCCESS (0x00) Successful IP address get.
  • NX_PTR_ERROR (0x07) Invalid IP or return variable pointer.
  • NX_CALLER_ERROR (0x11) Invalid caller of this service.

Allowed From

Initialization, threads

Preemption Possible

No

Example

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

See Also

  • 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

Set IP address and network mask

Prototype

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

Description

This service sets IP address and network mask for the primary network interface.

To set IP address and network mask for the secondary device, use the service nx_ip_interface_address_set.

Parameters

  • ip_ptr: Pointer to previously created IP instance.
  • ip_address: New IP address.
  • network_mask: New network mask.

Return Values

  • NX_SUCCESS (0x00) Successful IP address set.
  • NX_IP_ADDRESS_ERROR (0x21) Invalid IP address.
  • NX_PTR_ERROR (0x07) Invalid IP pointer.
  • NX_CALLER_ERROR (0x11) Invalid caller of this service.

Allowed From

Initialization, threads

Preemption Possible

No

Example

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

See Also

  • 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

Create an IP instance

Prototype

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);

Description

This service creates an IP instance with the user supplied IP address and network driver. In addition, the application must supply a previously created packet pool for the IP instance to use for internal packet allocation. Note that the supplied application network driver is not called until this IP's thread executes.

Parameters

  • ip_ptr: Pointer to control block to create a new IP instance.
  • name: Name of this new IP instance.
  • ip_address: IP address for this new IP instance.
  • network_mask: Mask to delineate the network portion of the IP address for sub-netting and super-netting uses.
  • default_pool: Pointer to control block of previously created NetX packet pool.
  • ip_network_driver: User-supplied network driver used to send and receive IP packets.
  • memory_ptr: Pointer to memory area for the IP helper thread’s stack area.
  • memory_size: Number of bytes in the memory area for the IP helper thread’s stack.
  • priority: Priority of IP helper thread.

Return Values

  • NX_SUCCESS (0x00) Successful IP instance creation.
  • NX_NOT_IMPLEMENTED (0x4A) NetX library is configured incorrectly.
  • NX_PTR_ERROR (0x07) Invalid IP, network driver function pointer, packet pool, or memory pointer.
  • NX_SIZE_ERROR (0x09) The supplied stack size is too small.
  • NX_CALLER_ERROR (0x11) Invalid caller of this service.
  • NX_IP_ADDRESS_ERROR (0x21) The supplied IP address is invalid.
  • NX_OPTION_ERROR (0x21) The supplied IP thread priority is invalid.

Allowed From

Initialization, threads

Preemption Possible

No

Example

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

See Also

  • 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

Delete previously created IP instance

Prototype

UINT nx_ip_delete(NX_IP *ip_ptr);

Description

This service deletes a previously created IP instance and releases all of the system resources owned by the IP instance.

Parameters

  • ip_ptr: Pointer to previously created IP instance.

Return Values

  • NX_SUCCESS (0x00) Successful IP deletion.
  • NX_SOCKETS_BOUND (0x28) This IP instance still has UDP or TCP sockets bound to it. All sockets must be unbound and deleted prior to deleting the IP instance.
  • NX_PTR_ERROR (0x07) Invalid IP pointer.
  • NX_CALLER_ERROR (0x11) Invalid caller of this service.

Allowed From

Threads

Preemption Possible

Yes

Example

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

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

See Also

  • 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

Issue command to network driver

Prototype

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

Description

This service provides a direct interface to the application's primary network interface driver specified during the nx_ip_create call.

Application-specific commands can be used providing their numeric value is greater than or equal to NX_LINK_USER_COMMAND.

To issue command for the secondary device, use the nx_ip_driver_interface_direct_command service.

Parameters

  • ip_ptr: Pointer to previously created IP instance.
  • command: Numeric command code. Standard commands are defined as follows:
    • 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: Pointer to return variable in the caller.

Return Values

  • NX_SUCCESS (0x00) Successful network driver direct command.
  • NX_UNHANDLED_COMMAND (0x44) Unhandled or unimplemented network driver command.
  • NX_PTR_ERROR (0x07) Invalid IP or return value pointer.
  • NX_CALLER_ERROR (0x11) Invalid caller of this service.
  • NX_INVALID_INTERFACE (0x4C) Invalid interface index.

Allowed From

Threads

Preemption Possible

No

Example

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

See Also

  • 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

Issue command to network driver

Prototype

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

Description

This service provides a direct command to the application's network device driver in the IP instance. Application-specific commands can be used providing their numeric value is greater than or equal to NX_LINK_USER_COMMAND.

Parameters

  • ip_ptr: Pointer to previously created IP instance.
  • command: Numeric command code. Standard commands are defined as follows:
    • 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: Index of the network interface the command should be sent to.
  • return_value_ptr: Pointer to return variable in the caller.

Return Values

  • NX_SUCCESS (0x00) Successful network driver direct command.
  • NX_UNHANDLED_COMMAND (0x44) Unhandled or unimplemented network driver command.
  • NX_INVALID_INTERFACE (0x4C) Invalid interface index
  • NX_PTR_ERROR (0x07) Invalid IP or return value pointer.
  • NX_CALLER_ERROR (0x11) Invalid caller of this service.

Allowed From

Threads

Preemption Possible

No

Example

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

See Also

  • 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

Disable IP packet forwarding

Prototype

UINT nx_ip_forwarding_disable(NX_IP *ip_ptr);

Description

This service disables forwarding IP packets inside the NetX IP component. On creation of the IP task, this service is automatically disabled.

Parameters

  • ip_ptr: Pointer to previously created IP instance.

Return Values

  • NX_SUCCESS (0x00) Successful IP forwarding disable.
  • NX_PTR_ERROR (0x07) Invalid IP pointer.
  • NX_CALLER_ERROR (0x11) Invalid caller of this service.

Allowed From

Initialization, threads, timers

Preemption Possible

No

Example

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

See Also

  • 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

Enable IP packet forwarding

Prototype

UINT nx_ip_forwarding_enable(NX_IP *ip_ptr);

Description

This service enables forwarding IP packets inside the NetX IP component. On creation of the IP task, this service is automatically disabled.

Parameters

  • ip_ptr: Pointer to previously created IP instance.

Return Values

  • NX_SUCCESS (0x00) Successful IP forwarding enable.
  • NX_PTR_ERROR (0x07) Invalid IP pointer.
  • NX_CALLER_ERROR (0x11) Invalid caller of this service.

Allowed From

Initialization, threads, timers

Preemption Possible

No

Example

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

See Also

  • 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

Disable IP packet fragmenting

Prototype

UINT nx_ip_fragment_disable(NX_IP *ip_ptr);

Description

This service disables IP packet fragmenting and reassembling functionality. For packets waiting to be reassembled, this service releases these packets. On creation of the IP task, this service is automatically disabled.

Parameters

  • ip_ptr: Pointer to previously created IP instance.

Return Values

  • NX_SUCCESS (0x00) Successful IP fragment disable.
  • NX_PTR_ERROR (0x07) Invalid IP pointer.
  • NX_CALLER_ERROR (0x11) Invalid caller of this service.
  • NX_NOT_ENABLED (0x14) IP Fragmentation is not enabled on the IP instance.

Allowed From

Initialization, threads

Preemption Possible

No

Example

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

See Also

  • 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

Enable IP packet fragmenting

Prototype

UINT nx_ip_fragment_enable(NX_IP *ip_ptr);

Description

This service enables IP packet fragmenting and reassembling functionality. On creation of the IP task, this service is automatically disabled.

Parameters

  • ip_ptr: Pointer to previously created IP instance.

Return Values

  • NX_SUCCESS (0x00) Successful IP fragment enable.
  • NX_PTR_ERROR (0x07) Invalid IP pointer.
  • NX_CALLER_ERROR (0x11) Invalid caller of this service.
  • NX_NOT_ENABLED (0x14) IP Fragmentation features is not compiled into NetX.

Allowed From

Initialization, threads

Preemption Possible

No

Example

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

See Also

  • 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

Set Gateway IP address

Prototype

UINT nx_ip_gateway_address_set(
    NX_IP *ip_ptr, 
    ULONG ip_address);

Description

This service sets the IP gateway IP address. All out-of-network traffic are routed to this gateway for transmission. The gateway must be directly accessible through one of the network interfaces.

Parameters

  • ip_ptr: Pointer to previously created IP instance.
  • ip_address: IP address of the gateway.

Return Values

  • NX_SUCCESS (0x00) Successful Gateway IP address set.
  • NX_PTR_ERROR (0x07) Invalid IP instance pointer.
  • NX_IP_ADDRESS_ERROR (0x21) Invalid IP address.
  • NX_CALLER_ERROR (0x11) Invalid caller of this service.

Allowed From

Initialization, thread

Preemption Possible

No

Example

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

See Also

  • nx_ip_info_get, nx_ip_static_route_add, nx_ip_static_route_delete

nx_ip_info_get

Retrieve information about IP activities

Prototype

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);

Description

This service retrieves information about IP activities for the specified IP instance.

If a destination pointer is NX_NULL, that particular information is not returned to the caller.

Parameters

  • ip_ptr: Pointer to previously created IP instance.
  • ip_total_packets_sent: Pointer to destination for the total number of IP packets sent.
  • ip_total_bytes_sent: Pointer to destination for the total number of bytes sent.
  • ip_total_packets_received: Pointer to destination of the total number of IP receive packets.
  • ip_total_bytes_received: Pointer to destination of the total number of IP bytes received.
  • ip_invalid_packets: Pointer to destination of the total number of invalid IP packets.
  • ip_receive_packets_dropped: Pointer to destination of the total number of receive packets dropped.
  • ip_receive_checksum_errors: Pointer to destination of the total number of checksum errors in receive packets.
  • ip_send_packets_dropped: Pointer to destination of the total number of send packets dropped.
  • ip_total_fragments_sent: Pointer to destination of the total number of fragments sent.
  • ip_total_fragments_received: Pointer to destination of the total number of fragments received.

Return Values

  • NX_SUCCESS (0x00) Successful IP information retrieval.
  • NX_CALLER_ERROR (0x11) Invalid caller of this service.
  • NX_PTR_ERROR (0x07) Invalid IP pointer.

Allowed From

Initialization, threads

Preemption Possible

No

Example

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

See Also

  • 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

Retrieve interface IP address

Prototype

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

Description

This service retrieves the IP address of a specified network interface.

The specified device, if not the primary device, must be previously attached to the IP instance.

Parameters

  • ip_ptr: Pointer to previously created IP instance.
  • interface_index: Interface index, the same value as the index to the network interface attached to the IP instance.
  • ip_address: Pointer to destination for the device interface IP address.
  • network_mask: Pointer to destination for the device interface network mask.

Return Values

  • NX_SUCCESS (0x00) Successful IP address get.
  • NX_INVALID_INTERFACE (0x4C) Specified network interface is invalid.
  • NX_CALLER_ERROR (0x11) Invalid caller of this service.
  • NX_PTR_ERROR (0x07) Invalid IP pointer.

Allowed From

Initialization, threads

Preemption Possible

No

Example

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

See Also

  • 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

Set interface IP address and network mask

Prototype

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

Description

This service sets the IP address and network mask for the specified IP interface.

The specified interface must be previously attached to the IP instance.

Parameters

  • ip_ptr: Pointer to previously created IP instance.
  • interface_index: Index of the interface attached to the NetX instance.
  • ip_address: New network interface IP address.
  • network_mask: New interface network mask.

Return Values

  • NX_SUCCESS (0x00) Successful IP address set.
  • NX_INVALID_INTERFACE (0x4C) Specified network interface is invalid.
  • NX_CALLER_ERROR (0x11) Invalid caller of this service.
  • NX_PTR_ERROR (0x07) Invalid pointers.
  • NX_IP_ADDRESS_ERROR (0x21) Invalid IP address

Allowed From

Initialization, threads

Preemption Possible

No

Example

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

See Also

  • 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

Attach network interface to IP instance

Prototype

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 *));

Description

This service adds a physical network interface to the IP interface. Note the IP instance is created with the primary interface so each additional interface is secondary to the primary interface. The total number of network interfaces attached to the IP instance (including the primary interface) cannot exceed NX_MAX_PHYSICAL_INTERFACES.

If the IP thread has not been running yet, the secondary interfaces will be initialized as part of the IP thread startup process that initializes all physical interfaces.

If the IP thread is not running yet, the secondary interface is initialized as part of the nx_ip_interface_attach service.

ip_ptr must point to a valid NetX IP structure.

NX_MAX_PHYSICAL_INTERFACES must be configured for the number of network interfaces for the IP instance. The default value is one.

Parameters

  • ip_ptr: Pointer to previously created IP instance.
  • interface_name: Pointer to interface name string.
  • ip_address: Device IP address in host byte order.
  • network_mask: Device network mask in host byte order.
  • ip_link_driver: Ethernet driver for the interface.

Return Values

  • NX_SUCCESS (0x00) Entry is added to static routing table.
  • NX_NO_MORE_ENTRIES (0x17) Max number of interfaces.
  • NX_MAX_PHYSICAL_INTERFACES is exceeded.
  • NX_DUPLICATED_ENTRY (0x52) The supplied IP address is already used on this IP instance.
  • NX_CALLER_ERROR (0x11) Invalid caller of this service.
  • NX_PTR_ERROR (0x07) Invalid pointer input.
  • NX_IP_ADDRESS_ERROR (0x21) Invalid IP address input.

Allowed From

Initialization, threads

Preemption Possible

No

Example

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

See Also

  • 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

Retrieve network interface parameters

Prototype

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);

Description

This service retrieves information on network parameters for the specified network interface. All data are retrieved in host byte order.

ip_ptr must point to a valid NetX IP structure. The specified interface, if not the primary interface, must be previously attached to the IP instance.

Parameters

  • ip_ptr: Pointer to previously created IP instance.
  • interface_index: Index specifying network interface.
  • interface_name: Pointer to the buffer that holds the name of the network interface.
  • ip_address: Pointer to the destination for the IP address of the interface.
  • network_mask: Pointer to destination for network mask.
  • mtu_size: Pointer to destination for maximum transfer unit for this interface.
  • physical_address_msw: Pointer to destination for top 16 bits of the device MAC address.
  • physical_address_lsw: Pointer to destination for lower 32 bits of the device MAC address.

Return Values

  • NX_SUCCESS (0x00) Interface information has been obtained.
  • NX_PTR_ERROR (0x07) Invalid pointer input.
  • NX_INVALID_INTERFACE (0x4C) Invalid IP pointer.
  • NX_CALLER_ERROR (0x11) Service is not called from system initialization or thread context.

Allowed From

Initialization, threads

Preemption Possible

No

Example

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

See Also

  • 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

Check status of an IP instance

Prototype

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

Description

This service checks and optionally waits for the specified status of the network interface of a previously created IP instance.

Parameters

  • ip_ptr: Pointer to previously created IP instance.
  • interface_index: Interface index number
  • needed_status: IP status requested, defined in bit-map form as follows:
    • 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: Pointer to destination of actual bits set.
  • *wait_option: Defines how the service behaves if the requested status bits are not available. The wait options are defined as follows:
    • NX_NO_WAIT (0x00000000)
    • NX_WAIT_FOREVER (0xFFFFFFFF)
    • timeout value in ticks (0x00000001 through 0xFFFFFFFE)

Return Values

  • NX_SUCCESS (0x00) Successful IP status check.
  • NX_NOT_SUCCESSFUL (0x43) Status request was not satisfied within the timeout specified.
  • NX_PTR_ERROR (0x07) IP pointer is or has become invalid, or actual status pointer is invalid.
  • NX_OPTION_ERROR (0x0a) Invalid needed status option.
  • NX_CALLER_ERROR (0x11) Invalid caller of this service.
  • NX_INVALID_INTERFACE (0x4C) Interface_index is out of range. or the interface is not valid.

Allowed From

Threads

Preemption Possible

No

Example

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

See Also

  • 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

Set the link status change notify callback function

Prototype

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));

Description

This service configures the link status change notify callback function. The user-supplied link_status_change_notify routine is invoked when either the primary or secondary interface status is changed (such as IP address is changed.) If link_status_change_notify is NULL, the link status change notify callback feature is disabled.

Parameters

  • ip_ptr: IP control block pointer
  • link_status_change_notify: User-supplied callback function to be called upon a change to the physical interface.

Return Values

  • NX_SUCCESS (0x00) Successful set
  • NX_PTR_ERROR (0x07) Invalid IP control block pointer or new physical address pointer
  • NX_CALLER_ERROR (0x11) Service is not called from system initialization or thread context.

Allowed From

Initialization, threads

Preemption Possible

No

Example

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

See Also

  • 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

Disable raw packet sending/receiving

Prototype

UINT nx_ip_raw_packet_disable(NX_IP *ip_ptr);

Description

This service disables transmission and reception of raw IP packets for this IP instance. If the raw packet service was previously enabled, and there are raw packets in the receive queue, this service will release any received raw packets.

Parameters

  • ip_ptr: Pointer to previously created IP instance.

Return Values

  • NX_SUCCESS (0x00) Successful IP raw packet disable.
  • NX_PTR_ERROR (0x07) Invalid IP pointer.
  • NX_CALLER_ERROR (0x11) Invalid caller of this service.

Allowed From

Initialization, threads

Preemption Possible

No

Example

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

See Also

  • 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

Enable raw packet processing

Prototype

UINT nx_ip_raw_packet_enable(NX_IP *ip_ptr);

Description

This service enables transmission and reception of raw IP packets for this IP instance. Incoming TCP, UDP, ICMP, and IGMP packets are still processed by NetX. Packets with unknown upper layer protocol types are processed by raw packet reception routine.

Parameters

  • ip_ptr: Pointer to previously created IP instance.

Return Values

  • NX_SUCCESS (0x00) Successful IP raw packet enable.
  • NX_PTR_ERROR (0x07) Invalid IP pointer.
  • NX_CALLER_ERROR (0x11) Invalid caller of this service.

Allowed From

Initialization, threads

Preemption Possible

No

Example

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

See Also

  • 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

Send raw IP packet through specified network interface

Prototype

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);

Description

This service sends a raw IP packet to the destination IP address using the specified local IP address as the source address, and through the associated network interface. Note that this routine returns immediately, and it is, therefore, not known if the IP packet has actually been sent. The network driver will be responsible for releasing the packet when the transmission is complete. This service differs from other services in that there is no way of knowing if the packet was actually sent. It could get lost on the Internet.

Note that raw IP processing must be enabled.

This service is similar to nx_ip_raw_packet_send, except that this service allows an application to send raw IP packet from a specified physical interfaces.

Parameters

  • ip_ptr: Pointer to previously created IP task.
  • packet_ptr: Pointer to packet to transmit.
  • destination_ip: IP address to send packet.
  • address_index: Index of the address of the interface to send packet out on.
  • type_of_service: Type of service for packet.

Return Values

  • NX_SUCCESS (0x00) Packet successfully transmitted.
  • NX_IP_ADDRESS_ERROR (0x21) No suitable outgoing interface available.
  • NX_NOT_ENABLED (0x14) Raw IP packet processing not enabled.
  • NX_CALLER_ERROR (0x11) Invalid caller of this service.
  • NX_PTR_ERROR (0x07) Invalid pointer input.
  • NX_OPTION_ERROR (0x0A) Invalid type of service specified.
  • NX_OVERFLOW (0x03) Invalid packet prepend pointer.
  • NX_UNDERFLOW (0x02) Invalid packet prepend pointer.
  • NX_INVALID_INTERFACE (0x4C) Invalid interface index specified.

Allowed From

Threads

Preemption Possible

No

Example

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

See Also

  • 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

Receive raw IP packet

Prototype

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

Description

This service receives a raw IP packet from the specified IP instance. If there are IP packets on the raw packet receive queue, the first (oldest) packet is returned to the caller. Otherwise, if no packets are available, the caller may suspend as specified by the wait option.

If NX_SUCCESS, is returned, the application is responsible for releasing the received packet when it is no longer needed.

Parameters

  • ip_ptr: Pointer to previously created IP instance.
  • packet_ptr: Pointer to pointer to place the received raw IP packet in.
  • wait_option: Defines how the service behaves if there are no raw IP packets available. The wait options are defined as follows:
    • NX_NO_WAIT (0x00000000)
    • NX_WAIT_FOREVER (0xFFFFFFFF)
    • timeout value in ticks (0x00000001 through 0xFFFFFFFE)

Return Values

  • NX_SUCCESS (0x00) Successful IP raw packet receive.
  • NX_NO_PACKET (0x01) No packet was available.
  • NX_WAIT_ABORTED (0x1A) Requested suspension was aborted by a call to tx_thread_wait_abort.
  • NX_NOT_ENABLED (0x14) This component has not been enabled.
  • NX_PTR_ERROR (0x07) Invalid IP or return packet pointer.
  • NX_CALLER_ERROR (0x11) Invalid caller of this service

Allowed From

Threads

Preemption Possible

No

Example

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

See Also

  • 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

Send raw IP packet

Prototype

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

Description

This service sends a raw IP packet to the destination IP address. Note that this routine returns immediately, and it is therefore not known whether the IP packet has actually been sent. The network driver will be responsible for releasing the packet when the transmission is complete.

For a multihome system, NetX uses the destination IP address to find an appropriate network interface and uses the IP address of the interface as the source address. If the destination IP address is broadcast or multicast, the first valid interface is used. Applications use the nx_ip_raw_packet_interface_send in this case.

Unless an error is returned, the application should not release the packet after this call. Doing so will cause unpredictable results because the network driver will release the packet after transmission.

Parameters

  • ip_ptr: Pointer to previously created IP instance.
  • packet_ptr: Pointer to the raw IP packet to send.
  • destination_ip: Destination IP address, which can be a specific host IP address, a network broadcast, an internal loop-back, or a multicast address.
  • type_of_service: Defines the type of service for the transmission, legal values are as follows:
    • NX_IP_NORMAL (0x00000000)
    • NX_IP_MIN_DELAY (0x00100000)
    • NX_IP_MAX_DATA (0x00080000)
    • NX_IP_MAX_RELIABLE (0x00040000)
    • NX_IP_MIN_COST (0x00020000)

Return Values

  • NX_SUCCESS (0x00) Successful IP raw packet send initiated.
  • NX_IP_ADDRESS_ERROR (0x21) Invalid IP address.
  • NX_NOT_ENABLED (0x14) Raw IP feature is not enabled.
  • NX_OPTION_ERROR (0x0A) Invalid type of service.
  • NX_UNDERFLOW (0x02) Not enough room to prepend an IP header on the packet.
  • NX_OVERFLOW (0x03) Packet append pointer is invalid.
  • NX_PTR_ERROR (0x07) Invalid IP or packet pointer.
  • NX_CALLER_ERROR (0x11) Invalid caller of this service.

Allowed From

Threads

Preemption Possible

No

Example

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

See Also

  • 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

Add static route to the routing table

Prototype

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

Description

This service adds an entry to the static routing table. Note that the next_hop address must be directly accessible from one of the local network devices.

Note that ip_ptr must point to a valid NetX IP structure and the NetX library must be built with NX_ENABLE_IP_STATIC_ROUTING defined to use this service. By default NetX is built without NX_ENABLE_IP_STATIC_ROUTING defined.

Parameters

  • ip_ptr: Pointer to previously created IP instance.
  • network_address: Target network address, in host byte order
  • net_mask: Target network mask, in host byte order
  • next_hop: Next hop address for the target network, in host byte order

Return Values

  • NX_SUCCESS (0x00) Entry is added to the static routing table.
  • NX_OVERFLOW (0x03) Static routing table is full.
  • NX_NOT_SUPPORTED (0x4B) This feature is not compiled in.
  • NX_IP_ADDRESS_ERROR (0x21) Next hop is not directly accessible via local interfaces.
  • NX_CALLER_ERROR (0x11) Invalid caller of this service.
  • NX_PTR_ERROR (0x07) Invalid ip_ptr pointer.

Allowed From

Initialization, threads

Preemption Possible

No

Example

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

See Also

  • nx_ip_gateway_address_set, nx_ip_info_get, nx_ip_static_route_delete

nx_ip_static_route_delete

Delete static route from routing table

Prototype

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

Description

This service deletes an entry from the static routing table.

Note that ip_ptr must point to a valid NetX IP structure and the NetX library must be built with NX_ENABLE_IP_STATIC_ROUTING defined to use this service. By default NetX is built without NX_ENABLE_IP_STATIC_ROUTING defined.

Parameters

  • ip_ptr: Pointer to previously created IP instance.
  • network_address: Target network address, in host byte order.
  • net_mask: Target network mask, in host byte order.

Allowed From

Initialization, threads

Preemption Possible

No

Example

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

See Also

  • nx_ip_gateway_address_set, nx_ip_info_get, nx_ip_static_route_add

nx_ip_status_check

Check status of an IP instance

Prototype

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

Description

This service checks and optionally waits for the specified status of the primary network interface of a previously created IP instance. To obtain status on secondary interfaces, applications shall use the service nx_ip_interface_status_check.

Parameters

  • ip_ptr: Pointer to previously created IP instance.
  • needed_status: IP status requested, defined in bit-map form as follows:
    • 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: Pointer to destination of actual bits set.
  • wait_option: Defines how the service behaves if the requested status bits are not available. The wait options are defined as follows:
    • NX_NO_WAIT (0x00000000)
    • NX_WAIT_FOREVER (0xFFFFFFFF)
    • timeout value in ticks (0x00000001 through 0xFFFFFFFE)

Return Values

  • NX_SUCCESS (0x00) Successful IP status check.
  • NX_NOT_SUCCESSFUL (0x43) Status request was not satisfied within the timeout specified.
  • NX_PTR_ERROR (0x07) IP pointer is or has become invalid, or actual status pointer is invalid.
  • NX_OPTION_ERROR (0x0a) Invalid needed status option.
  • NX_CALLER_ERROR (0x11) Invalid caller of this service.

Allowed From

Threads

Preemption Possible

No

Example

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

See Also

  • 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

Allocate packet from specified pool

Prototype

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

Description

This service allocates a packet from the specified pool and adjusts the prepend pointer in the packet according to the type of packet specified. If no packet is available, the service suspends according to the supplied wait option.

Parameters

  • pool_ptr: Pointer to previously created packet pool.
  • packet_ptr: Pointer to the pointer of the allocated packet pointer.
  • packet_type: Defines the type of packet requested. See “Packet Pools” on page 49 in Chapter 3 for a list of supported packet types.
  • wait_option: Defines the wait time in ticks if there are no packets available in the packet pool. The wait options are defined as follows:
    • NX_NO_WAIT (0x00000000)
    • NX_WAIT_FOREVER (0xFFFFFFFF)
    • timeout value in ticks (0x00000001 through 0xFFFFFFFE)

Return Values

  • NX_SUCCESS (0x00) Successful packet allocate.
  • NX_NO_PACKET (0x01) No packet available.
  • NX_WAIT_ABORTED (0x1A) Requested suspension was aborted by a call to tx_thread_wait_abort.
  • NX_INVALID_PARAMETERS (0x4D) Packet size cannot support protocol.
  • NX_OPTION_ERROR (0x0A) Invalid packet type.
  • NX_PTR_ERROR (0x07) Invalid pool or packet return pointer.
  • NX_CALLER_ERROR (0x11) Invalid wait option from nonthread.

Allowed From

Initialization, threads, timers, and ISRs (application network drivers). Wait option must be NX_NO_WAIT when used in ISR or in timer context.

Preemption Possible

No

Example

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

See Also

  • 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

Copy packet

Prototype

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

Description

This service copies the information in the supplied packet to one or more new packets that are allocated from the supplied packet pool. If successful, the pointer to the new packet is returned in destination pointed to by new_packet_ptr.

Parameters

  • packet_ptr: Pointer to the source packet.
  • new_packet_ptr: Pointer to the destination of where to return the pointer to the new copy of the packet.
  • pool_ptr: Pointer to the previously created packet pool that is used to allocate one or more packets for the copy.
  • wait_option: Defines how the service waits if there are no packets available. The wait options are defined as follows:
    • NX_NO_WAIT (0x00000000)
    • NX_WAIT_FOREVER (0xFFFFFFFF)
    • timeout value in ticks (0x00000001 through 0xFFFFFFFE)

Return Values

  • NX_SUCCESS (0x00) Successful packet copy.
  • NX_NO_PACKET (0x01) Packet not available for copy.
  • NX_INVALID_PACKET (0x12) Empty source packet or copy failed.
  • NX_WAIT_ABORTED (0x1A) Requested suspension was aborted by a call to tx_thread_wait_abort.
  • NX_INVALID_PARAMETERS (0x4D) Packet size cannot support protocol.
  • NX_PTR_ERROR (0x07) Invalid pool, packet, or destination pointer.
  • NX_UNDERFLOW (0x02) Invalid packet prepend pointer.
  • NX_OVERFLOW (0x03) Invalid packet append pointer.
  • NX_CALLER_ERROR (0x11) A wait option was specified in initialization or in an ISR.

Allowed From

Initialization, threads, timers, and ISRs

Preemption Possible

No

Example

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

See Also

  • 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

Append data to end of packet

Prototype

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

Description

This service appends data to the end of the specified packet. The supplied data area is copied into the packet. If there is not enough memory available, and the chained packet feature is enabled, one or more packets will be allocated to satisfy the request. If the chained packet feature is not enabled, NX_SIZE_ERROR is returned.

Parameters

  • packet_ptr: Packet pointer.
  • data_start: Pointer to the start of the user’s data area to append to the packet.
  • data_size: Size of user’s data area.
  • pool_ptr: Pointer to packet pool from which to allocate another packet if there is not enough room in the current packet.
  • wait_option: Defines how the service behaves if there are no packets available. The wait options are defined as follows:
    • NX_NO_WAIT (0x00000000)
    • NX_WAIT_FOREVER (0xFFFFFFFF)
    • timeout value in ticks (0x00000001 through 0xFFFFFFFE)

Return Values

  • NX_SUCCESS (0x00) Successful packet append.
  • NX_NO_PACKET (0x01) No packet available.
  • NX_WAIT_ABORTED (0x1A) Requested suspension was aborted by a call to tx_thread_wait_abort.
  • NX_INVALID_PARAMETERS (0x4D) Packet size cannot support protocol.
  • NX_UNDERFLOW (0x02) Prepend pointer is less than payload start.
  • NX_OVERFLOW (0x03) Append pointer is greater than payload end.
  • NX_PTR_ERROR (0x07) Invalid pool, packet, or data Pointer.
  • NX_SIZE_ERROR (0x09) Invalid data size.
  • NX_CALLER_ERROR (0x11) Invalid wait option from nonthread.

Allowed From

Initialization, threads, timers, and ISRs (application network drivers)

Preemption Possible

No

Example

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

See Also

  • 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

Extract data from packet via an offset

Prototype

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

Description

This service copies data from a NetX packet (or packet chain) starting at the specified offset from the packet prepend pointer of the specified size in bytes into the specified buffer. The number of bytes actually copied is returned in bytes_copied. This service does not remove data from the packet, nor does it adjust the prepend pointer or other internal state information.

Parameters

  • packet_ptr: Pointer to packet to extract
  • offset: Offset from the current prepend pointer.
  • buffer_start: Pointer to start of save buffer
  • buffer_length: Number of bytes to copy
  • bytes_copied: Number of bytes actually copied

Return Values

  • NX_SUCCESS (0x00) Successful packet copy
  • NX_PACKET_OFFSET_ERROR (0x53) Invalid offset value was supplied
  • NX_PTR_ERROR (0x07) Invalid packet pointer or buffer pointer

Allowed From

Initialization, threads, timers, and ISRs

Preemption Possible

No

Example

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

See Also

  • 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

Retrieve data from packet

Prototype

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

Description

This service copies data from the supplied packet into the supplied buffer. The actual number of bytes copied is returned in the destination pointed to by bytes_copied.

Note that this service does not change internal state of the packet. The data being retrieved is still available in the packet.

The destination buffer must be large enough to hold the packet's contents. If not, memory will be corrupted causing unpredictable results.

Parameters

  • packet_ptr: Pointer to the source packet.
  • buffer_start: Pointer to the start of the buffer area.
  • bytes_copied: Pointer to the destination for the number of bytes copied.

Return Values

  • NX_SUCCESS (0x00) Successful packet data retrieve.
  • NX_INVALID_PACKET (0x12) Invalid packet.
  • NX_PTR_ERROR (0x07) Invalid packet, buffer start, or bytes copied pointer.

Allowed From

Initialization, threads, timers, and ISRs

Preemption Possible

No

Example

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

See Also

  • 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

Get length of packet data

Prototype

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

Description

This service gets the length of the data in the specified packet.

Parameters

  • packet_ptr: Pointer to the packet.
  • length: Destination for the packet length.

Allowed From

Initialization, threads, timers, and ISRs

Preemption Possible

No

Example

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

See Also

  • 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

Create packet pool in specified memory area

Prototype

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

Description

This service creates a packet pool of the specified packet size in the memory area supplied by the user.

Parameters

  • pool_ptr: Pointer to packet pool control block.
  • name: Pointer to application’s name for the packet pool.
  • payload_size: Number of bytes in each packet in the pool. This value must be at least 40 bytes and must also be evenly divisible by 4.
  • memory_ptr: Pointer to the memory area to place the packet pool in. The pointer should be aligned on an ULONG boundary.
  • memory_size: Size of the pool memory area.

Return Values

  • NX_SUCCESS (0x00) Successful packet pool create.
  • NX_PTR_ERROR (0x07) Invalid pool or memory pointer.
  • NX_SIZE_ERROR (0x09) Invalid block or memory size.
  • NX_CALLER_ERROR (0x11) Invalid caller of this service.

Allowed From

Initialization, threads

Preemption Possible

No

Example

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

See Also

  • 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

Delete previously created packet pool

Prototype

UINT nx_packet_pool_delete(NX_PACKET_POOL *pool_ptr);

Description

This service deletes a previously-created packet pool. NetX checks for any threads currently suspended on packets in the packet pool and clears the suspension.

Parameters

  • pool_ptr: Packet pool control block pointer.

Return Values

  • NX_SUCCESS (0x00) Successful packet pool delete.
  • NX_PTR_ERROR (0x07) Invalid pool pointer.
  • NX_CALLER_ERROR (0x11) Invalid caller of this service.

Allowed From

Threads

Preemption Possible

Yes

Example

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

See Also

  • 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

Retrieve information about a packet pool

Prototype

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);

Description

This service retrieves information about the specified packet pool.

If a destination pointer is NX_NULL, that particular information is not returned to the caller.

Parameters

  • pool_ptr: Pointer to previously created packet pool.
  • total_packets: Pointer to destination for the total number of packets in the pool.
  • free_packets: Pointer to destination for the total number of currently free packets.
  • empty_pool_requests: Pointer to destination of the total number of allocation requests when the pool was empty.
  • empty_pool_suspensions: Pointer to destination of the total number of empty pool suspensions.
  • invalid_packet_releases: Pointer to destination of the total number of invalid packet releases.

Return Values

  • NX_SUCCESS (0x00) Successful packet pool information retrieval.
  • NX_PTR_ERROR (0x07) Invalid IP pointer.
  • NX_CALLER_ERROR (0x11) Invalid caller of this service.

Allowed From

Initialization, threads, and timers

Preemption Possible

No

Example

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

See Also

  • 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

Release previously allocated packet

Prototype

UINT nx_packet_release(NX_PACKET *packet_ptr);

Description

This service releases a packet, including any additional packets chained to the specified packet. If another thread is blocked on packet allocation, it is given the packet and resumed.

The application must prevent releasing a packet more than once, because doing so will cause unpredictable results.

Parameters

  • packet_ptr: Packet pointer.

Return Values

  • NX_SUCCESS (0x00) Successful packet release.
  • NX_PTR_ERROR (0x07) Invalid packet pointer.
  • NX_UNDERFLOW (0x02) Prepend pointer is less than payload start.
  • NX_OVERFLOW (0x03) Append pointer is greater than payload end.

Allowed From

Initialization, threads, timers, and ISRs (application network drivers)

Preemption Possible

Yes

Example

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

See Also

  • 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

Release a transmitted packet

Prototype

UINT nx_packet_transmit_release(NX_PACKET *packet_ptr);

Description

For non-TCP packets, this service releases a transmitted packet, including any additional packets chained to the specified packet. If another thread is blocked on packet allocation, it is given the packet and resumed. For a transmitted TCP packet, the packet is marked as being transmitted but not released till the packet is acknowledged. This service is typically called from the application's network driver after a packet is transmitted.

The network driver should remove the physical media header and adjust the length of the packet before calling this service.

Parameters

  • packet_ptr: Packet pointer.

Return Values

  • NX_SUCCESS (0x00) Successful transmit packet release.
  • NX_PTR_ERROR (0x07) Invalid packet pointer.
  • NX_UNDERFLOW (0x02) Prepend pointer is less than payload start.
  • NX_OVERFLOW (0x03) Append pointer is greater than payload end.

Allowed From

Initialization, threads, timers, Application network drivers (including ISRs)

Preemption Possible

Yes

Example

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

See Also

  • 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

Disable Reverse Address Resolution Protocol (RARP)

Prototype

UINT nx_rarp_disable(NX_IP *ip_ptr);

Description

This service disables the RARP component of NetX for the specific IP instance. For a multihome system, this service disables RARP on all interfaces.

Parameters

  • ip_ptr: Pointer to previously created IP instance.

Return Values

  • NX_SUCCESS (0x00) Successful RARP disable.
  • NX_NOT_ENABLED (0x14) RARP was not enabled.
  • NX_PTR_ERROR (0x07) Invalid IP pointer.
  • NX_CALLER_ERROR (0x11) Invalid caller of this service.

Allowed From

Initialization, threads

Preemption Possible

No

Example

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

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

See Also

  • nx_rarp_enable, nx_rarp_info_get

nx_rarp_enable

Enable Reverse Address Resolution Protocol (RARP)

Prototype

UINT nx_rarp_enable(NX_IP *ip_ptr);

Description

This service enables the RARP component of NetX for the specific IP instance. The RARP components searches through all attached network interfaces for zero IP address. A zero IP address indicates the interface does not have IP address assignment yet. RARP attempts to resolve the IP address by enabling RARP process on that interface.

Parameters

  • ip_ptr: Pointer to previously created IP instance.

Return Values

  • NX_SUCCESS (0x00) Successful RARP enable.
  • NX_IP_ADDRESS_ERROR (0x21) IP address is already valid.
  • NX_ALREADY_ENABLED (0x15) RARP was already enabled.
  • NX_PTR_ERROR (0x07) Invalid IP pointer.
  • NX_CALLER_ERROR (0x11) Invalid caller of this service.

Allowed From

Initialization, threads, timers

Preemption Possible

No

Example

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

See Also

  • nx_rarp_disable, nx_rarp_info_get

nx_rarp_info_get

Retrieve information about RARP activities

Prototype

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

Description

This service retrieves information about RARP activities for the specified IP instance.

If a destination pointer is NX_NULL, that particular information is not returned to the caller.

Parameters

  • ip_ptr: Pointer to previously created IP instance.
  • rarp_requests_sent: Pointer to destination for the total number of RARP requests sent.
  • rarp_responses_received: Pointer to destination for the total number of RARP responses received.
  • rarp_invalid_messages: Pointer to destination of the total number of invalid messages.

Return Values

  • NX_SUCCESS (0x00) Successful RARP information retrieval.
  • NX_PTR_ERROR (0x07) Invalid IP pointer.
  • NX_NOT_ENABLED (0x14) This component has not been enabled.
  • NX_CALLER_ERROR (0x11) Invalid caller of this service.

Allowed From

Initialization, threads

Preemption Possible

No

Example

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

See Also

  • nx_rarp_disable, nx_rarp_enable

nx_system_initialize

Initialize NetX System

Prototype

VOID nx_system_initialize(VOID);

Description

This service initializes the basic NetX system resources in preparation for use. It should be called by the application during initialization and before any other NetX call are made.

Parameters

None

Return Values

None

Allowed From

Initialization, threads, timers, ISRs

Preemption Possible

No

Example

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

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

See Also

  • 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_ip_status_check

nx_tcp_client_socket_bind

Bind client TCP socket to TCP port

Prototype

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

Description

This service binds the previously created TCP client socket to the specified TCP port. Valid TCP sockets range from 0 through 0xFFFF. If the specified TCP port is unavailable, the service suspends according to the supplied wait option.

Parameters

  • socket_ptr: Pointer to previously created TCP socket instance.
  • port: Port number to bind (1 through 0xFFFF). If port number is NX_ANY_PORT (0x0000), the IP instance will search for the next free port and use that for the binding.
  • wait_option: Defines how the service behaves if the port is already bound to another socket. The wait options are defined as follows:
    • NX_NO_WAIT (0x00000000)
    • NX_WAIT_FOREVER (0xFFFFFFFF)
    • timeout value in ticks (0x00000001 through 0xFFFFFFFE)

Return Values

  • NX_SUCCESS (0x00) Successful socket bind.
  • NX_ALREADY_BOUND (0x22) This socket is already bound to another TCP port.
  • NX_PORT_UNAVAILABLE (0x23) Port is already bound to a different socket.
  • NX_NO_FREE_PORTS (0x45) No free port.
  • NX_WAIT_ABORTED (0x1A) Requested suspension was aborted by a call to tx_thread_wait_abort.
  • NX_INVALID_PORT (0x46) Invalid port.
  • NX_PTR_ERROR (0x07) Invalid socket pointer.
  • NX_CALLER_ERROR (0x11) Invalid caller of this service.
  • NX_NOT_ENABLED (0x14) This component has not been enabled.

Allowed From

Threads

Preemption Possible

No

Example

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

See Also

  • 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_state_wait

nx_tcp_client_socket_connect

Connect client TCP socket

Prototype

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

Description

This service connects the previously-created and bound TCP client socket to the specified server's port. Valid TCP server ports range from 0 through 0xFFFF. If the connection does not complete immediately, the service suspends according to the supplied wait option.

Parameters

  • socket_ptr: Pointer to previously created TCP socket instance.
  • server_ip: Server’s IP address.
  • server_port: Server port number to connect to (1 through 0xFFFF).
  • wait_option: Defines how the service behaves while the connection is being established. The wait options are defined as follows:
    • NX_NO_WAIT (0x00000000)
    • NX_WAIT_FOREVER (0xFFFFFFFF)
    • timeout value in ticks (0x00000001 through 0xFFFFFFFE)

Return Values

  • NX_SUCCESS (0x00) Successful socket connect.
  • NX_NOT_BOUND (0x24) Socket is not bound.
  • NX_NOT_CLOSED (0x35) Socket is not in a closed state.
  • NX_IN_PROGRESS (0x37) No wait was specified, the connection attempt is in progress.
  • NX_INVALID_INTERFACE (0x4C) Invalid interface supplied.
  • NX_WAIT_ABORTED (0x1A) Requested suspension was aborted by a call to tx_thread_wait_abort.
  • NX_IP_ADDRESS_ERROR (0x21) Invalid server IP address.
  • NX_INVALID_PORT (0x46) Invalid port.
  • NX_PTR_ERROR (0x07) Invalid socket pointer.
  • NX_CALLER_ERROR (0x11) Invalid caller of this service.
  • NX_NOT_ENABLED (0x14) This component has not been enabled.

Allowed From

Threads

Preemption Possible

No

Example

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

See Also

  • nx_tcp_client_socket_bind, 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_state_wait

nx_tcp_client_socket_port_get

Get port number bound to client TCP socket

Prototype

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

Description

This service retrieves the port number associated with the socket, which is useful to find the port allocated by NetX in situations where the NX_ANY_PORT was specified at the time the socket was bound.

Parameters

  • socket_ptr: Pointer to previously created TCP socket instance.
  • port_ptr: Pointer to destination for the return port number. Valid port numbers are (1 through 0xFFFF).

Return Values

  • *NX_SUCCESS: (0x00) Successful socket bind.
  • *NX_NOT_BOUND: (0x24) This socket is not bound to a port.
  • NX_PTR_ERROR (0x07) Invalid socket pointer or port return pointer.
  • NX_CALLER_ERROR (0x11) Invalid caller of this service.
  • NX_NOT_ENABLED (0x14) This component has not been enabled.

Allowed From

Threads

Preemption Possible

No

Example

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

See Also

  • 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

Unbind TCP client socket from TCP port

Prototype

UINT nx_tcp_client_socket_unbind(NX_TCP_SOCKET *socket_ptr);

Description

This service releases the binding between the TCP client socket and a TCP port. If there are other threads waiting to bind another socket to the same port number, the first suspended thread is then bound to this port.

Parameters

  • socket_ptr: Pointer to previously created TCP socket instance.

Return Values

  • NX_SUCCESS (0x00) Successful socket unbind.
  • NX_NOT_BOUND (0x24) Socket was not bound to any port.
  • NX_NOT_CLOSED (0x35) Socket has not been disconnected.
  • NX_PTR_ERROR (0x07) Invalid socket pointer.
  • NX_CALLER_ERROR (0x11) Invalid caller of this service.
  • NX_NOT_ENABLED (0x14) This component has not been enabled.

Allowed From

Threads

Preemption Possible

Yes

Example

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

See Also

  • nx_tcp_client_socket_bind, nx_tcp_client_socket_connect,
  • nx_tcp_client_socket_port_get, 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_enable

Enable TCP component of NetX

Prototype

UINT nx_tcp_enable(NX_IP *ip_ptr);

Description

This service enables the Transmission Control Protocol (TCP) component of NetX. After enabled, TCP connections may be established by the application.

Parameters

  • ip_ptr: Pointer to previously created IP instance.

Return Values

  • NX_SUCCESS (0x00) Successful TCP enable.
  • NX_ALREADY_ENABLED (0x15) TCP is already enabled.
  • NX_PTR_ERROR (0x07) Invalid IP pointer.
  • NX_CALLER_ERROR (0x11) Invalid caller of this service.

Allowed From

Initialization, threads, timers

Preemption Possible

No

Example

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

See Also

  • 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

Find next available TCP port

Prototype

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

Description

This service attempts to locate a free TCP port (unbound) starting from the application supplied port. The search logic will wrap around if the search happens to reach the maximum port value of 0xFFFF. If the search is successful, the free port is returned in the variable pointed to by free_port_ptr.

This service can be called from another thread and have the same port returned. To prevent this race condition, the application may wish to place this service and the actual client socket bind under the protection of a mutex.

Parameters

  • ip_ptr: Pointer to previously created IP instance.
  • port: Port number to start search at (1 through 0xFFFF).
  • free_port_ptr: Pointer to the destination free port return value.

Return Values

  • NX_SUCCESS (0x00) Successful free port find.
  • NX_NO_FREE_PORTS (0x45) No free ports found.
  • NX_PTR_ERROR (0x07) Invalid IP pointer.
  • NX_CALLER_ERROR (0x11) Invalid caller of this service.
  • NX_NOT_ENABLED (0x14) This component has not been enabled.
  • NX_INVALID_PORT (0x46) The specified port number is invalid.

Allowed From

Threads

Preemption Possible

No

Example

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

See Also

  • 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

Retrieve information about TCP activities

Prototype

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);

Description

This service retrieves information about TCP activities for the specified IP instance.

If a destination pointer is NX_NULL, that particular information is not returned to the caller.

Parameters

  • ip_ptr: Pointer to previously created IP instance.
  • tcp_packets_sent: Pointer to destination for the total number of TCP packets sent.
  • tcp_bytes_sent: Pointer to destination for the total number of TCP bytes sent.
  • tcp_packets_received: Pointer to destination of the total number of TCP packets received.
  • tcp_bytes_received: Pointer to destination of the total number of TCP bytes received.
  • tcp_invalid_packets: Pointer to destination of the total number of invalid TCP packets.
  • tcp_receive_packets_dropped: Pointer to destination of the total number of TCP receive packets dropped.
  • tcp_checksum_errors: Pointer to destination of the total number of TCP packets with checksum errors.
  • tcp_connections: Pointer to destination of the total number of TCP connections.
  • tcp_disconnections: Pointer to destination of the total number of TCP disconnections.
  • tcp_connections_dropped: Pointer to destination of the total number of TCP connections dropped.
  • tcp_retransmit_packets: Pointer to destination of the total number of TCP packets retransmitted.

Return Values

  • NX_SUCCESS (0x00) Successful TCP information retrieval.
  • NX_PTR_ERROR (0x07) Invalid IP pointer.
  • NX_CALLER_ERROR (0x11) Invalid caller of this service.
  • NX_NOT_ENABLED (0x14) This component has not been enabled.

Allowed From

Initialization, threads

Preemption Possible

No

Example

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

See Also

  • 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

Accept TCP connection

Prototype

UINT nx_tcp_server_socket_accept(
    NX_TCP_SOCKET *socket_ptr, 
    ULONG wait_option);

Description

This service accepts (or prepares to accept) a TCP client socket connection request for a port that was previously set up for listening. This service may be called immediately after the application calls the listen or re-listen service, or after the listen callback routine is called when the client connection is actually present. If a connection cannot not be established right away, the service suspends according to the supplied wait option.

The application must call nx_tcp_server_socket_unaccept after the connection is no longer needed to remove the server socket's binding to the server port.

*Application callback routines are called from within the IP's helper thread.

Parameters

  • socket_ptr: Pointer to the TCP server socket control block.
  • wait_option: Defines how the service behaves while the connection is being established. The wait options are defined as follows:
    • NX_NO_WAIT (0x00000000)
    • NX_WAIT_FOREVER (0xFFFFFFFF)
    • timeout value in ticks (0x00000001 through 0xFFFFFFFE)

Return Values

  • NX_SUCCESS (0x00) Successful TCP server socket accept (passive connect).
  • NX_NOT_LISTEN_STATE (0x36) The server socket supplied is not in a listen state.
  • NX_IN_PROGRESS (0x37) No wait was specified, the connection attempt is in progress.
  • NX_WAIT_ABORTED (0x1A) Requested suspension was aborted by a call to tx_thread_wait_abort.
  • NX_PTR_ERROR (0x07) Socket pointer error.
  • NX_CALLER_ERROR (0x11) Invalid caller of this service.
  • NX_NOT_ENABLED (0x14) This component has not been enabled.

Allowed From

Initialization, threads

Preemption Possible

No

Example

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);
}

See Also

  • 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

Enable listening for client connection on TCP port

Prototype

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));

Description

This service enables listening for a client connection request on the specified TCP port. When a client connection request is received, the supplied server socket is bound to the specified port and the supplied listen callback function is called.

The listen callback routine's processing is completely up to the application. It may contain logic to wake up an application thread that subsequently performs an accept operation. If the application already has a thread suspended on accept processing for this socket, the listen callback routine may not be needed.

If the application wishes to handle additional client connections on the same port, the nx_tcp_server_socket_relisten must be called with an available socket (a socket in the CLOSED state) for the next connection. Until the re-listen service is called, additional client connections are queued. When the maximum queue depth is exceeded, the oldest connection request is dropped in favor of queuing the new connection request. The maximum queue depth is specified by this service.

Application callback routines are called from the internal IP helper thread.

Parameters

  • ip_ptr: Pointer to previously created IP instance.
  • port: Port number to listen on (1 through 0xFFFF).
  • socket_ptr: Pointer to socket to use for the connection.
  • listen_queue_size: Number of client connection requests that can be queued.
  • listen_callback: Application function to call when the connection is received. If a NULL is specified, the listen callback feature is disabled.

Return Values

  • NX_SUCCESS (0x00) Successful TCP port listen enable.
  • NX_MAX_LISTEN (0x33) No more listen request structures are available. The constant NX_MAX_LISTEN_REQUESTS in nx_api.h defines how many active listen requests are possible.
  • NX_NOT_CLOSED (0x35) The supplied server socket is not in a closed state.
  • NX_ALREADY_BOUND (0x22) The supplied server socket is already bound to a port.
  • NX_DUPLICATE_LISTEN (0x34) There is already an active listen request for this port.
  • NX_INVALID_PORT (0x46) Invalid port specified.
  • NX_PTR_ERROR (0x07) Invalid IP or socket pointer.
  • NX_CALLER_ERROR (0x11) Invalid caller of this service.
  • NX_NOT_ENABLED (0x14) This component has not been enabled.

Allowed From

Threads

Preemption Possible

No

Example

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);

See Also

  • 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

Re-listen for client connection on TCP port

Prototype

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

Description

This service is called after a connection has been received on a port that was setup previously for listening. The main purpose of this service is to provide a new server socket for the next client connection. If a connection request is queued, the connection will be processed immediately during this service call.

The same callback routine specified by the original listen request is also called when a connection is present for this new server socket.

Parameters

  • ip_ptr: Pointer to previously created IP instance.
  • port: Port number to re-listen on (1 through 0xFFFF).
  • socket_ptr: Socket to use for the next client connection.

Return Values

  • NX_SUCCESS (0x00) Successful TCP port re-listen.
  • NX_NOT_CLOSED (0x35) The supplied server socket is not in a closed state.
  • NX_ALREADY_BOUND (0x22) The supplied server socket is already bound to a port.
  • NX_INVALID_RELISTEN (0x47) There is already a valid socket pointer for this port or the port specified does not have a listen request active.
  • NX_CONNECTION_PENDING (0x48) Same as NX_SUCCESS, except there was a queued connection request and it was processed during this call.
  • NX_INVALID_PORT (0x46) Invalid port specified.
  • NX_PTR_ERROR (0x07) Invalid IP or listen callback pointer.
  • NX_CALLER_ERROR (0x11) Invalid caller of this service.
  • NX_NOT_ENABLED (0x14) This component has not been enabled.

Allowed From

Threads

Preemption Possible

No

Example

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);
}

See Also

  • 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

Remove socket association with listening port

Prototype

UINT nx_tcp_server_socket_unaccept(NX_TCP_SOCKET *socket_ptr);

Description

This service removes the association between this server socket and the specified server port. The application must call this service after a disconnection or after an unsuccessful accept call.

Parameters

  • socket_ptr: Pointer to previously setup server socket instance.

Return Values

  • NX_SUCCESS (0x00) Successful server socket unaccept.
  • NX_NOT_LISTEN_STATE (0x36) Server socket is in an improper state, and is probably not disconnected.
  • NX_PTR_ERROR (0x07) Invalid socket pointer.
  • NX_CALLER_ERROR (0x11) Invalid caller of this service.
  • NX_NOT_ENABLED (0x14) This component has not been enabled.

Allowed From

Threads

Preemption Possible

No

Example

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);
}

See Also

  • 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

Disable listening for client connection on TCP port

Prototype

UINT nx_tcp_server_socket_unlisten(NX_IP *ip_ptr, UINT port);

Description

This service disables listening for a client connection request on the specified TCP port.

Parameters

  • ip_ptr: Pointer to previously created IP instance.
  • port: Number of port to disable listening (0 through 0xFFFF).

Return Values

  • NX_SUCCESS (0x00) Successful TCP listen disable.
  • NX_ENTRY_NOT_FOUND (0x16) Listening was not enabled for the specified port.
  • NX_INVALID_PORT (0x46) Invalid port specified.
  • NX_PTR_ERROR (0x07) Invalid IP pointer.
  • NX_CALLER_ERROR (0x11) Invalid caller of this service.
  • NX_NOT_ENABLED (0x14) This component has not been enabled.

Allowed From

Threads

Preemption Possible

No

Example

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);
}

See Also

  • 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

Retrieves number of bytes available for retrieval

Prototype

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

Description

This service obtains the number of bytes available for retrieval in the specified TCP socket. Note that the TCP socket must already be connected.

Parameters

  • socket_ptr: Pointer to previously created and connected TCP socket.
  • bytes_available: Pointer to destination for bytes available.

Return Values

  • NX_SUCCESS (0x00) Service executes successfully. Number of bytes available for read is returned to the caller.
  • NX_NOT_CONNECTED (0x38) Socket is not in a connected state.
  • NX_PTR_ERROR (0x07) Invalid pointers.
  • NX_NOT_ENABLED (0x14) TCP is not enabled.
  • NX_CALLER_ERROR (0x11) Invalid caller of this service.

Allowed From

Threads

Preemption Possible

No

Example

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

See Also

  • 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

Create TCP client or server socket

Prototype

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));

Description

This service creates a TCP client or server socket for the specified IP instance.

Application callback routines are called from the thread associated with this IP instance.

Parameters

  • ip_ptr: Pointer to previously created IP instance.
  • socket_ptr: Pointer to new TCP socket control block.
  • name: Application name for this TCP socket.
  • type_of_service: Defines the type of service for the transmission, legal values are as follows:
    • 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: Specifies whether or not IP fragmenting is allowed. If NX_FRAGMENT_OKAY (0x0) is specified, IP fragmenting is allowed. If NX_DONT_FRAGMENT (0x4000) is specified, IP fragmenting is disabled.
  • time_to_live: Specifies the 8-bit value that defines how many routers this packet can pass before being thrown away. The default value is specified by NX_IP_TIME_TO_LIVE.
  • window_size: Defines the maximum number of bytes allowed in the receive queue for this socket
  • urgent_data_callback: Application function that is called whenever urgent data is detected in the receive stream. If this value is NX_NULL, urgent data is ignored.
  • disconnect_callback: Application function that is called whenever a disconnect is issued by the socket at the other end of the connection. If this value is NX_NULL, the disconnect callback function is disabled.

Return Values

  • NX_SUCCESS (0x00) Successful TCP client socket create.
  • NX_OPTION_ERROR (0x0A) Invalid type-of-service, fragment, invalid window size, or time-tolive option.
  • NX_PTR_ERROR (0x07) Invalid IP or socket pointer.
  • NX_CALLER_ERROR (0x11) Invalid caller of this service.
  • NX_NOT_ENABLED (0x14) This component has not been enabled.

Allowed From

Initialization and Threads

Preemption Possible

No

Example

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

See Also

  • 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

Delete TCP socket

Prototype

UINT nx_tcp_socket_delete(NX_TCP_SOCKET *socket_ptr);

Description

This service deletes a previously created TCP socket. If the socket is still bound or connected, the service returns an error code.

Parameters

  • socket_ptr: Previously created TCP socket

Return Values

  • NX_SUCCESS (0x00) Successful socket delete.
  • NX_NOT_CREATED (0x27) Socket was not created.
  • NX_STILL_BOUND (0x42) Socket is still bound.
  • NX_PTR_ERROR (0x07) Invalid socket pointer.
  • NX_CALLER_ERROR (0x11) Invalid caller of this service.
  • NX_NOT_ENABLED (0x14) This component has not been enabled.

Allowed From

Threads

Preemption Possible

No

Example

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

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

See Also

  • 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

Disconnect client and server socket connections

Prototype

UINT nx_tcp_socket_disconnect(
    NX_TCP_SOCKET *socket_ptr,
    ULONG wait_option);

Description

This service disconnects an established client or server socket connection. A disconnect of a server socket should be followed by an unaccept request, while a client socket that is disconnected is left in a state ready for another connection request. If the disconnect process cannot finish immediately, the service suspends according to the supplied wait option.

Parameters

  • socket_ptr: Pointer to previously connected client or server socket instance.
  • wait_option: Defines how the service behaves while the disconnection is in progress. The wait options are defined as follows:
    • NX_NO_WAIT (0x00000000)
    • NX_WAIT_FOREVER (0xFFFFFFFF)
    • timeout value in ticks (0x00000001 through 0xFFFFFFFE)

Return Values

  • NX_SUCCESS (0x00) Successful socket disconnect.
  • NX_NOT_CONNECTED (0x38) Specified socket is not connected.
  • NX_IN_PROGRESS (0x37) Disconnect is in progress, no wait was specified.
  • NX_WAIT_ABORTED (0x1A) Requested suspension was aborted by a call to tx_thread_wait_abort.
  • NX_PTR_ERROR (0x07) Invalid socket pointer.
  • NX_CALLER_ERROR (0x11) Invalid caller of this service.
  • NX_NOT_ENABLED (0x14) This component has not been enabled.

Allowed From

Threads

Preemption Possible

Yes

Example

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

See Also

  • 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

Install TCP disconnect complete notify callback function

Prototype

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

Description

This service registers a callback function which is invoked after a socket disconnect operation is completed. The TCP socket disconnect complete callback function is available if NetX is built with the option NX_ENABLE_EXTENDED_NOTIFY_SUPPORT defined.

Parameters

  • socket_ptr: Pointer to previously connected client or server socket instance.
  • tcp_disconnect_complete_notify: The callback function to be installed.

Return Values

  • NX_SUCCESS (0x00) Successfully registered the callback function.
  • NX_NOT_SUPPORTED (0x4B) The extended notify feature is not built into the NetX library
  • NX_PTR_ERROR (0x07) Invalid socket pointer.
  • NX_CALLER_ERROR (0x11) Invalid caller of this service.
  • NX_NOT_ENABLED (0x14) TCP feature is not enabled.

Allowed From

Initialization, threads

Preemption Possible

No

Example

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

See Also

  • 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

Set TCP establish notify callback function

Prototype

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

Description

This service registers a callback function, which is called after a TCP socket makes a connection. The TCP socket establish callback function is available if NetX is built with the option NX_ENABLE_EXTENDED_NOTIFY_SUPPORT defined.

Parameters

  • socket_ptr: Pointer to previously connected client or server socket instance.
  • tcp_establish_notify: Callback function invoked after a TCP connection is established.

Return Values

  • NX_SUCCESS (0x00) Successfully sets the notify function.
  • NX_NOT_SUPPORTED (0x4B) The extended notify feature is not built into the NetX library
  • NX_PTR_ERROR (0x07) Invalid socket pointer.
  • NX_CALLER_ERROR (0x11) Invalid caller of this service.
  • NX_NOT_ENABLED (0x14) TCP has not been enabled by the application.

Allowed From

Threads

Preemption Possible

No

Example

/* 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);

See Also

  • 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

Retrieve information about TCP socket activities

Prototype

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);

Description

This service retrieves information about TCP socket activities for the specified TCP socket instance.

If a destination pointer is NX_NULL, that particular information is not returned to the caller.

Parameters

  • socket_ptr: Pointer to previously created TCP socket instance.
  • tcp_packets_sent: Pointer to destination for the total number of TCP packets sent on socket.
  • tcp_bytes_sent: Pointer to destination for the total number of TCP bytes sent on socket.
  • tcp_packets_received: Pointer to destination of the total number of TCP packets received on socket.
  • tcp_bytes_received: Pointer to destination of the total number of TCP bytes received on socket.
  • tcp_retransmit_packets: Pointer to destination of the total number of TCP packet retransmissions.
  • tcp_packets_queued: Pointer to destination of the total number of queued TCP packets on socket.
  • tcp_checksum_errors: Pointer to destination of the total number of TCP packets with checksum errors on socket.
  • tcp_socket_state: Pointer to destination of the socket’s current state.
  • tcp_transmit_queue_depth: Pointer to destination of the total number of transmit packets still queued waiting for ACK.
  • tcp_transmit_window: Pointer to destination of the current transmit window size.
  • tcp_receive_window: Pointer to destination of the current receive window size.

Return Values

  • NX_SUCCESS (0x00) Successful TCP socket information retrieval.
  • NX_PTR_ERROR (0x07) Invalid socket pointer.
  • NX_CALLER_ERROR (0x11) Invalid caller of this service.
  • NX_NOT_ENABLED (0x14) This component has not been enabled.

Return Values

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

Allowed From

Initialization, threads

Preemption Possible

No

Example

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

See Also

  • 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

Get MSS of socket

Prototype

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

Description

This service retrieves the specified socket's local Maximum Segment Size (MSS).

Parameters

  • socket_ptr: Pointer to previously created socket.
  • mss: Destination for returning MSS.

Return Values

  • NX_SUCCESS (0x00) Successful MSS get.
  • NX_PTR_ERROR (0x07) Invalid socket or MSS destination pointer.
  • NX_NOT_ENABLED (0x14) TCP is not enabled.
  • NX_CALLER_ERROR (0x11) Caller is not a thread or initialization.

Allowed From

Initialization and threads

Preemption Possible

No

Example

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

See Also

  • 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

Get MSS of the peer TCP socket

Prototype

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

Description

This service retrieves the Maximum Segment Size (MSS) advertised by the peer socket.

Parameters

  • socket_ptr: Pointer to previously created and connected socket.
  • mss: Destination for returning the MSS.

Return Values

  • NX_SUCCESS (0x00) Successful peer MSS get.
  • NX_PTR_ERROR (0x07) Invalid socket or MSS destination pointer.
  • NX_NOT_ENABLED (0x14) TCP is not enabled.
  • NX_CALLER_ERROR (0x11) Caller is not a thread or initialization.

Allowed From

Threads

Preemption Possible

No

Example

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

See Also

  • 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

Set MSS of socket

Prototype

UINT nx_tcp_socket_mss_set(
    NX_TCP_SOCKET *socket_ptr, 
    ULONG mss);

Description

This service sets the specified socket's Maximum Segment Size (MSS). Note the MSS value must be within the network interface IP MTU, allowing room for IP and TCP headers.

This service should be used before a TCP socket starts the connection process. If the service is used after a TCP connection is established, the new value has no effect on the connection.

Parameters

  • socket_ptr: Pointer to previously created socket.
  • mss: Value of MSS to set.

Return Values

  • NX_SUCCESS (0x00) Successful MSS set.
  • NX_SIZE_ERROR (0x09) Specified MSS value is too large.
  • NX_NOT_CONNECTED (0x38) TCP connection has not been established
  • NX_PTR_ERROR (0x07) Invalid socket pointer.
  • NX_NOT_ENABLED (0x14) TCP is not enabled.
  • NX_CALLER_ERROR (0x11) Caller is not a thread or initialization.

Allowed From

Initialization and threads

Preemption Possible

No

Example

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

See Also

  • 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

Retrieve information about peer TCP socket

Prototype

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

Description

This service retrieves peer IP address and port information for the connected TCP socket over IP network.

Parameters

  • socket_ptr: Pointer to previously created TCP socket.
  • peer_ip_address: Pointer to destination for peer IP address, in host byte order.
  • peer_port: Pointer to destination for peer port number, in host byte order.

Return Values

  • NX_SUCCESS (0x00) Service executes successfully. Peer IP address and port number are returned to the caller.
  • NX_NOT_CONNECTED (0x38) Socket is not in a connected state.
  • NX_PTR_ERROR (0x07) Invalid pointers.
  • NX_NOT_ENABLED (0x14) TCP is not enabled.
  • NX_CALLER_ERROR (0x11) Invalid caller of this service.

Allowed From

Threads

Preemption Possible

No

Example

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

See Also

  • 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

Receive data from TCP socket

Prototype

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

Description

This service receives TCP data from the specified socket. If no data are queued on the specified socket, the caller suspends based on the supplied wait option.

If NX_SUCCESS is returned, the application is responsible for releasing the received packet when it is no longer needed.

Parameters

  • socket_ptr: Pointer to previously created TCP socket instance.
  • packet_ptr: Pointer to TCP packet pointer.
  • wait_option: Defines how the service behaves if no data are currently queued on this socket. The wait options are defined as follows:
    • NX_NO_WAIT (0x00000000)
    • NX_WAIT_FOREVER (0xFFFFFFFF)
    • timeout value in ticks (0x00000001 through 0xFFFFFFFE)

Return Values

  • NX_SUCCESS (0x00) Successful socket data receive.
  • NX_NOT_BOUND (0x24) Socket is not bound yet.
  • NX_NO_PACKET (0x01) No data received.
  • NX_WAIT_ABORTED (0x1A) Requested suspension was aborted by a call to tx_thread_wait_abort.
  • NX_NOT_CONNECTED (0x38) The socket is no longer connected.
  • NX_PTR_ERROR (0x07) Invalid socket or return packet pointer.
  • NX_CALLER_ERROR (0x11) Invalid caller of this service.
  • NX_NOT_ENABLED (0x14) This component has not been enabled.

Allowed From

Threads

Preemption Possible

No

Example

/* Receive a packet from the previously created and connected TCP client socket. If no packet is available, wait for 200 timer ticks before giving up. */ status = nx_tcp_socket_receive(&client_socket, &packet_ptr, 200);

/* If status is NX_SUCCESS, the received packet is pointed to by "packet_ptr". */

See Also

  • 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

Notify application of received packets

Prototype

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

Description

This service configures the receive notify function pointer with the callback function specified by the application. This callback function is then called whenever one or more packets are received on the socket. If a NX_NULL pointer is supplied, the notify function is disabled.

Parameters

  • socket_ptr: Pointer to the TCP socket.
  • tcp_receive_notify: Application callback function pointer that is called when one or more packets are received on the socket.

Return Values

  • NX_SUCCESS (0x00) Successful socket receive notify.
  • NX_PTR_ERROR (0x07) Invalid socket pointer.
  • NX_CALLER_ERROR (0x11) Invalid caller of this service.
  • NX_NOT_ENABLED (0x14) TCP feature is not enabled.

Allowed From

Initialization, threads

Preemption Possible

No

Example

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

See Also

  • 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

Send data through a TCP socket

Prototype

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

Description

This service sends TCP data through a previously connected TCP socket. If the receiver's last advertised window size is less than this request, the service optionally suspends based on the wait option specified. This service guarantees that no packet data larger than MSS is sent to the IP layer.

Unless an error is returned, the application should not release the packet after this call. Doing so will cause unpredictable results because the network driver will also try to release the packet after transmission.

Parameters

  • socket_ptr: Pointer to previously connected TCP socket instance.
  • packet_ptr: TCP data packet pointer.
  • wait_option: Defines how the service behaves if the request is greater than the window size of the receiver. The wait options are defined as follows:
    • NX_NO_WAIT (0x00000000)
    • NX_WAIT_FOREVER (0xFFFFFFFF)
    • timeout value in ticks (0x00000001 through 0xFFFFFFFE)

Return Values

  • NX_SUCCESS (0x00) Successful socket send.
  • NX_NOT_BOUND (0x24) Socket was not bound to any port.
  • NX_NO_INTERFACE_ADDRESS (0x50) No suitable outgoing interface found.
  • NX_NOT_CONNECTED (0x38) Socket is no longer connected.
  • NX_WINDOW_OVERFLOW (0x39) Request is greater than receiver’s advertised window size in bytes.
  • NX_WAIT_ABORTED (0x1A) Requested suspension was aborted by a call to tx_thread_wait_abort.
  • NX_INVALID_PACKET (0x12) Packet is not allocated.
  • NX_TX_QUEUE_DEPTH (0x49) Maximum transmit queue depth has been reached.
  • NX_OVERFLOW (0x03) Packet append pointer is invalid.
  • NX_PTR_ERROR (0x07) Invalid socket pointer.
  • NX_CALLER_ERROR (0x11) Invalid caller of this service.
  • NX_NOT_ENABLED (0x14) This component has not been enabled.
  • NX_UNDERFLOW (0x02) Packet prepend pointer is invalid.

Allowed From

Threads

Preemption Possible

No

Example

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

See Also

  • 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

Wait for TCP socket to enter specific state

Prototype

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

Description

This service waits for the socket to enter the desired state. If the socket is not in the desired state, the service suspends according to the supplied wait option.

Parameters

  • socket_ptr: Pointer to previously connected TCP socket instance.
  • desired_state: Desired TCP state. Valid TCP socket states are defined as follows:
    • 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: Defines how the service behaves if the requested state is not present. The wait options are defined as follows:
    • NX_NO_WAIT (0x00000000)
    • NX_WAIT_FOREVER (0xFFFFFFFF)
    • timeout value in ticks (0x00000001 through 0xFFFFFFFE)

Return Values

  • NX_SUCCESS (0x00) Successful state wait.
  • NX_PTR_ERROR (0x07) Invalid socket pointer.
  • NX_NOT_SUCCESSFUL (0x43) State not present within the specified wait time.
  • NX_WAIT_ABORTED (0x1A) Requested suspension was aborted by a call to tx_thread_wait_abort.
  • NX_CALLER_ERROR (0x11) Invalid caller of this service.
  • NX_NOT_ENABLED (0x14) This component has not been enabled.
  • NX_OPTION_ERROR (0x0A) The desired socket state is invalid.

Allowed From

Threads

Preemption Possible

No

Example

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

See Also

  • 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

Install callback for timed wait state

Prototype

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

Description

This service registers a callback function which is invoked when the TCP socket is in timed wait state. To use this service, the NetX library must be built with the option NX_ENABLE_EXTENDED_NOTIFY defined.

Parameters

  • socket_ptr: Pointer to previously connected client or server socket instance.
  • tcp_timed_wait_callback: The timed wait callback function

Return Values

  • NX_SUCCESS (0x00) Successfully registers the callback function socket
  • NX_NOT_SUPPORTED (0x4B) NetX library is built without the extended notify feature enabled.
  • NX_PTR_ERROR (0x07) Invalid socket pointer.
  • NX_CALLER_ERROR (0x11) Invalid caller of this service.
  • NX_NOT_ENABLED (0x14) TCP feature is not enabled.

Allowed From

Initialization, threads

Preemption Possible

No

Example

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

See Also

  • 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

Configure socket's transmit parameters

Prototype

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

Description

This service configures various transmit parameters of the specified TCP socket.

Parameters

  • socket_ptr: Pointer to the TCP socket.
  • max_queue_depth: Maximum number of packets allowed to be queued for transmission.
  • timeout: Number of ThreadX timer ticks an ACK is waited for before the packet is sent again.
  • max_retries: Maximum number of retries allowed.
  • timeout_shift: Value to shift the timeout for each subsequent retry. A value of 0, results in the same timeout between successive retries. A value of 1, doubles the timeout between retries.

Return Values

  • NX_SUCCESS (0x00) Successful transmit socket configure.
  • NX_PTR_ERROR (0x07) Invalid socket pointer.
  • NX_OPTION_ERROR (0x0a) Invalid queue depth option.
  • NX_CALLER_ERROR (0x11) Invalid caller of this service.
  • NX_NOT_ENABLED (0x14) TCP feature is not enabled.

Allowed From

Initialization, threads

Preemption Possible

No

Example

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

See Also

  • 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

Notify application of window size updates

Prototype

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

Description

This service installs a socket window update callback routine. This routine is called automatically whenever the specified socket receives a packet indicating an increase in the window size of the remote host.

Parameters

  • socket_ptr: Pointer to previously created TCP socket.
  • tcp_window_update_notify: Callback routine to be called when the window size changes. A value of NULL disables the window change update.

Return Values

  • NX_SUCCESS (0x00) Callback routine is installed on the socket.
  • NX_CALLER_ERROR (0x11) Invalid caller of this service.
  • NX_PTR_ERROR (0x07) Invalid pointers.
  • NX_NOT_ENABLED (0x14) TCP feature is not enabled.

Allowed From

Initialization, threads

Preemption Possible

No

Example

/* 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;
}

See Also

  • 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

Enable UDP component of NetX

Prototype

UINT nx_udp_enable(NX_IP *ip_ptr);

Description

This service enables the User Datagram Protocol (UDP) component of NetX. After enabled, UDP datagrams may be sent and received by the application.

Parameters

  • ip_ptr: Pointer to previously created IP instance.

Return Values

  • NX_SUCCESS (0x00) Successful UDP enable.
  • NX_PTR_ERROR (0x07) Invalid IP pointer.
  • NX_CALLER_ERROR (0x11) Invalid caller of this service.
  • NX_ALREADY_ENABLED (0x15) This component has already been enabled.

Allowed From

Initialization, threads, timers

Preemption Possible

No

Example

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

See Also

  • 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

Find next available UDP port

Prototype

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

Description

This service looks for a free UDP port (unbound) starting from the application supplied port number. The search logic will wrap around if the search reaches the maximum port value of 0xFFFF. If the search is successful, the free port is returned in the variable pointed to by free_port_ptr.

This service can be called from another thread and can have the same port returned. To prevent this race condition, the application may wish to place this service and the actual socket bind under the protection of a mutex.

Parameters

  • ip_ptr: Pointer to previously created IP instance.
  • port: Port number to start search (1 through 0xFFFF).
  • free_port_ptr: Pointer to the destination free port return variable.

Return Values

  • NX_SUCCESS (0x00) Successful free port find.
  • NX_NO_FREE_PORTS (0x45) No free ports found.
  • NX_PTR_ERROR (0x07) Invalid IP pointer.
  • NX_CALLER_ERROR (0x11) Invalid caller of this service.
  • NX_NOT_ENABLED (0x14) This component has not been enabled.
  • NX_INVALID_PORT (0x46) Specified port number is invalid.

Allowed From

Threads

Preemption Possible

No

Example

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

See Also

  • 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

Retrieve information about UDP activities

Prototype

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);

Description

This service retrieves information about UDP activities for the specified IP instance.

If a destination pointer is NX_NULL, that particular information is not returned to the caller.

Parameters

  • ip_ptr: Pointer to previously created IP instance.
  • udp_packets_sent: Pointer to destination for the total number of UDP packets sent.
  • udp_bytes_sent: Pointer to destination for the total number of UDP bytes sent.
  • udp_packets_received: Pointer to destination of the total number of UDP packets received.
  • udp_bytes_received: Pointer to destination of the total number of UDP bytes received.
  • udp_invalid_packets: Pointer to destination of the total number of invalid UDP packets.
  • udp_receive_packets_dropped: Pointer to destination of the total number of UDP receive packets dropped.
  • udp_checksum_errors: Pointer to destination of the total number of UDP packets with checksum errors.

Return Values

  • NX_SUCCESS (0x00) Successful UDP information retrieval.
  • NX_PTR_ERROR (0x07) Invalid IP pointer.
  • NX_CALLER_ERROR (0x11) Invalid caller of this service.
  • NX_NOT_ENABLED (0x14) This component has not been enabled.

Allowed From

Initialization, threads, and timers

Preemption Possible

No

Example

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

See Also

  • 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

Extract network parameters from UDP packet

Prototype

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

Description

This service extracts network parameters, such as IP address, peer port number, protocol type (this service always returns UDP type) from a packet received on an incoming interface.

Parameters

  • packet_ptr: Pointer to packet.
  • ip_address: Pointer to sender IP address.
  • protocol: Pointer to protocol (UDP).
  • port: Pointer to sender’s port number.
  • interface_index: Pointer to receiving interface index.

Return Values

  • NX_SUCCESS (0x00) Packet interface data successfully extracted.
  • NX_INVALID_PACKET (0x12) Packet does not contain IP frame.
  • NX_PTR_ERROR (0x07) Invalid pointer input
  • NX_CALLER_ERROR (0x11) Invalid caller of this service.

Allowed From

Threads

Preemption Possible

No

Example

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

See Also

  • 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

Bind UDP socket to UDP port

Prototype

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

Description

This service binds the previously created UDP socket to the specified UDP port. Valid UDP sockets range from 0 through 0xFFFF. If the requested port number is bound to another socket, this service waits for specified period of time for the socket to unbind from the port number.

Parameters

  • socket_ptr: Pointer to previously created UDP socket instance.
  • port: Port number to bind to (1 through 0xFFFF). If port number is NX_ANY_PORT (0x0000), the IP instance will search for the next free port and use that for the binding.
  • wait_option: Defines how the service behaves if the port is already bound to another socket. The wait options are defined as follows:
    • NX_NO_WAIT (0x00000000)
    • NX_WAIT_FOREVER (0xFFFFFFFF)
    • timeout value in ticks (0x00000001 through 0xFFFFFFFE)

Return Values

  • NX_SUCCESS (0x00) Successful socket bind.
  • NX_ALREADY_BOUND (0x22) This socket is already bound to another port.
  • NX_PORT_UNAVAILABLE (0x23) Port is already bound to a different socket.
  • NX_NO_FREE_PORTS (0x45) No free port.
  • NX_WAIT_ABORTED (0x1A) Requested suspension was aborted by a call to tx_thread_wait_abort.
  • NX_INVALID_PORT (0x46) Invalid port specified.
  • NX_PTR_ERROR (0x07) Invalid socket pointer.
  • NX_CALLER_ERROR (0x11) Invalid caller of this service.
  • NX_NOT_ENABLED (0x14) This component has not been enabled.

Allowed From

Threads

Preemption Possible

No

Example

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

See Also

  • 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

Retrieves number of bytes available for retrieval

Prototype

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

Description

This service retrieves number of bytes available for reception in the specified UDP socket.

Parameters

  • socket_ptr: Pointer to previously created UDP socket.
  • bytes_available: Pointer to destination for bytes available.

Return Values

  • NX_SUCCESS (0x00) Successful bytes available retrieval.
  • NX_NOT_SUCCESSFUL (0x43) Socket not bound to a port.
  • NX_PTR_ERROR (0x07) Invalid pointers.
  • NX_NOT_ENABLED (0x14) UDP feature is not enabled.
  • NX_CALLER_ERROR (0x11) Invalid caller of this service.

Allowed From

Threads

Preemption Possible

No

Example

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

See Also

  • 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

Disable checksum for UDP socket

Prototype

UINT nx_udp_socket_checksum_disable(NX_UDP_SOCKET *socket_ptr);

Description

This service disables the checksum logic for sending and receiving packets on the specified UDP socket. When the checksum logic is disabled, a value of zero is loaded into the UDP header's checksum field for all packets sent through this socket. A zero-value checksum value in the UDP header signals the receiver that checksum is not computed for this packet.

Also note that this has no effect if NX_DISABLE_UDP_RX_CHECKSUM and NX_DISABLE_UDP_TX_CHECKSUM are defined when receiving and sending UDP packets respectively.

Parameters

  • socket_ptr: Pointer to previously created UDP socket instance.

Return Values

  • NX_SUCCESS (0x00) Successful socket checksum disable.
  • NX_NOT_BOUND (0x24) Socket is not bound.
  • NX_PTR_ERROR (0x07) Invalid socket pointer.
  • NX_CALLER_ERROR (0x11) Invalid caller of this service.
  • NX_NOT_ENABLED (0x14) This component has not been enabled.

Allowed From

Initialization, threads, timer

Preemption Possible

No

Example

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

See Also

  • 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

Enable checksum for UDP socket

Prototype

UINT nx_udp_socket_checksum_enable(NX_UDP_SOCKET *socket_ptr);

Description

This service enables the checksum logic for sending and receiving packets on the specified UDP socket. The checksum covers the entire UDP data area as well as a pseudo IP header.

Also note that this has no effect if NX_DISABLE_UDP_RX_CHECKSUM and NX_DISABLE_UDP_TX_CHECKSUM are defined when receiving and sending UDP packets respectively.

Parameters

  • socket_ptr: Pointer to previously created UDP socket instance.

Return Values

  • NX_SUCCESS (0x00) Successful socket checksum enable.
  • NX_NOT_BOUND (0x24) Socket is not bound.
  • NX_PTR_ERROR (0x07) Invalid socket pointer.
  • NX_CALLER_ERROR (0x11) Invalid caller of this service.
  • NX_NOT_ENABLED (0x14) This component has not been enabled.

Allowed From

Initialization, threads, timer

Preemption Possible

No

Example

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

See Also

  • 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

Create UDP socket.

Prototype

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);

Description

This service creates a UDP socket for the specified IP instance.

Parameters

  • ip_ptr: Pointer to previously created IP instance.
  • socket_ptr: Pointer to new UDP socket control bloc.
  • name: Application name for this UDP socket.
  • type_of_service: Defines the type of service for the transmission, legal values are as follows:
    • 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: Specifies whether or not IP fragmenting is allowed. If NX_FRAGMENT_OKAY (0x0) is specified, IP fragmenting is allowed. If NX_DONT_FRAGMENT (0x4000) is specified, IP fragmenting is disabled.
  • time_to_live: Specifies the 8-bit value that defines how many routers this packet can pass before being thrown away. The default value is specified by NX_IP_TIME_TO_LIVE.
  • queue_maximum: Defines the maximum number of UDP datagrams that can be queued for this socket. After the queue limit is reached, for every new packet received the oldest UDP packet is released.

Return Values

  • NX_SUCCESS (0x00) Successful UDP socket create.
  • NX_OPTION_ERROR (0x0A) Invalid type-of-service, fragment, or time-to-live option.
  • NX_PTR_ERROR (0x07) Invalid IP or socket pointer.
  • NX_CALLER_ERROR (0x11) Invalid caller of this service.
  • NX_NOT_ENABLED (0x14) This component has not been enabled.

Allowed From

Initialization and Threads

Preemption Possible

No

Example

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

See Also

  • 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

Delete UDP socket

Prototype

UINT nx_udp_socket_delete(NX_UDP_SOCKET *socket_ptr);

Description

This service deletes a previously created UDP socket. If the socket was bound to a port, the socket must be unbound first.

Parameters

  • socket_ptr: Pointer to previously created UDP socket instance.

Return Values

  • NX_SUCCESS (0x00) Successful socket delete.
  • NX_STILL_BOUND (0x42) Socket is still bound.
  • NX_PTR_ERROR (0x07) Invalid socket pointer.
  • NX_CALLER_ERROR (0x11) Invalid caller of this service.
  • NX_NOT_ENABLED (0x14) This component has not been enabled.

Allowed From

Threads

Preemption Possible

No

Example

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

See Also

  • 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

Retrieve information about UDP socket activities

Prototype

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);

Description

This service retrieves information about UDP socket activities for the specified UDP socket instance.

If a destination pointer is NX_NULL, that particular information is not returned to the caller.

Parameters

  • socket_ptr: Pointer to previously-created UDP socket instance.
  • udp_packets_sent: Pointer to destination for the total number of UDP packets sent on socket.
  • udp_bytes_sent: Pointer to destination for the total number of UDP bytes sent on socket.
  • udp_packets_received: Pointer to destination of the total number of UDP packets received on socket.
  • udp_bytes_received: Pointer to destination of the total number of UDP bytes received on socket.
  • udp_packets_queued: Pointer to destination of the total number of queued UDP packets on socket.
  • udp_receive_packets_dropped: Pointer to destination of the total number of UDP receive packets dropped for socket due to queue size being exceeded.
  • udp_checksum_errors: Pointer to destination of the total number of UDP packets with checksum errors on socket.

Return Values

  • NX_SUCCESS (0x00) Successful UDP socket information retrieval.
  • NX_PTR_ERROR (0x07) Invalid socket pointer.
  • NX_CALLER_ERROR (0x11) Invalid caller of this service.
  • NX_NOT_ENABLED (0x14) This component has not been enabled.

Allowed From

Initialization, threads, and timers

Preemption Possible

No

Example

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

See Also

  • 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

Pick up port number bound to UDP socket

Prototype

UINT nx_udp_socket_port_get(NX_UDP_SOCKET *socket_ptr, UINT *port_ptr);

Description

This service retrieves the port number associated with the socket, which is useful to find the port allocated by NetX in situations where the NX_ANY_PORT was specified at the time the socket was bound.

Parameters

  • socket_ptr: Pointer to previously created UDP socket instance.
  • port_ptr: Pointer to destination for the return port number. Valid port numbers are (1- 0xFFFF).

Return Values

  • NX_SUCCESS (0x00) Successful socket bind.
  • NX_NOT_BOUND (0x24) This socket is not bound to a port.
  • NX_PTR_ERROR (0x07) Invalid socket pointer or port return pointer.
  • NX_CALLER_ERROR (0x11) Invalid caller of this service.
  • NX_NOT_ENABLED (0x14) This component has not been enabled.

Allowed From

Threads

Preemption Possible

No

Example

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

See Also

  • 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

Receive datagram from UDP socket

Prototype

UINT nx_udp_socket_receive(
    NX_UDP_SOCKET *socket_ptr,
    NX_PACKET **packet_ptr, 
    ULONG wait_option);

Description

This service receives an UDP datagram from the specified socket. If no datagram is queued on the specified socket, the caller suspends based on the supplied wait option.

If NX_SUCCESS is returned, the application is responsible for releasing the received packet when it is no longer needed.

Parameters

  • socket_ptr: Pointer to previously created UDP socket instance.
  • packet_ptr: Pointer to UDP datagram packet pointer.
  • wait_option: Defines how the service behaves if a datagram is not currently queued on this socket. The wait options are defined as follows:
    • NX_NO_WAIT (0x00000000)
    • NX_WAIT_FOREVER (0xFFFFFFFF)
    • timeout value in ticks (0x00000001 through 0xFFFFFFFE)

Allowed From

Threads

Preemption Possible

No

Example

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

See Also

  • 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

Notify application of each received packet

Prototype

UINT nx_udp_socket_receive_notify(
    NX_UDP_SOCKET *socket_ptr,
    VOID (*udp_receive_notify)
    (NX_UDP_SOCKET *socket_ptr));

Description

This service sets the receive notify function pointer to the callback function specified by the application. This callback function is then called whenever a packet is received on the socket. If a NX_NULL pointer is supplied, the receive notify function is disabled.

Parameters

  • socket_ptr: Pointer to the UDP socket.
  • udp_receive_notify: Application callback function pointer that is called when a packet is received on the socket.

Allowed From

Initialization, threads, timers, and ISRs

Preemption Possible

No

Example

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

See Also

  • 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

Send a UDP Datagram

Prototype

UINT nx_udp_socket_send(
    NX_UDP_SOCKET *socket_ptr,
    NX_PACKET *packet_ptr,
    ULONG ip_address,
    UINT port);

Description

This service sends a UDP datagram through a previously created and bound UDP socket. NetX finds a suitable local IP address as source address based on the destination IP address. To specify a specific interface and source IP address, the application should use the nx_udp_socket_interface_send service.

Note that this service returns immediately regardless of whether the UDP datagram was successfully sent.

The socket must be bound to a local port.

Parameters

  • socket_ptr: Pointer to previously created UDP socket instance
  • packet_ptr: UDP datagram packet pointer
  • ip_address: Destination IP address
  • port: Valid destination port number between 1 and 0xFFFF), in host byte order

Return Values

  • NX_SUCCESS (0x00) Successful UDP socket send
  • NX_NOT_BOUND (0x24) Socket not bound to any port
  • NX_NO_INTERFACE_ADDRESS (0x50) No suitable outgoing interface can be found.
  • NX_IP_ADDRESS_ERROR (0x21) Invalid server IP address
  • NX_UNDERFLOW (0x02) Not enough room for UDP header in the packet
  • NX_OVERFLOW (0x03) Packet append pointer is invalid
  • NX_PTR_ERROR (0x07) Invalid socket pointer
  • NX_CALLER_ERROR (0x11) Invalid caller of this service
  • NX_NOT_ENABLED (0x14) UDP has not been enabled
  • NX_INVALID_PORT (0x46) Port number is not within a valid range

Allowed From

Threads

Preemption Possible

No

Example

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

See Also

  • 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

Send datagram through UDP socket.

Prototype

UINT nx_udp_socket_interface_send(
    NX_UDP_SOCKET *socket_ptr,
    NX_PACKET *packet_ptr,
    ULONG ip_address,
    UINT port,
    UINT address_index);

Description

This service sends a UDP datagram through a previously created and bound UDP socket through the network interface with the specified IP address as the source address. Note that service returns immediately, regardless of whether or not the UDP datagram was successfully sent.

Parameters

  • socket_ptr: Socket to transmit the packet out on.
  • packet_ptr: Pointer to packet to transmit.
  • ip_address: Destination IP address to send packet.
  • port: Destination port.
  • address_index: Index of the address associated with the interface to send packet on.

Return Values

  • NX_SUCCESS (0x00) Packet successfully sent.
  • NX_NOT_BOUND (0x24) Socket not bound to a port.
  • NX_IP_ADDRESS_ERROR (0x21) Invalid IP address.
  • NX_NOT_ENABLED (0x14) UDP processing not enabled.
  • NX_PTR_ERROR (0x07) Invalid pointer.
  • NX_OVERFLOW (0x03) Invalid packet append pointer.
  • NX_UNDERFLOW (0x02) Invalid packet prepend pointer.
  • NX_CALLER_ERROR (0x11) Invalid caller of this service.
  • NX_INVALID_INTERFACE (0x4C) Invalid address index.
  • NX_INVALID_PORT (0x46) Port number exceeds maximum port number.

Allowed From

Threads

Preemption Possible

No

Example

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

See Also

  • 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

Unbind UDP socket from UDP port.

Prototype

UINT nx_udp_socket_unbind(NX_UDP_SOCKET *socket_ptr);

Description

This service releases the binding between the UDP socket and a UDP port. Any received packets stored in the receive queue are released as part of the unbind operation.

If there are other threads waiting to bind another socket to the unbound port, the first suspended thread is then bound to the newly unbound port.

Parameters

  • socket_ptr: Pointer to previously created UDP socket instance.

Return Values

  • NX_SUCCESS (0x00) Successful socket unbind.
  • NX_NOT_BOUND (0x24) Socket was not bound to any port.
  • NX_PTR_ERROR (0x07) Invalid socket pointer.
  • NX_CALLER_ERROR (0x11) Invalid caller of this service.
  • NX_NOT_ENABLED (0x14) This component has not been enabled.

Allowed From

Threads

Preemption Possible

Yes

Example

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

See Also

  • 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

Extract IP and sending port from UDP datagram

Prototype

UINT nx_udp_source_extract(
    NX_PACKET *packet_ptr,
    ULONG *ip_address, UINT *port);

Description

This service extracts the sender's IP and port number from the IP and UDP headers of the supplied UDP datagram.

Parameters

  • packet_ptr: UDP datagram packet pointer.
  • ip_address: Valid pointer to the return IP address variable.
  • port: Valid pointer to the return port variable.

Return Values

  • NX_SUCCESS (0x00) Successful source IP/port extraction.
  • NX_INVALID_PACKET (0x12) The supplied packet is invalid.
  • NX_PTR_ERROR (0x07) Invalid packet or IP or port destination.

Allowed From

Initialization, threads, timers, ISR

Preemption Possible

No

Example

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

See Also

  • 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