Chapter 3 - Description of Azure RTOS NetX DHCP Client services

This chapter contains a description of all Azure RTOS NetX DHCP services (listed below) in alphabetic order.

In the “Return Values” section in the following API descriptions, values in BOLD are not affected by the NX_DISABLE_ERROR_CHECKING define that is used to disable API error checking, while non-bold values are completely disabled.

  • nx_dhcp_create: Create a DHCP instance

  • nx_dhcp_clear_broadcast_flag: Clear broadcast flag on Client messages

  • nx_dhcp_delete: Delete a DHCP instance

  • nx_dhcp_decline: Send Decline message to server

  • nx_dhcp_force_renew: Send force renew message

  • nx_dhcp_packet_pool_set: Set the DHCP Client packet pool

  • nx_dhcp_release: Send Release message to server

  • nx_dhcp_reinitialize: Clear DHCP client network parameters

  • nx_dhcp_request_client_ip: Specify a specific IP address

  • nx_dhcp_send_request: Send DHCP message to server

  • nx_dhcp_server_address_get: Retrieve DHCP Client’s DHCP server address

  • nx_dhcp_set_interface_index: Specify the Client network interface

  • nx_dhcp_start: Start DHCP processing

  • nx_dhcp_state_change_notify: Notify application of DHCP state change

  • nx_dhcp_stop: Stop DHCP processing

  • nx_dhcp_user_option_retrieve: Retrieve DHCP option

  • nx_dhcp_user_option_convert: Convert four bytes to ULONG

Interface specific DHCP Client services:

  • nx_dhcp_interface_clear_broadcast_flag: Clear broadcast flag on Client messages on specified interface

  • nx_dhcp_interface_enable: Enable interface to run DHCP on the specified interface

  • nx_dhcp_interface_disable: Disable interface to run DHCP on the specified interface

  • nx_dhcp_interface_decline: Send Decline message to server on the specified interface

  • nx_dhcp_interface_force_renew: Send a force renew message on the specified interface

  • nx_dhcp_interface_reinitialize: Clear DHCP client network parameters on the specified interface

  • nx_dhcp_interface_release: Send Release message to server on the specified interface

  • nx_dhcp_interface_request_client_ip: Specify a specific IP address on the specified interface

  • nx_dhcp_interface_send_request: Send DHCP message to server on the specified interface

  • nx_dhcp_interface_server_address_get: Get the DHCP server IP address on the specified interface

  • nx_dhcp_interface_start: Start the DHCP Client processing on the specified interface

  • nx_dhcp_interface_stop: Stop the DHCP Client processing on the specified interface

  • nx_dhcp_interface_state_change_notify: Set the callback function when DHCP state changes on the specified interface

  • nx_dhcp_interface_user_option_retrieve: Retrieve the specified DHCP option on the specified interface

DHCP Client Services if NX_DHCP_CLIENT_RESORE_STATE is defined:

  • nx_dhcp_resume: Resume previously established DHCP Client state

  • nx_dhcp_suspend: Suspend processing the DHCP Client state

  • nx_dhcp_client_get_record: Create a record of the DHCP Client state

  • nx_dhcp_client_restore_record: Restore a previously saved record to the DHCP Client

  • nx_dhcp_client_update_time_remaining: Update the time remaining in the current DHCP state

Interface Specific DHCP Client Services if NX_DHCP_CLIENT_RESORE_STATE is defined:

  • nx_dhcp_client_interface_get_record: Create a record of the DHCP Client state on the specified interface

  • nx_dhcp_client_interface_restore_record: Restore a previously saved record to the DHCP Client on the specified interface

  • nx_dhcp_client_interface_update_time_remaining: Update the time remaining in the current DHCP state on the specified interface

nx_dhcp_create

Create a DHCP instance

Prototype

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

Description

This service creates a DHCP instance for the previously created IP instance. By default the primary interface is enabled for running DHCP. The name input, while not used in the NetX implementation of DHCP Client, must follow RFC 1035 criteria for host names. The total length must not exceed 255 characters, the labels separate by dots must begin with a letter, and end with a letter or number, and may contain hyphens but no other non-alphanumeric character.

If the application would like to run DHCP another interface registered with the IP instance, (using nx_ip_interface_attach), the application can call nx_dhcp_set_interface_index to run DHCP on just that interface, or nx_dhcp_interface_enable to run DHCP on that interface as well. See description of these services for more details.

Note

The application must make sure the DHCP Client packet pool payload can support the minimum DHCP message size specified by the RFC 2131 Section 2 (548 bytes of DHCP message data plus UDP, IP and physical network frame headers).

Input Parameters

  • dhcp_ptr: Pointer to DHCP control block.
  • ip_ptr: Pointer to previously created IP instance.
  • name_ptr: Pointer to host name for DHCP instance.

Return Values

  • NX_SUCCESS (0x00) Successful DHCP create

  • NX_DHCP_INVALID_NAME (0xA8) Invalid host name

  • NX_DHCP_INVALID_PAYLOAD (0x9C) Payload too small for DHCP message

  • NX_PTR_ERROR (0x16) Invalid IP or DHCP pointer

Allowed From

Threads, Initialization

Example

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

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

nx_dhcp_interface_enable

Enable the specified interface to run DHCP

Prototype

UINT nx_dhcp_interface_enable
    (NX_DHCP *dhcp_ptr,
    UINT interface_index);

Description

This service enables the specified interface for running DHCP. By default the primary interface is enabled for DHCP Client. At this point, DHCP can be started on this interface either by calling nx_dhcp_interface_start or to start DHCP on all enabled interfaces nx_dhcp_start.

Note the application must first register this interface with the IP instance, using nx_ip_interface_attach.

Further, there must be an available DHCP Client interface ‘record’ to add this interface to the list of enabled interfaces. By default NX_DHCP_CLIENT_MAX_RECORDS is defined to 1. Set this option to the maximum number of interfaces expected to run DHCP Client simultaneously. Typically NX_DHCP_CLIENT_MAX_RECORDS will equal NX_MAX_PHYSICAL_INTERFACES; however, if a device has more physical interfaces than it expects to run DHCP Client, it can save memory by setting NX_DHCP_CLIENT_MAX_RECORDS to less than that number. There is not a one to one mapping of physical interfaces with DHCP Client interface records.

The difference between this service and nx_dhcp_set_interface_index is the latter sets only a single interface to run DHCP whereas this service simply adds the specified interface to the list of Client interfaces enabled for DHCP.

To disable an interface for DHCP, the application can call the nx_dhcp_interface_disable service.

Input Parameters

  • dhcp_ptr: Pointer to DHCP control block.

  • interface_index: Index of interface to enable DHCP on

Return Values

  • NX_SUCCESS (0x00) Successful DHCP enable

  • NX_DHCP_NO_RECORDS_AVAILABLE (0xA7) No record available for another Interface to be enabled for DHCP

  • NX_DHCP_INTERFACE_ALREADY_ENABLED (0xA3) Interface enabled for DHCP

  • NX_PTR_ERROR (0x16) Invalid IP or DHCP pointer

  • NX_INVALID_INTERFACE (0x4C) Invalid network interface

Allowed From

Threads, Initialization

Example

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

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


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

nx_dhcp_interface_disable

Disable the specified interface to run DHCP

Prototype

UINT nx_dhcp_interface_disable(
    NX_DHCP *dhcp_ptr,
    UINT interface_index);

Description

This service disables the specified interface for running DHCP. It reinitializes the DHCP Client on this interface.

To restart the DHCP Client the application must re-enable the interface using nx_dhcp_interface_enable and restart DHCP by calling nx_dhcp_interface_start.

Input Parameters

  • dhcp_ptr: Pointer to DHCP control block.

  • interface_index: Index of interface to disable DHCP on

Return Values

  • NX_SUCCESS (0x00) Successful DHCP create

  • NX_DHCP_INTERFACE_NOT_ENABLED (0xA4) Interface not enabled for DHCP

  • NX_PTR_ERROR (0x16) Invalid IP or DHCP pointer

  • NX_CALLER_ERROR (0x11) Invalid caller of this service

  • NX_INVALID_INTERFACE (0x4C) Invalid network interface

Allowed From

Threads

Example

/* Disable DHCP on a secondary interface.
. */

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

nx_dhcp_clear_broadcast_flag

Set the DHCP broadcast flag

Prototype

UINT nx_dhcp_clear_broadcast_flag
    (NX_DHCP *dhcp_ptr,
    UINT clear_flag);

Description

This service sets or clears the broadcast flag the DHCP message header for all interfaces enabled for DHCP. For some DHCP messages (e.g. DISCOVER) the broadcast flag is set to broadcast because the Client does not have an IP address.

This service is intended for DHCP Clients that must go through a router to get to the DHCP Server, where the router rejects forwarding broadcast messages.

Input Parameters

  • dhcp_ptr: Pointer to DHCP control block

  • clear_flag: Clears the broadcast flag if this parameter is set to NX_TRUE. Sets the broadcast flag if this parameter is set to NX_FALSE.

Return Values

  • NX_SUCCESS (0x00) Successfully updated the broadcast flag

  • NX_PTR_ERROR (0x16) Invalid IP or DHCP pointer

  • NX_CALLER_ERROR (0x11) Invalid caller of this service

Allowed From

Threads, Initialization

Example

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

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

nx_dhcp_interface_clear_broadcast_flag

Set or clear the broadcast flag on the specified interface

Prototype

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

Description

This service enables the DHCP Client host application to set or clear the broadcast flag in DHCP Client messages to the DHCP Server on the specified interface. For more details see nx_dhcp_clear_broadcast_flag.

Input Parameters

  • dhcp_ptr: Pointer to DHCP control block

  • interface_index: Index of interface to set the broadcast flag

  • clear_flag: Value to set the broadcast flag to

Return Values

  • NX_SUCCESS (0x00) Successfully updated the broadcast flag

  • NX_DHCP_INTERFACE_NOT_ENABLED (0xA4) Interface not enabled for DHCP

  • NX_PTR_ERROR (0x16) Invalid IP or DHCP pointer

  • NX_INVALID_INTERFACE (0x4C) Invalid network interface

Allowed From

Threads, Initialization

Example

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

iface_index = 1;

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

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

nx_dhcp_delete

Delete a DHCP instance

Prototype

UINT nx_dhcp_delete(NX_DHCP *dhcp_ptr);

Description

This service deletes a previously created DHCP instance.

Input Parameters

  • dhcp_ptr: Pointer to previously created DHCP instance.

Return Values

  • NX_SUCCESS (0x00) Successful DHCP delete.

  • NX_PTR_ERROR (0x16) Invalid DHCP pointer.

  • NX_CALLER_ERROR (0x11) Invalid caller of this service.

Allowed From

Threads

Example

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

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

nx_dhcp_force_renew

Send a force renew message

Prototype

UINT nx_dhcp_force_renew(NX_DHCP *dhcp_ptr);

Description

This service enables the host application to send a force renew message on all interfaces enabled for DHCP. The DHCP Client must be in a BOUND state. This function sets the state to RENEW such that the DHCP Client will try to renew before the T1 timeout expires.

To send a force renew on a specific interface when multiple interfaces are DHCP-enabled, use nx_dhcp_interface_force_renew.

Input Parameters

  • dhcp_ptr: Pointer to previously created DHCP instance.

Return Values

  • NX_SUCCESS (0x00) Successfully sent force renew.

  • NX_PTR_ERROR (0x16) Invalid DHCP pointer.

  • NX_CALLER_ERROR (0x11) Invalid caller of this service.

Allowed From

Threads

Example

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

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

nx_dhcp_interface_force_renew

Send a force renew message on the specified interface

Prototype

UINT nx_dhcp_interface_force_renew(
    NX_DHCP *dhcp_ptr,
    UINT interface_index);

Description

This service enables the host application to send a force renew message on the input interface as long as that interface has been enabled for DHCP (see nx_dhcp_interface_enable). The DHCP Client on the specified interface must be in a BOUND state. This function sets the state to RENEW such that the DHCP Client will try to renew before the T1 timeout expires.

Input Parameters

  • dhcp_ptr: Pointer to previously created DHCP instance.

Return Values

  • NX_SUCCESS (0x00) Successfully sent force renew.

  • NX_DHCP_INTERFACE_NOT_ENABLED (0xA4) Interface not enabled for DHCP

  • NX_PTR_ERROR (0x16) Invalid IP or DHCP pointer

  • NX_INVALID_INTERFACE (0x4C) Invalid network interface

Allowed From

Threads

Example

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

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

nx_dhcp_packet_pool_set

Set the DHCP Client packet pool

Prototype

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

Description

This service allows the application to create the DHCP Client packet pool by passing in a pointer to a previously created packet pool in this service call. To use this feature, the host application must define NX_DHCP_CLIENT_USER_CREATE_PACKET_POOL. When defined, the nx_dhcp_create service will not create the Client’s packet pool. Note that the application is recommended to use the default values for the DHCP client packet pool payload, defined as NX_DHCP_PACKET_PAYLOAD in nx_dhcp.h when creating the packet pool.

Input Parameters

  • dhcp_ptr: Pointer to DHCP control block.

  • packet_pool_ptr: Pointer to previously created packet pool

Return Values

  • NX_SUCCESS (0x00) DHCP Client packet pool is set

  • NX_NOT_ENABLED (0x14) Service is not enabled

  • NX_PTR_ERROR (0x16) Invalid DHCP pointer

  • NX_DHCP_INVALID_PAYLOAD (0x9C) Payload is too small

Allowed From

Application code

Example

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

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

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

nx_dhcp_request_client_ip

Set requested IP address for DHCP instance

Prototype

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

Description

This service sets the IP address for the DHCP Client to request from the DHCP Server on the first interface enabled for DHCP in the DHCP Client record. If the skip_discover_message flag is set, the DHCP Client skips the Discover message and sends a Request message.

To set the request for a specific IP for DHCP messages on a specific interface, use the nx_dhcp_interface_request_client_ip service.

Input Parameters

  • dhcp_ptr: Pointer to DHCP control block.

  • client_ip_address: IP address to request from DHCP server

  • skip_discover_message: If true, DHCP Client sends Request message
    If false, it sends the Discover message.

Return Values

  • NX_SUCCESS (0x00) Requested IP address is set.

  • NX_DHCP_INTERFACE_NOT_ENABLED (0xA4) Interface not enabled for DHCP

  • NX_PTR_ERROR (0x16) Invalid IP or DHCP pointer

  • NX_INVALID_INTERFACE (0x4C) Invalid network interface

Allowed From

Threads

Example

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

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

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

nx_dhcp_interface_request_client_ip

Set requested IP address for DHCP instance on specified interface

Prototype

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

Description

This service sets the IP address for the DHCP Client to request from the DHCP Server on the specified interface, if that interface is enabled for DHCP (see nx_dhcp_interface_enable). If the skip_discover_message flag is set, the DHCP Client skips the Discover message and sends a Request message.

Input Parameters

  • dhcp_ptr: Pointer to DHCP control block.

  • Interface_index: Index of interface to request IP address on

  • client_ip_address: IP address to request from DHCP server

  • skip_discover_message: If true, DHCP Client sends Request message; else it sends the Discover message.

Return Values

  • NX_SUCCESS (0x00) Requested IP address is set.

  • NX_DHCP_INTERFACE_NOT_ENABLED (0xA4) Interface not enabled for DHCP

  • NX_PTR_ERROR (0x16) Invalid IP or DHCP pointer

  • NX_INVALID_INTERFACE (0x4C) Invalid network interface

Allowed From

Threads

Example

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

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

nx_dhcp_reinitialize

Clear the DHCP client network parameters

Prototype

UINT nx_dhcp_reinitialize(NX_DHCP *dhcp_ptr);

Description

This service clears the host application network parameters (IP address, network address and network mask), and clears the DHCP Client state on all interfaces enabled for DHCP. It is used in combination with nx_dhcp_stop and nx_dhcp_start to ‘restart’ the DHCP state machine:

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

To reinitialize the DHCP Client on a specific interface when multiple interfaces are enabled for DHCP, use the nx_dhcp_interface_reinitialize service.

Input Parameters

  • dhcp_ptr: Pointer to previously created DHCP instance.

Return Values

  • NX_SUCCESS (0x00) DHCP successfully reinitialized

  • NX_PTR_ERROR (0x16) Invalid DHCP pointer

Allowed From

Threads

Example

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

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

nx_dhcp_interface_reinitialize

Clear the DHCP client network parameters on the specified interface

Prototype

UINT nx_dhcp_interface_reinitialize(
    NX_DHCP *dhcp_ptr,
    UINT interface_index);

Description

This service clears the network parameters (IP address, network address and network mask) on the specified interface if that interface is enabled for DHCP (see nx_dhcp_interface_enable). See nx_dhcp_reinitialize for more details.

Input Parameters

  • dhcp_ptr: Pointer to previously created DHCP instance

  • interface_index: Index of interface to reinitialize.

Return Values

  • NX_SUCCESS (0x00) Interface successfully reinitialized

  • NX_DHCP_INTERFACE_NOT_ENABLED (0xA4) Interface not enabled for DHCP

  • NX_PTR_ERROR (0x16) Invalid DHCP pointer

  • NX_CALLER_ERROR (0x11) Invalid caller of this service.

  • NX_INVALID_INTERFACE (0x4C) Invalid network interface

Allowed From

Threads

Example

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

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

nx_dhcp_release

Release Leased IP address

Prototype

UINT nx_dhcp_release(NX_DHCP *dhcp_ptr);

Description

This service releases the IP address obtained from a DHCP server by sending the RELEASE message to that server. It then reinitializes the DHCP Client. This service is applied to all interfaces enabled for DHCP.

The application can restart the DHCP Client by calling nx_dhcp_start.

To release an address back to the DHCP server on a specific interface, use the nx_dhcp_interface_release service

Input Parameters

  • dhcp_ptr: Pointer to previously created DHCP instance.

Return Values

  • NX_SUCCESS (0x00) Successful DHCP release.

  • NX_DHCP_NOT_BOUND (0x94) The IP address has not been leased so it can’t be released.

  • NX_PTR_ERROR (0x16) Invalid DHCP pointer.

  • NX_CALLER_ERROR (0x11) Invalid caller of this service.

Allowed From

Threads

Example

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

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

nx_dhcp_interface_release

Release IP address on the specified interface

Prototype

UINT nx_dhcp_interface_release(
    NX_DHCP *dhcp_ptr,
    UINT interface_index);

Description

This service releases the IP address obtained from a DHCP server on the specified interface and reinitializes the DHCP Client. The DHCP Client can be restarted by calling nx_dhcp_start.

Input Parameters

  • dhcp_ptr: Pointer to previously created DHCP instance.

Return Values

  • NX_SUCCESS (0x00) Successful DHCP release.

  • NX_DHCP_INTERFACE_NOT_ENABLED (0xA4) Interface not enabled for DHCP

  • NX_DHCP_NOT_BOUND (0x94) The IP address has not been leased so it can’t be released.

  • NX_PTR_ERROR (0x16) Invalid DHCP pointer

  • NX_CALLER_ERROR (0x11) Invalid caller of this service.

  • NX_INVALID_INTERFACE (0x4C) Invalid network interface

Allowed From

Threads

Example

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

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

nx_dhcp_decline

Decline IP address from DHCP Server

Prototype

UINT nx_dhcp_decline(NX_DHCP *dhcp_ptr);

Description

This service declines an IP address leased from the DHCP server on all interfaces enabled for DHCP. If NX_DHCP_CLIENT_ SEND_ ARP_PROBE is defined, the DHCP Client will send a DECLINE message if it detects that the IP address is already in use. See ARP Probes in Chapter One for more information on ARP probe configuration in the NetX DHCP Client.

The application can use this service to decline its IP address if it discovers the address is in use by other means.

This service reinitializes the DHCP Client to that it can be restarted by calling nx_dhcp_start.

Input Parameters

  • dhcp_ptr: Pointer to previously created DHCP instance.

Return Values

  • NX_SUCCESS (0x00) Decline successfully sent

  • NX_DHCP_NOT_STARTED (0x96) The DHCP instance not started

  • NX_PTR_ERROR (0x16) Invalid DHCP pointer

  • NX_CALLER_ERROR (0x11) Invalid caller of this service

Allowed From

Threads

Example

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

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

nx_dhcp_interface_decline

Decline IP address from DHCP Server on the specified interface

Prototype

UINT nx_dhcp_interface_decline(NX_DHCP *dhcp_ptr,
								UINT interface_index);

Description

This service sends the DECLINE message to the server to decline an IP address assigned by the DHCP server. It also reinitializes the DHCP Client. See nx_dhcp_decline for more details.

Input Parameters

  • dhcp_ptr: Pointer to previously created DHCP instance.

  • Interface_index: Index of interface to decline IP address

Return Values

  • NX_SUCCESS (0x00) DHCP decline message sent

  • NX_DHCP_NOT_BOUND (0x94) DHCP Client not bound

  • NX_DHCP_INTERFACE_NOT_ENABLED (0xA4) Interface not enabled for DHCP

  • NX_PTR_ERROR (0x16) Invalid DHCP pointer

  • NX_CALLER_ERROR (0x11) Invalid caller of this service.

  • NX_INVALID_INTERFACE (0x4C) Invalid network interface

Allowed From

Threads

Example

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

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

nx_dhcp_send_request

Send DHCP message to Server

Prototype

UINT nx_dhcp_send_request(
    NX_DHCP *dhcp_ptr,
    UINT dhcp_message_type);

Description

This service sends the specified DHCP message to the DHCP server on the first interface enabled for DHCP found in the DHCP Client record. To send a RELEASE or DECLINE message, the application must use the nx_dhcp[_interface]_release() or nx_dhcp_interface_decline() services respectively.

The DHCP Client must be started to use this service except for sending the INFORM_REQUEST message type.

Note

This service is not intended for the host application to ‘drive’ the DHCP Client state machine.

Input Parameters

  • dhcp_ptr: Pointer to DHCP control block.

  • dhcp_message_type: Message request (defined in nx_dhcp.h)

Return Values

  • NX_SUCCESS (0x00) DHCP message sent

  • NX_DHCP_NOT_STARTED (0x96) Invalid interface index

  • NX_DHCP_INVALID_MESSAGE (0x9B) Invalid message type to send

  • NX_PTR_ERROR (0x16) Invalid pointer input

Allowed From

Threads

Example

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

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

nx_dhcp_interface_send_request

Send DHCP message to Server on a specific interface

Prototype

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

Description

This service sends a message to the DHCP server on the specified interface if that interface is enabled for DHCP. To send a RELEASE or DECLINE message, the application must use the nx_dhcp[_interface]_release() or nx_dhcp_interface_decline() services respectively.

The DHCP Client must be started to use this service except for sending the DHCP INFORM REQUEST message type.

This service is not intended for the host application to ‘drive’ the DHCP Client state machine.

Input Parameters

  • dhcp_ptr: Pointer to DHCP control block.

  • Interface_index: Index of interface to send message on

  • dhcp_message_type: Message request (defined in nx_dhcp.h)

Return Values

  • NX_SUCCESS (0x00) DHCP message sent

  • NX_DHCP_NOT_STARTED (0x96) Invalid interface index

  • NX_DHCP_INVALID_MESSAGE (0x9B) Invalid message type to send

  • NX_DHCP_INTERFACE_NOT_ENABLED (0xA4) Interface not enabled for DHCP

  • NX_PTR_ERROR (0x16) Invalid DHCP pointer

  • NX_CALLER_ERROR (0x11) Invalid caller of this service.

  • NX_INVALID_INTERFACE (0x4C) Invalid network interface

Allowed From

Threads

Example

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

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

nx_dhcp_server_address_get

Get the DHCP Client’s DHCP server IP address

Prototype

UINT nx_dhcp_server_address_get(
    NX_DHCP *dhcp_ptr,
    ULONG server_address);

Description

This service retrieves the DHCP Client DHCP server IP address on the first interface enabled for DHCP found in the DHCP Client record. The caller can only use this service after the DHCP Client is bound to an IP address assigned by the DHCP Server. The host application can use the nx_ip_status_check service to verify IP address is set, or it can use the nx_dhcp_state_change_notify and query the DHCP Client state is NX_DHCP_STATE_BOUND. See nx_dhcp_state_change_notify for more details about setting the state change callback function.

To find the DHCP server on a specific interface when multiple interfaces are enabled for DHCP Client, use the nx_dhcp_interface_server_address_get service

Input Parameters

  • dhcp_ptr: Pointer to DHCP control block.

  • server_address: Pointer to server IP address

Return Values

  • NX_SUCCESS (0x00) DHCP server address returned

  • NX_PTR_ERROR (0x16) Invalid input pointer

  • NX_CALLER_ERROR (0x11) Invalid caller of this service.

Allowed From

Threads

Example

/* Use the state change notify service to determine the Client transition to the 
bound state and get its DHCP server IP address. 
/* void dhcp_state_change(NX_DHCP *dhcp_ptr, UCHAR new_state)
{

ULONG server_address;
UINT  status;

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

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

nx_dhcp_interface_server_address_get

Get the DHCP Client’s DHCP server IP address on the specified interface

Prototype

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

Description

This service retrieves the DHCP Client DHCP server IP address on the specified interface if that interface is enabled for DHCP. The DHCP Client must be in the Bound state. After starting the DHCP Client on that interface, the host application can either use the nx_ip_status_check service to verify the IP address is set, or it can use the DHCP Client state change callback and query the DHCP Client state is NX_DHCP_STATE_BOUND. See nx_dhcp_state_change_notify for more details about setting the state change callback function.

Input Parameters

  • dhcp_ptr: Pointer to DHCP control block.

  • Interface_index: Index of interface to obtain IP address

  • server_address: Pointer to server IP address

Return Values

  • NX_SUCCESS (0x00) DHCP server address returned

  • NX_DHCP_NO_INTERFACES_ENABLED (0xA5) No interfaces enabled for DHCP

  • NX_DHCP_NOT_BOUND (0x94) DHCP Client not bound

  • NX_PTR_ERROR (0x16) Invalid DHCP pointer

  • NX_CALLER_ERROR (0x11) Invalid caller of this service.

  • NX_INVALID_INTERFACE (0x4C) Invalid network interface

Allowed From

Threads

Example

/* Use the state change notify service to determine the Client transition to the 
bound state and get its DHCP server IP address. 
/* void dhcp_state_change(NX_DHCP *dhcp_ptr, UCHAR new_state)
{

ULONG server_address;
UINT  status;

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

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

nx_dhcp_set_interface_index

Set network interface for DHCP instance

Prototype

UINT nx_dhcp_set_interface_index(
    NX_DHCP *dhcp_ptr,
    UINT index);

Description

This service sets the network interface for the DHCP instance to connect to the DHCP Server on when running DHCP Client configured for a single network interface.

By default the DHCP Client runs on the primary interface. To run DHCP on a secondary service, use this service to set the secondary interface as the DHCP Client interface. The application must previously register the specified interface to the IP instance using the nx_ip_interface_attach service.

Note that this service is intended for applications that intend to run the DHCP Client on only one interface. To run DHCP on multiple interfaces see nx_dhcp_interface_enable for more details.

Input Parameters

  • dhcp_ptr: Pointer to DHCP control block.

  • index: Index of device network interface

Return Values

  • NX_SUCCESS (0x00) Interface is successfully set.

  • NX_INVALID_INTERFACE (0x4C) Invalid network interface

  • NX_DHCP_INTERFACE_ALREADY_ENABLED (0xA3) Interface enabled for DHCP

  • NX_DHCP_NO_RECORDS_AVAILABLE (0xA7) No record available for another

  • NX_PTR_ERROR (0x16) Invalid DHCP pointer

Allowed From

Threads

Example

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

nx_dhcp_start

Start DHCP processing

Prototype

UINT nx_dhcp_start(NX_DHCP *dhcp_ptr);

Description

This service starts DHCP processing on all interfaces enabled for DHCP. By default the primary interface is enabled for DHCP when the application calls nx_dhcp_create.

To verify when the IP instance is bound to an IP address on the DHCP Client interface, use nx_ip_status_check to see confirm the IP address is valid.

If there are other interfaces already running DHCP, this service will not affect them.

To start DHCP on a specific interface when multiple interfaces are enabled, use the nx_dhcp_interface_start service.

Input Parameters

  • dhcp_ptr: Pointer to previously created DHCP instance.

Return Values

  • NX_SUCCESS (0x00) Successful DHCP start.

  • NX_DHCP_ALREADY_STARTED (0x93) DHCP already started.

  • NX_PTR_ERROR (0x16) Invalid DHCP pointer.

  • NX_CALLER_ERROR (0x11) Invalid caller of service.

Allowed From

Threads

Example

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

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

nx_dhcp_interface_start

Start DHCP processing on the specified interface

Prototype

UINT nx_dhcp_interface_start(
    NX_DHCP *dhcp_ptr,
    UINT interface_index);

Description

This service starts DHCP processing on the specified interface if that interface is enabled for DHCP. See nx_dhcp_interface_enable for more details about enabling an interface for DHCP. By default the primary interface is enabled for DHCP when the application calls nx_dhcp_create.

If there are no other interfaces running DHCP Client this service will start/resume the DHCP Client thread and (re)activate the DHCP Client timer.

The application should use nx_ip_status_check to verify if an IP address is obtained.

Input Parameters

  • dhcp_ptr: Pointer to previously created DHCP instance

  • interface_index: Index on which to start the DHCP Client

Return Values

  • NX_SUCCESS (0x00) Successful DHCP start.

  • NX_DHCP_ALREADY_STARTED (0x93) The DHCP instance has already been started.

  • NX_PTR_ERROR (0x16) Invalid DHCP pointer.

  • NX_CALLER_ERROR (0x11) Invalid caller of service.

  • NX_INVALID_INTERFACE (0x4C) Invalid network interface

Allowed From

Threads

Example

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

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

nx_dhcp_state_change_notify

Set DHCP state change callback function

Prototype

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

Description

This service registers the specified callback function dhcp_state_change_notify for notifying an application of DHCP state changes. The callback function supplies the state the DHCP Client has transitioned into.

Following are values associated with the various DHCP states:

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

Input Parameters

  • dhcp_ptr: Pointer to previously created DHCP instance.

  • dhcp_state_change_notify: State change callback function pointer

Return Values

  • NX_SUCCESS (0x00) Successful callback set.

  • NX_PTR_ERROR (0x16) Invalid DHCP pointer.

  • NX_CALLER_ERROR (0x11) Invalid caller of service.

Allowed From

Threads, Initialization

Example

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

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

nx_dhcp_interface_state_change_notify

Set DHCP state change callback function on the specified interface

Prototype

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

Description

This service registers the specified callback function for notifying an application of DHCP state changes. The callback funciton input arguments are the interface index and the state the DHCP Client has transitioned to on that interface.

For more information about state change functions, see nx_dhcp_state_change_notify().

Input Parameters

  • dhcp_ptr: Pointer to previously created DHCP instance.

  • dhcp_interface_state_change_notify: Application callback function pointer

Return Values

  • NX_SUCCESS (0x00) Successful callback set.

  • NX_PTR_ERROR (0x16) Invalid DHCP pointer.

Allowed From

Threads, Initialization

Example

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

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


status =  nx_dhcp_interstate_state_change_notify(&my_dhcp,  
                                                 dhcp_interstate_state_change);

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

nx_dhcp_stop

Stops DHCP processing

Prototype

UINT nx_dhcp_stop(NX_DHCP *dhcp_ptr);

Description

This service stops DHCP processing on all interfaces that have started DHCP processing. If there are no interfaces processing DHCP, this service will suspend the DHCP Client thread, and inactivate the DHCP Client timer.

To stop DHCP on a specific interface if multiple interfaces are enabled for DHCP, use the nx_dhcp_interface_stop service.

Input Parameters

  • dhcp_ptr: Pointer to previously created DHCP instance.

Return Values

  • NX_SUCCESS (0x00) Successful DHCP stop

  • NX_DHCP_NOT_STARTED (0x96) The DHCP instance not started.

  • NX_PTR_ERROR (0x16) Invalid DHCP pointer.

  • NX_CALLER_ERROR (0x11) Invalid caller of service.

Allowed From

Threads

Example

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

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

nx_dhcp_interface_stop

Stop DHCP processing on the specified interface

Prototype

UINT nx_dhcp_interface_stop(
    NX_DHCP *dhcp_ptr,
    UINT interface_index);

Description

This service stops DHCP processing on the specified interface if DHCP is already started. If there are no other interfaces running DHCP, the DHCP thread and timer are suspended.

Input Parameters

  • dhcp_ptr: Pointer to previously created DHCP instance.

  • interface_index: Interface on which to stop DHCP processing

Return Values

  • NX_SUCCESS (0x00) Successful DHCP stop

  • NX_DHCP_NOT_STARTED (0x96) DHCP not started.

  • NX_PTR_ERROR (0x16) Invalid DHCP pointer.

  • NX_CALLER_ERROR (0x11) Invalid caller of service.

  • NX_INVALID_INTERFACE (0x4C) Invalid network interface

Allowed From

Threads

Example

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

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

nx_dhcp_user_option_retrieve

Retrieve a DHCP option from last server response

Prototype

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

Description

This service retrieves the specified DHCP option from the DHCP options buffer on the first interface enabled for DHCP found on the DHCP Client record. If successful, the option data is copied into the specified buffer.

Input Parameters

  • dhcp_ptr: Pointer to previously created DHCP instance.

  • request_option: DHCP option, as specified by the RFCs. See the NX_DHCP_OPTION option in nx_dhcp.h.

  • destination_ptr: Pointer to the destination for the response string.

  • destination_size: Pointer to the size of the destination and on return, the destination to place the number of bytes returned.

Return Values

  • NX_SUCCESS (0x00) Successful option retrieval.

  • NX_DHCP_NOT_BOUND (0x94) DHCP Client not bound.

  • NX_DHCP_NO_INTERFACES_ENABLED (0xA5) No interfaces enabled for DHCP

  • NX_DHCP_DEST_TO_SMALL (0x95) Destination is too small to hold response.

  • NX_DHCP_PARSE_ERROR (0x97) DHCP Option not found in Server response.

  • NX_PTR_ERROR (0x16) Invalid input pointer.

  • NX_CALLER_ERROR (0x11) Invalid caller of this service.

Allowed From

Threads

Example

UCHAR  dns_ip_string[4];
ULONG  size;

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

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

nx_dhcp_interface_user_option_retrieve

Retrieve a DHCP option from last server response on the specified interface

Prototype

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

Description

This service retrieves the specified DHCP option from the DHCP options buffer on the specified interface, if that interface is enabled for DHCP. If successful, the option data is copied into the specified buffer.

Input Parameters

  • dhcp_ptr: Pointer to previously created DHCP instance.

  • interface_index: Index on which to retrieve the specified option

  • request_option: DHCP option, as specified by the RFCs. See the NX_DHCP_OPTION option in nx_dhcp.h.

  • destination_ptr: Pointer to the destination for the response string.

  • destination_size: Pointer to the size of the destination and on return, the destination to place the number of bytes returned.

Return Values

  • NX_SUCCESS (0x00) Successful option retrieval.

  • NX_DHCP_NOT_BOUND (0x94) IP address not assigned

  • NX_DHCP_DEST_TO_SMALL (0x95) Buffer is too small

  • NX_DHCP_PARSE_ERROR (0x97) DHCP Option not found in Server response.

  • NX_PTR_ERROR (0x16) Invalid DHCP pointer.

  • NX_CALLER_ERROR (0x11) Invalid caller of service.

  • NX_INVALID_INTERFACE (0x4C) Invalid network interface

Allowed From

Threads

Example

UCHAR  dns_ip_string[4];
ULONG  size;

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

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

nx_dhcp_user_option_convert

Convert four bytes to ULONG

Prototype

ULONG nx_dhcp_user_option_convert(UCHAR *option_string_ptr);

Description

This service converts the four characters pointed to by option_string_ptr into an unsigned long value. It is especially useful when IP addresses are present.

Input Parameters

  • option_string_ptr: Pointer to previously retrieved option string.

Return Values

  • Value Value of first four bytes.

Allowed From

Threads

Example

UCHAR  dns_ip_string[4];
ULONG  dns_ip;

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

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

nx_dhcp_user_option_add_callback_set

Set callback function for adding user supplied options

Prototype

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

Description

This service registers the specified callback function for adding user supplied options.

If the callback function specified, the applications can add user supplied options into the packet by iface_index and message_type.

Note

In user’s routine. Applications must follow the DHCP options format when add user supplied options. The total size of user options must be less or equal to user_option_length, and update the user_option_length as real options length. Return NX_TRUE if add options successfully, else return NX_FALSE.

Input Parameters

  • dhcp_ptr: Pointer to previously created DHCP instance.

  • dhcp_user_option_add: Pointer to user option add function.

Return Values

  • NX_SUCCESS (0x00) Successful callback set.

  • NX_PTR_ERROR (0x16) Invalid pointer.

Allowed From

Threads

Example

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

status =  nx_dhcp_user_option_add_callback_set(&my_dhcp, my_dhcp_user_option_add);

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