Step-by-step Usage Instructions

Minimal steps

1. Make sure you have the SOCK library in your project.
2. Add dhcp.tbs and dhcp.tbh files to your project (they are in current_library_set\dhcp\trunk).
3. Add #define DHCP_DEBUG_PRINT 1 to the defines section of the global.tbh file of your project. This way you will "see what's going on". Don't forget to remove this later, after you've made sure that the library operates as expected.
4. Add include "dhcp\trunk\dhcp.tbh" to the includes section of the global.tbh file.
5. Add dhcp_proc_timer() to the on_sys_timer() event handler code (see "Further considerations" below).
6. Add dhcp_proc_data() to the on_sock_data_arrival() event handler code.
7. Create empty callback function bodies (presumably in the device.tbs): callback_dhcp_ok(), callback_dhcp_failure(), callback_dhcp_pre_clear_ip(), callback_dhcp_pre_buffrq(), and callback_dhcp_buff_released().  Hint: copy from declarations in the dhcp.tbh or from our code example.
8. Call dhcp_start() from somewhere — once for every interface you want to use DHCP on. How you will do this depends on your program's logic. The no-brainer decision is to call from the on_sys_init() event handler. In the simplest case, leave the suggested_ip and host_name arguments empty. Note that dhcp_start() may fail, so it is wise to check the returned status code.
9. Implement meaningful code for the callback_dhcp_ok() function. Typically, once the DHCP process completes, you should update the IP, netmask, and gateway IP of the corresponding interface.

All of the above is illustrated in the Code Examples.

Additional recommended steps

1. Store the obtained IP address in the EEPROM and provide it with the dhcp_start(). The STG library comes handy for this — see our example. This way your device will be (mostly) able to keep using the same IP.
2. Optionally provide the device (host) name with the dhcp_start(). Some DHCP servers are linked to DNS servers and sending the host name will automatically register your device with the DNS server. By default, device names are disabled. To enable names, add a like like this to the global.tbh: #define DHCP_MAX_HOST_NAME_LEN 32 (this will allow names of up to 32 chars).
3. The use of dhcp_stop() is optional. In fact, under the normal circumstances you should let the DHCP client run continuously. This is because the library needs to take care of the "lease expiration" and renew the lease at proper times (see Operation Details). However, you may choose to terminate the DHCP client on a particular interface if the DHCP configuration fails (too many times).
4. The use of callback_dhcp_failure() is optional. You may leave the procedure empty. Alternatively, once DHCP fails (too many times), you can set an alternative IP, netmask, and gateway IP for the corresponding network interface of your device.
5. Callback_dhcp_pre_buffrq() is only called when there isn't enough free buffer space for the DHCP library's needs. Leave the procedure empty if you are supremely confident that there is always enough free buffer space. Alternatively, free up the required space when asked for it, or the DHCP will fail.
6. Callback_dhcp_buff_released() is called when the DHCP library no longer needs buffer space. A smart application would seize on the opportunity to redistribute newly available buffer pages to other needy parts of your system. Then, again, you can just ignore this chance.

See Code Examples for illustration of the points above.

Further considerations

The DHCP library expects the dhcp_proc_timer() to be called at 0.5 sec intervals. This is the default value which can be changed through the sys.onsystimerperiod property. If your project needs to have the on_sys_timer() event at a different rate, please make sure that dhcp_proc_timer() is still called 2 times/second. For example, if the on_sys_timer() is set to trigger 4 times/second, you need to add "divider" code that only calls dhcp_proc_timer() on every second invocation of the on_sys_timer().