Select your cookie preferences

We use essential cookies and similar tools that are necessary to provide our site and services. We use performance cookies to collect anonymous statistics, so we can understand how customers use our site and make improvements. Essential cookies cannot be deactivated, but you can choose “Customize” or “Decline” to decline performance cookies.

If you agree, AWS and approved third parties will also use cookies to provide useful site features, remember your preferences, and display relevant content, including relevant advertising. To accept or decline all non-essential cookies, choose “Accept” or “Decline.” To make more detailed choices, choose “Customize.”

LibrariesinsideAPI reference

Updated Jun 2025

FreeRTOS_SendPingRequest()

[FreeRTOS-Plus-TCP API Reference]

FreeRTOS_sockets.h

1BaseType_t FreeRTOS_SendPingRequest( uint32_t ulIPAddress,
2                                        size_t xNumberOfBytesToSend,
3                                        TickType_t xBlockTimeTicks );

Send a ping (ICMP echo)external_link request to a remote computer.

ipconfigSUPPORT_OUTGOING_PINGS must be set to 1 in FreeRTOSIPConfig.h for FreeRTOS_SendPingRequest() to be available.

The TCP/IP stack calls the application defined vApplicationPingReplyHook() hook (or callback) function when it receives a reply to an outgoing ping request.

Parameters:

  • ulIPAddress

    The IP address to which the ping request is sent.

    The IP address is expressed as a 32-bit number in network byte order.

  • xNumberOfBytesToSend

    The number of data bytes to send in the ping request.

  • xBlockTimeTicks

    The maximum time the calling RTOS task is prepared to wait for a network buffer if one is not immediately available.

    If a network buffer is not available then the calling RTOS task will be held in the Blocked state (so other tasks can execute) until either a buffer becomes available and therefore the ping request transmitted, or the block time expires.

    The block time is specified in ticks. Milliseconds can be converted to ticks by dividing the time in milliseconds by portTICK_PERIOD_MS.

Returns:

  • If a ping request is successfully sent then the sequence number sent in the ping message is returned to allow the application writer to match ping requests transmitted with ping replies received. See the example below.

  • If a ping request could not be sent then pdFAIL is returned.

Example usage:

This example defines two functions. vSendPing() transmits 8 bytes to a remote IP address. vApplicationPingReplyHook() is the standard FreeRTOS-Plus-TCP ping reply callback function. vApplicationPingReplyHook() receives the ping reply, then sends the received sequence number to vSendPing() where it is compared to the sequence number from the ping request.

1/* FreeRTOS-Plus-TCP sockets include. */  
2#include "FreeRTOS_sockets.h"  
3  
4/* This example code snippet assumes the queue has already been created! */  
5QueueHandle_t xPingReplyQueue;  
6  
7/* If ipconfigSUPPORT_OUTGOING_PINGS is set to 1 in FreeRTOSIPConfig.h then  
8   vApplicationPingReplyHook() is called by the TCP/IP stack when the stack receives a  
9   ping reply. */
10void vApplicationPingReplyHook( ePingReplyStatus_t eStatus, uint16_t usIdentifier )  
11{  
12    switch( eStatus )  
13    {  
14        case eSuccess    :  
15            /* A valid ping reply has been received. Post the sequence number  
16               on the queue that is read by the vSendPing() function below. Do  
17               not wait more than 10ms trying to send the message if it cannot be  
18               sent immediately because this function is called from the TCP/IP  
19               RTOS task - blocking in this function will block the TCP/IP RTOS task. */  
20            xQueueSend( xPingReplyQueue, &usIdentifier, 10 / portTICK_PERIOD_MS );  
21            break;  
22  
23        case eInvalidChecksum :  
24        case eInvalidData :  
25            /* A reply was received but it was not valid. */  
26            break;  
27    }  
28}  
29  
30  
31BaseType_t vSendPing( const int8_t *pcIPAddress )  
32{  
33uint16_t usRequestSequenceNumber, usReplySequenceNumber;  
34uint32_t ulIPAddress;  
35  
36    /* The pcIPAddress parameter holds the destination IP address as a string in  
37       decimal dot notation (for example, "192.168.0.200"). Convert the string into  
38       the required 32-bit format. */  
39    ulIPAddress = FreeRTOS_inet_addr( pcIPAddress );  
40  
41    /* Send a ping containing 8 data bytes. Wait (in the Blocked state) a  
42       maximum of 100ms for a network buffer into which the generated ping request  
43       can be written and sent. */  
44    usRequestSequenceNumber = FreeRTOS_SendPingRequest( ulIPAddress, 8, 100 / portTICK_PERIOD_MS );  
45  
46    if( usRequestSequenceNumber == pdFAIL )  
47    {  
48        /* The ping could not be sent because a network buffer could not be  
49           obtained within 100ms of FreeRTOS\_SendPingRequest() being called. */  
50    }  
51    else  
52    {  
53        /* The ping was sent. Wait 200ms for a reply. The sequence number from  
54           each reply is sent from the vApplicationPingReplyHook() on the  
55           xPingReplyQueue queue (this is not standard behaviour, but implemented in  
56           the example function above). It is assumed the queue was created before  
57           this function was called! */  
58        if( xQueueReceive( xPingReplyQueue,  
59                           &usReplySequenceNumber,  
60                           200 / portTICK_PERIOD_MS ) == pdPASS )  
61        {  
62            /* A ping reply was received. Was it a reply to the ping just sent? */  
63            if( usRequestSequenceNumber == usReplySequenceNumber )  
64            {  
65                /* This was a reply to the request just sent. */  
66            }  
67        }  
68    }  
69}

Example use of the FreeRTOS_SendPingRequest() API function