Jump to main content

##

# PPP_EchoRequest Function

## C

    PPP_ECHO_RESULT PPP_EchoRequest (DRV_HANDLE hMac, PPP_ECHO_REQUEST* pEchoRequest, PPP_REQUEST_HANDLE* pHandle);

## Returns

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

## Description

This function allows a PPP client to send an PPP query message to a peer. 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.

## Remarks

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

The number of active echo requests at a time is controlled by PPP_MAX_ECHO_REQUESTS. If more requests are active, a PPP_ECHO_BUSY code will be returned.

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

## Preconditions

The IP PPP module initialized and up and running.

## Parameters

- hMac - driver handle (obtained by calling TCPIP_MAC_Open/DRV_PPP_MAC_Open)

- pEchoRequest - pointer to a PPP_ECHO_REQUEST data structure describing the request:

  - pData - data buffer in the request
  - dataSize - number of bytes in the data buffer
  - callback - callback function to be called when a reply is received

- pHandle - address to store a handle to this PPP request.

  - It will contain a valid handle/pointer if the call succeeded, 0 otherwise.

  - It can be used to cancel the request (if the user timeout is < than the PPP timeout: PPP_ECHO_REQUEST_TIMEOUT) Could be NULL if not needed.

## Example

        uint8_t  myDataBuffer[200];     // buffer for the echo request data
        void EchoCallback(PPP_ECHO_REQUEST* pReqData, PPP_REQUEST_HANDLE pppHandle, PPP_ECHO_RESULT result);    // callback function to be called

        PPP_ECHO_REQUEST myEchoRequest;
        myEchoRequest.pData          = myDataBuffer;
        myEchoRequest.dataSize       = sizeof(myDataBuffer);
        myEchoRequest.callback       = EchoCallback;

        if(PPP_EchoRequest(hMac, &myEchoRequest, 0) == PPP_ECHO_OK )
        {
            // successfully sent the PPP request
            //
            // EchoCallback() will be called and data can be examined
        }
        else
        {
            // process the error
        }