Download FreeRTOS
 

Quality RTOS & Embedded Software

LIBRARIES
WHAT'S NEW
Simplifying Authenticated Cloud Connectivity for Any Device.
Designing an energy efficient and cloud-connected IoT solution with CoAP.
Introducing FreeRTOS Kernel version 11.0.0:
FreeRTOS Roadmap and Code Contribution process.
OPC-UA over TSN with FreeRTOS.
NOTE: This API has been deprecated from FreeRTOS V4.0.0 onwards. Please refer to vApplicationIPNetworkEventHook_Multi() for the new API supporting IPv6, Multiple Endpoints and Multiple interfaces. To use the deprecated APIs please set ipconfigIPv4_BACKWARD_COMPATIBLE to 1 in the FreeRTOSIPConfig.h header file.

vApplicationIPNetworkEventHook()

[FreeRTOS-Plus-TCP API Reference]

FreeRTOS_sockets.h
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.

Example usage:


/* Defined by the application code, but called by FreeRTOS-Plus-TCP when the network
connects/disconnects (if ipconfigUSE_NETWORK_EVENT_HOOK is set to 1 in
FreeRTOSIPConfig.h). */

void vApplicationIPNetworkEventHook( eIPCallbackEvent_t eNetworkEvent )
{
uint32_t ulIPAddress, ulNetMask, ulGatewayAddress, ulDNSServerAddress;
static BaseType_t xTasksAlreadyCreated = pdFALSE;
int8_t cBuffer[ 16 ];

/* Check this was a network up event, as opposed to a network down event. */
if( eNetworkEvent == eNetworkUp )
{
/* Create the tasks that use the TCP/IP stack if they have not already been
created. */

if( xTasksAlreadyCreated == pdFALSE )
{
/*
* Create the tasks here.
*/


xTasksAlreadyCreated = pdTRUE;
}

/* The network is up and configured. Print out the configuration,
which may have been obtained from a DHCP server. */

FreeRTOS_GetAddressConfiguration( &ulIPAddress,
&ulNetMask,
&ulGatewayAddress,
&ulDNSServerAddress );

/* Convert the IP address to a string then print it out. */
FreeRTOS_inet_ntoa( ulIPAddress, cBuffer );
printf( "IP Address: %srn", cBuffer );

/* Convert the net mask to a string then print it out. */
FreeRTOS_inet_ntoa( ulNetMask, cBuffer );
printf( "Subnet Mask: %srn", cBuffer );

/* Convert the IP address of the gateway to a string then print it out. */
FreeRTOS_inet_ntoa( ulGatewayAddress, cBuffer );
printf( "Gateway IP Address: %srn", cBuffer );

/* Convert the IP address of the DNS server to a string then print it out. */
FreeRTOS_inet_ntoa( ulDNSServerAddress, cBuffer );
printf( "DNS server IP Address: %srn", cBuffer );
}
}

Example vApplicationIPNetworkEventHook() definition
Copyright (C) Amazon Web Services, Inc. or its affiliates. All rights reserved.