The NetX Duo DHCP Client configuration option, NX_DHCP_CLIENT_RESTORE_STATE, allows a system to restore a previously created DHCP Client Record in a Bound state between system reboots.
When this option is enabled, the application can suspend and resume the DHCP Client thread. There is also a service to update the DHCP Client with the elapsed time between suspending and resuming the thread.
Before restoring a DHCP Client after rebooting, a previously created DHCP Client that must reach the Bound state and be is assigned an IP address from the DHCP server. Before it powers down, the DHCP application must then save the current DHCP Client record to non-volatile memory. There must also be an independent 'time keeper' elsewhere in the system to keep track of the time elapsed during this powered down state. On powering up, the application creates a new DHCP Client instance, and then updates it with the previously created DHCP Client record. The elapsed time is obtained from the "time keeper" and then applied to the time remaining on the DHCP Client lease. Note that this may cause the DHCP Client to change states e.g. from BOUND to RENEWING. At this point, the application can resume the DHCP Client.
If the time elapsed during power down puts the DHCP Client state in either a RENEW or REBIND state, the DHCP Client will automatically initiate DHCP messages requesting to renew or rebind the IP address lease. If the IP address is expired, the DHCP Client will automatically clear the IP address on the IP instance and begin the DHCP process from the INIT state, requesting a new IP address.
In this manner the DHCP Client can operate between reboots as if uninterrupted.
Below is an illustration of this feature. This assumes DHCP Client is running only on the primary interface.
/* On the power up, create an IP instance, DHCP Client, enable ICMP and UDP
and other resources (not shown) for the DHCP Client/application
in tx_application_define(). */
/* Define the DHCP application thread. */
void thread_dhcp_client_entry(ULONG thread_input)
{
UINT status;
UINT time_elapsed = 0;
NX_DHCP_CLIENT_RECORD client_nv_record;
if (/* The application checks if there is a previously saved DHCP Client record. */)
{
/* No previously saved Client record. Start the DHCP Client in the INIT state. */
status = nx_dhcp_start(&dhcp_0);
if (status !=NX_SUCCESS)
return;
do
{
/* Wait for DHCP to assign the IP address. */
} while (status != NX_SUCCESS);
/* We have a valid IP address. */
/* At some point decide we power down the system. */
/* Save the Client state data which we will subsequently need to restore the DHCP
Client. */
status = nx_dhcp_client_get_record(&dhcp_0, &client_nv_record);
/* Copy this memory to non-volatile memory (not shown). */
/* Delete the IP and DHCP Client instances before powering down. */
nx_dhcp_delete(&dhcp_0);
nx_ip_delete(&ip_0);
/* Ready to power down, having released other resources as necessary. */
}
else
{
/* The application has determined there is a previously saved record. We will
restore it to the current DHCP Client instance. */
/* Get the previous Client state data from non-volatile memory. */
/* Apply the record to the current Client instance. This will also
update the IP instance with IP address, mask etc. */
status = nx_dhcp_client_restore_record(&dhcp_0, &client_nv_record, time_elapsed);
if (status != NX_SUCCESS)
return;
/* We are ready to resume the DHCP Client thread and use the assigned IP address. */
status = nx_dhcp_resume(&dhcp_0);
if (status != NX_SUCCESS)
return;
}To suspend a DHCP Client thread without powering down, the application calls nx_dhcp_suspend on a DHCP Client which has achieved the BOUND state and which has a valid IP address. When it is ready to resume the DHCP Client it first calls nx_dhcp_client_update_time_remaining to update the time remaining on the DHCP address lease (obtaining the time elapsed from an independent time keeper). Then it calls the nx_dhcp_resume to resume the DHCP Client thread.
If the time elapsed puts the DHCP Client state in either a RENEW or REBIND state, the DHCP Client will automatically initiate DHCP messages requesting to renew or rebind the IP address lease. If the IP address is expired, the DHCP Client will automatically clear the IP address and begin the DHCP process from the INIT state, requesting a new IP address.
Below is an illustration of using this feature.
/* Create an IP instance, DHCP Client, enable ICMP and UDP
and other resources (not shown) typically in tx_application_define(). */
/* Define the DHCP application thread. */
void thread_dhcp_client_entry(ULONG thread_input)
{
/* Start the DHCP Client. */
status = nx_dhcp_start(&dhcp_0);
if (status !=NX_SUCCESS)
return;
while(1)
{
/* Wait for DHCP to obtain an IP address. */
}
/* Do tasks with the IP address e.g. send pings to another host on the network... */
status = nx_icmp_ping(…);
if (status !=NX_SUCCESS)
printf("Failed %d byte Ping!\n", length);
/* At some later time, suspend the DHCP Client e.g. the device is going to low
power mode (sleep) so we do not want any threads to wake it up. */
nx_dhcp_suspend(&dhcp_0);
/* During this suspended state, an independent timer is keeping track of the elapsed
time. */
/* At some point, we are ready to resume the DHCP Client thread. */
/* Update the DHCP Client lease time remaining with the time elapsed. */
status = nx_dhcp_client_update_time_remaining(&dhcp_0, time_elapsed);
if (status != NX_SUCCESS)
return;
/* We now can resume the DHCP Client thread. */
status = nx_dhcp_resume(&dhcp_0);
if (status != NX_SUCCESS)
return;
/* Resume tasks e.g. ping another host. */
status = nx_icmp_ping(…);
}Below is a list of services for restoring a DHCP Client state from memory and for suspending and resuming the DHCP Client.
Create a record of the current DHCP Client state
This service saves the DHCP Client running on the first interface enabled for DHCP found on the DHCP Client instance to the record pointed to by record_ptr. This allows the DHCP Client application restore its DHCP Client state after, for example, a power down and reboot.
To save a DHCP Client record on a specific interface if more than one interface is enabled for DHCP, use the nx_dhcp_interface_client_get_record service.
-
NX_SUCCESS (0x0): Client record created
-
NX_DHCP_NOT_BOUND: (0x94) Client not in Bound states
-
NX_DHCP_NO_INTERFACES_ENABLED: (0xA5) No interfaces enabled for DHCP
-
NX_PTR_ERROR: (0x16) Invalid pointer input
Create a record of the current DHCP Client state on the specified interface
ULONG nx_dhcp_interface_client_get_record(NX_DHCP *dhcp_ptr, UINT interface_index,
NX_DHCP_CLIENT_RECORD *record_ptr);This service saves the DHCP Client running on the specified interface to the record pointed to by record_ptr. This allows the DHCP Client application restore its DHCP Client state after, for example, a power down and reboot.
-
dhcp_ptr: Pointer to DHCP Client
-
interface_index: Index on which to get record
-
record_ptr: Pointer to DHCP Client record
-
NX_SUCCESS (0x0): Client record created
-
NX_DHCP_NOT_BOUND: (0x94) Client not in Bound state
-
NX_DHCP_BAD_INTERFACE_INDEX_ERROR: (0x9A) Invalid interface index
-
NX_PTR_ERROR: (0x16) Invalid DHCP pointer.
-
NX_INVALID_INTERFACE: (0x4C) Invalid network interface
Restore DHCP Client from a previously saved record
ULONG nx_dhcp_client_restore_record(NX_DHCP *dhcp_ptr,
NX_DHCP_CLIENT_RECORD *record_ptr,
ULONG time_elapsed);This service enables an application to restore its DHCP Client from a previous session using the DHCP Client record pointed to by record_ptr. The time_elapsed input is applied to the time remaining on DHCP Client lease.
This requires that the DHCP Client application created a record of the DHCP Client before powering down, and saved that record to nonvolatile memory.
If more than one interface is enabled for DHCP Client, this service is applied to the first valid interface found in the DHCP Client instance.
-
dhcp_ptr: Pointer to DHCP Client
-
record_ptr: Pointer to DHCP Client record
-
time_elapsed: Time to subtract from the lease time remaining in the input client record
-
NX_SUCCESS: (0x0) Client record restored
-
NX_DHCP_NO_INTERFACES_ENABLED: (0xA5) No interfaces running DHCP
-
NX_PTR_ERROR: (0x16) Invalid pointer Input
NX_DHCP_CLIENT_RECORD dhcp_record;
ULONG time_elapsed;
/* Obtain time (timer ticks) elapsed from independent time keeper. */
Time_elapsed = /* to be determined by application */ 1000;
/* Obtain a record of the current client state. */
status= nx_dhcp_client_restore_record(client_ptr, &dhcp_record, time_elapsed);
/* If status is NX_SUCCESS the current DHCP Client pointed to by dhcp_ptr contains the current client record updated for time elapsed during power down. */Restore DHCP Client from a previously saved record on specified interface
ULONG nx_dhcp_interface_client_restore_record(NX_DHCP *dhcp_ptr,
NX_DHCP_CLIENT_RECORD *record_ptr,
ULONG time_elapsed);This service enables an application to restore its DHCP Client on the specified interface using the DHCP Client record pointed to by record_ptr. The time_elapsed input is applied to the time remaining on DHCP Client lease.
This requires that the DHCP Client application created a record of the DHCP Client before powering down, and saved that record to nonvolatile memory.
If more than one interface is enabled for DHCP Client, this service is applied to the first valid interface found in the DHCP Client instance.
-
dhcp_ptr: Pointer to DHCP Client
-
record_ptr: Pointer to DHCP Client record
-
time_elapsed: Time to subtract from the lease time remaining in the input client record
-
NX_SUCCESS: (0x0) Client record restored
-
NX_DHCP_NOT_BOUND: (0x94) Client not bound to IP address
-
NX_DHCP_BAD_INTERFACE_INDEX_ERROR: (0x9A) Invalid interface index
-
NX_PTR_ERROR: (0x16) Invalid DHCP pointer.
-
NX_INVALID_INTERFACE: (0x4C) Invalid network interface
NX_DHCP_CLIENT_RECORD dhcp_record;
ULONG time_elapsed;
/* Obtain time (timer ticks) elapsed from independent time keeper. */
Time_elapsed = /* to be determined by application */ 1000;
/* Obtain a record of the current client state on the primary interface. */
status= nx_dhcp_interface_client_restore_record(client_ptr, 0, &dhcp_record, time_elapsed);
/* If status is NX_SUCCESS the current DHCP Client pointed to by dhcp_ptr contains the current client record updated for time elapsed during power down. */Update the time remaining on DHCP Client lease
This service updates the time remaining on the DHCP Client IP address lease with the time_elapsed input on the first interface enabled for DHCP found on the DHCP Client instance. The application must suspend the DHCP Client thread before using this service using nx_dhcp_suspend. After calling this service, the application can resume the DHCP Client thread by calling nx_dhcp_resume.
This is intended for DHCP Client applications that need to suspend the DHCP Client thread for a period of time, and then update the IP address lease time remaining.
|
Note
|
This service is not intended to be used with nx_dhcp_client_get_record and nx_dhcp_client_restore_record described previously). These services are previously described in this section. |
-
dhcp_ptr: Pointer to DHCP Client
-
time_elapsed: Time to subtract from the time remaining on the IP address lease
-
NX_SUCCESS: (0x0) Client IP lease updated
-
NX_DHCP_NO_INTERFACES_ENABLED: (0xA5) No interfaces enabled for DHCP
-
NX_PTR_ERROR: (0x16) Invalid Pointer Input
ULONG time_elapsed;
/* Obtain time (timer ticks) elapsed from independent time keeper. */
time_elapsed = /* to be determined by application */ 1000;
/* Apply the elapsed time to the DHCP Client address lease. */
status= nx_dhcp_client_update_time_remaining(client_ptr, time_elapsed);
/* If status is NX_SUCCESS the DHCP Client is updated for time elapsed. */Update the time remaining on DHCP Client lease on the specified interface
ULONG nx_dhcp_interface_client_update_time_remaining(NX_DHCP *dhcp_ptr,
UINT interface_index,
ULONG time_elapsed);This service updates the time remaining on the DHCP Client IP address lease with the time_elapsed input on the specified interface if that interface is enabled for DHCP. The application must suspend the DHCP Client thread before using this service using nx_dhcp_suspend. After calling this service, the application can resume the DHCP Client thread by calling nx_dhcp_resume. Note suspending and resuming the DHCP Client thread applies to all interfaces enabled for DHCP.
This is intended for DHCP Client applications that need to suspend the DHCP Client thread for a period of time, and then update the IP address lease time remaining.
|
Note
|
This service is not intended to be used with nx_dhcp_client_get_record and nx_dhcp_client_restore_record described previously). These services are previously described in this section. |
-
dhcp_ptr: Pointer to DHCP Client
-
interface_index: Index to interface to apply elapsed time to
-
time_elapsed: Time to subtract from the time remaining on the IP address lease
-
NX_SUCCESS: (0x0) Client IP lease updated
-
NX_DHCP_BAD_INTERFACE_INDEX_ERROR: (0x9A) Invalid interface index
-
NX_PTR_ERROR: (0x16) Invalid DHCP pointer.
-
NX_INVALID_INTERFACE: (0x4C) Invalid network interface
ULONG time_elapsed;
/* Obtain time (timer ticks) elapsed from independent time keeper. */
time_elapsed = /* to be determined by application */ 1000;
/* Apply the elapsed time to the DHCP Client address lease on interface 1. */
status= nx_dhcp_interface_client_update_time_remaining(client_ptr, 1, time_elapsed);
/* If status is NX_SUCCESS the DHCP Client is updated for time elapsed. */Suspend the DHCP Client thread
This service suspends the current DHCP Client thread. Note that unlike nx_dhcp_stop, there is no change to the DHCP Client state when this service is called.
This service suspends DHCP running on all interfaces enabled for DHCP.
To update the DHCP Client state with elapsed time while the DHCP Client is suspended, see the nx_dhcp_client_update_time_remaining described previously. To resume a suspended DHCP Client thread, the application should call nx_dhcp_resume.
-
NX_SUCCESS: (0x0) Client thread is suspended
-
NX_PTR_ERROR: (0x16) Invalid pointer Input
Resume a suspended DHCP Client thread
This service resumes a suspended DHCP Client thread. Note that there is no change to the actual DHCP Client state after resuming the Client thread. To update the time remaining on the DHCP Client IP address lease with elapsed time before calling nx_dhcp_resume, see the nx_dhcp_client_update_time_remaining described previously.
This service resumes DHCP running on all interfaces enabled for DHCP.