Jump to main content

##

# TCPIP_ICMP_EchoRequest Function

## C

    ICMP_ECHO_RESULT TCPIP_ICMP_EchoRequest(
        TCPIP_ICMP_ECHO_REQUEST* pEchoRequest,
        TCPIP_ICMP_REQUEST_HANDLE* pHandle
    );

## Description

This function allows a stack client to send an ICMP query message to a remote host. The supplied sequence number and identifier will be used in the query message. The request will also contain user supplied data. The request is scheduled and the user will be notified of the outcome of the query using the callback function that's specified in the call.

## Preconditions

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

## Returns

- ICMP_ECHO_OK - Indicates the query request was successfully sent.
- ICMP_ECHO_RESULT - The query request was unsuccessfully sent, which results in an error code (interface not ready for transmission, allocation error, etc.).

## Remarks

The data buffer that's passed as part of the callback routine is no longer available after the callback routine returns control.

This routine is more generic than TCPIP_ICMP_EchoRequestSend() and is preferred.

The user has to enforce the fact that the "identifier" field has to be unique per (destination address, source address) pair.

Currently there could be only one ping/echo request active at a time. If another echo request is active, a ICMP_ECHO_BUSY code will be returned.

Once the callback notification occurs, the echo request is completed and the icmpHandle is invalidated.

## Example

    uint8_t  myDataBuffer[200];     // buffer for the ping data
    void EchoCallback(TCPIP_ICMP_ECHO_REQUEST* pReqData, TCPIP_ICMP_REQUEST_HANDLE icmpHandle, TCPIP_ICMP_ECHO_REQUEST_RESULT result);    // callback function to be called

    TCPIP_ICMP_ECHO_REQUEST myEchoRequest;
    myEchoRequest.netH  = 0;
    myEchoRequest.targetAddr  = 0xc0a00101;
    myEchoRequest.sequenceNumber = 1;
    myEchoRequest.identifier     = 0x1234;
    myEchoRequest.pData          = myDataBuffer;
    myEchoRequest.dataSize       = sizeof(myDataBuffer);
    myEchoRequest.callback       = EchoCallback;

    if(TCPIP_ICMP_EchoRequest(&myEchoRequest, 0) == ICMP_ECHO_OK )
    {
        // successfully sent the ICMP request
        //
        // EchoCallback() will be called and data can be examined
    }
    else
    {
        // process the error
    }