Jump to main content

##

# TCPIP_ICMP_CallbackRegister Function

## C

    ICMP_HANDLE TCPIP_ICMP_CallbackRegister(
        void (*callback)(TCPIP_NET_HANDLE hNetIf, IPV4_ADDR * remoteIP, void * data)
    );

## Description

Allows a stack client to be notified of the receiving of a response from an ICMP query. Once an echo request reply is received, the notification handler callback will be called, letting the client know of the result of the query. The callback will contain as parameters:

- The network interface handle on which the query reply was received
- The remote host IP address
- A 32-bit value containing the sequence number in the low 16-bit part and the identifier value in the high 16-bit part.

## Preconditions

The TCP/IP Stack must be initialized and up and running.

## Parameters

Parameters | Description
--- | ---
callback | Notification function to be registered. This function will be called when an echo request reply is received.

## Returns

- A non-null handle if the registration succeeded.
- 0 if the registration operation failed (out of memory, for example).

## Remarks

None.

## Example

    // Callback function prototype
    void MyICMPCallbackFunction(TCPIP_NET_HANDLE hNetIf, IPV4_ADDR * remoteIP, void * data);

    // *****************************************************************************
    // Register callback function
    ICMP_HANDLE hIcmp = TCPIP_ICMP_CallbackRegister(&MyICMPCallbackFunction);
    if(hIcmp == 0)
    {
        // process error; couldn't register a handler
    }

    // success; I can send an Echo request and receive notification

    // *****************************************************************************
    IPV4_ADDR remoteIP = 0xc0a00101;
    uint16_t mySequenceNumber = 1;
    uint16_t myId = 0x1234;
    // send an ICMP query request
    TCPIP_ICMP_EchoRequestSend(&remoteIP, mySequenceNumber, myId);

    // *****************************************************************************
    // process the ICMP reply in the callback function
    void MyICMPCallbackFunction(TCPIP_NET_HANDLE hNetIf, IPV4_ADDR * remoteIP, void * data)
    {
        // process request from interface hNetIf and remoteIP address
        uint16_t* pReply = (uint16_t*)data;
        uint16_t myRecvId = *pReply;
        uint16_t myRecvSequenceNumber = *(pReply + 1);

        // check that the sequence number, ID and IP address match, etc.
    }