[FreeRTOS+TCP API Reference]
void vApplicationIPNetworkEventHook( eIPCallbackEvent_t eNetworkEvent );
vApplicationIPNetworkEventHook() is an application defined hook (or callback) function that is called by the TCP/IP stack when the network either connects or disconnects. As the function is called by the TCP/IP stack the TCP/IP sets sets the value of the function’s parameter.
Callback functions are implemented by the application writer, but called by the TCP/IP stack. The prototype of the callback function must exactly match the prototype above (including the function name).
The value of the eNetworkEvent parameter will equal eNetworkUp if the IP stack called vApplicationIPNetworkEventHook() because the network connected:
If ipconfigUSE_DHCP server is set to 1 in FreeRTOSIPConfig.h then
vApplicationIPNetworkEventHook( eNetworkUp ) is called when an IP address
is obtained from a DHCP server and when the lease for an IP address
previously obtained from a DHCP is renewed.
- If ipconfigUSE_DHCP server is set to 0 in FreeRTOSIPConfig.h then vApplicationIPNetworkEventHook( eNetworkUp ) is called when the network has been initialised with a static IP address.
The value of the eNetworkEvent parameter will equal eNetworkDown if the IP stack called vApplicationIPNetworkEventHook() because the network disconnected:
- the TCP/IP stack calls vApplicationIPNetworkEventHook( eNetworkDown ) when it is informed by the network driver (the interface to the Ethernet peripheral) that network connectivity has been lost. Not all drivers will implement this functionality.
The application will only call vApplicationIPNetworkEventHook() if ipconfigUSE_NETWORK_EVENT_HOOK is set to 1 in FreeRTOSIPConfig.h.
The network event hook is a good place to create tasks that use the IP stack as it ensures the tasks are not created until the TCP/IP stack is ready.