Función IcmpSendEcho (icmpapi.h)

La función IcmpSendEcho envía una solicitud de eco ICMP IPv4 y devuelve las respuestas de respuesta de eco. La llamada devuelve cuando el tiempo de espera ha expirado o se rellena el búfer de respuesta.

Sintaxis

IPHLPAPI_DLL_LINKAGE DWORD IcmpSendEcho(
  [in]           HANDLE                 IcmpHandle,
  [in]           IPAddr                 DestinationAddress,
  [in]           LPVOID                 RequestData,
  [in]           WORD                   RequestSize,
  [in, optional] PIP_OPTION_INFORMATION RequestOptions,
  [out]          LPVOID                 ReplyBuffer,
  [in]           DWORD                  ReplySize,
  [in]           DWORD                  Timeout
);

Parámetros

[in] IcmpHandle

Identificador abierto devuelto por la función IcmpCreateFile .

[in] DestinationAddress

Dirección de destino IPv4 de la solicitud de eco, en forma de estructura IPAddr .

[in] RequestData

Puntero a un búfer que contiene datos que se van a enviar en la solicitud.

[in] RequestSize

Tamaño, en bytes, del búfer de datos de solicitud al que apunta el parámetro RequestData .

[in, optional] RequestOptions

Puntero a las opciones de encabezado IP de la solicitud, en forma de una estructura de IP_OPTION_INFORMATION . En una plataforma de 64 bits, este parámetro tiene el formato de una estructura de IP_OPTION_INFORMATION32 .

Este parámetro puede ser NULL si no es necesario especificar ninguna opción de encabezado IP.

[out] ReplyBuffer

Búfer que contiene las respuestas a la solicitud de eco. Tras la devolución, el búfer contiene una matriz de estructuras de ICMP_ECHO_REPLY seguidas de las opciones y los datos de las respuestas. El búfer debe ser lo suficientemente grande como para contener al menos una estructura de ICMP_ECHO_REPLY más RequestSize bytes de datos.

[in] ReplySize

Tamaño asignado, en bytes, del búfer de respuesta. El búfer debe ser lo suficientemente grande como para contener al menos una estructura de ICMP_ECHO_REPLY más RequestSize bytes de datos.

Este búfer también debe ser lo suficientemente grande como para contener 8 bytes más de datos (el tamaño de un mensaje de error ICMP).

[in] Timeout

El tiempo, en milisegundos, para esperar respuestas.

Valor devuelto

La función IcmpSendEcho devuelve el número de estructuras de ICMP_ECHO_REPLY almacenadas en ReplyBuffer. El estado de cada respuesta se encuentra en la estructura . Si el valor devuelto es cero, llame a GetLastError para obtener información de error adicional.

Si se produce un error en la función, el código de error extendido devuelto por GetLastError puede ser uno de los valores siguientes.

Comentarios

La función IcmpSendEcho envía una solicitud de eco ICMP a la dirección especificada y devuelve el número de respuestas recibidas y almacenadas en ReplyBuffer. La función IcmpSendEcho es una función sincrónica y devuelve después de esperar el tiempo especificado en el parámetro Timeout para una respuesta. Si el valor devuelto es cero, llame a GetLastError para obtener información de error extendida.

Las funciones IcmpSendEcho2 e IcmpSendEcho2Ex son una versión mejorada de IcmpSendEcho que admite la operación asincrónica. La función IcmpSendEcho2Ex también permite especificar la dirección IP de origen. Esta característica es útil en equipos con varias interfaces de red.

Para IPv6, use las funciones Icmp6CreateFile, Icmp6SendEcho2 e Icmp6ParseReplies .

La función IcmpSendEcho se exporta desde el Icmp.dll en Windows 2000. La función IcmpSendEcho se exporta desde el Iphlpapi.dll en Windows XP y versiones posteriores. No se recomienda la comprobación de versiones de Windows para usar esta función. Las aplicaciones que requieren portabilidad con esta función en Windows 2000, Windows XP, Windows Server 2003 y versiones posteriores de Windows no deben vincularse estáticamente al archivo Icmp.lib o Iphlpapi.lib . En su lugar, la aplicación debe comprobar la presencia de IcmpSendEcho en el Iphlpapi.dll con llamadas a LoadLibrary y GetProcAddress. Si se produce un error, la aplicación debe comprobar la presencia de IcmpSendEcho en el Icmp.dll con llamadas a LoadLibrary y GetProcAddress.

Tenga en cuenta que la directiva include para el archivo de encabezado Iphlpapi.h debe colocarse antes del archivo de encabezado Icmpapi.h .

Ejemplos

En el ejemplo siguiente se envía una solicitud de eco ICMP a la dirección IP especificada en la línea de comandos e imprime la información recibida de la primera respuesta.

#include <winsock2.h>
#include <iphlpapi.h>
#include <icmpapi.h>
#include <stdio.h>

#pragma comment(lib, "iphlpapi.lib")
#pragma comment(lib, "ws2_32.lib")

int __cdecl main(int argc, char **argv)  {

    // Declare and initialize variables
    
    HANDLE hIcmpFile;
    unsigned long ipaddr = INADDR_NONE;
    DWORD dwRetVal = 0;
    char SendData[32] = "Data Buffer";
    LPVOID ReplyBuffer = NULL;
    DWORD ReplySize = 0;
    
    // Validate the parameters
    if (argc != 2) {
        printf("usage: %s IP address\n", argv[0]);
        return 1;
    }

    ipaddr = inet_addr(argv[1]);
    if (ipaddr == INADDR_NONE) {
        printf("usage: %s IP address\n", argv[0]);
        return 1;
    }
    
    hIcmpFile = IcmpCreateFile();
    if (hIcmpFile == INVALID_HANDLE_VALUE) {
        printf("\tUnable to open handle.\n");
        printf("IcmpCreatefile returned error: %ld\n", GetLastError() );
        return 1;
    }    

    ReplySize = sizeof(ICMP_ECHO_REPLY) + sizeof(SendData);
    ReplyBuffer = (VOID*) malloc(ReplySize);
    if (ReplyBuffer == NULL) {
        printf("\tUnable to allocate memory\n");
        return 1;
    }    
    
    
    dwRetVal = IcmpSendEcho(hIcmpFile, ipaddr, SendData, sizeof(SendData), 
        NULL, ReplyBuffer, ReplySize, 1000);
    if (dwRetVal != 0) {
        PICMP_ECHO_REPLY pEchoReply = (PICMP_ECHO_REPLY)ReplyBuffer;
        struct in_addr ReplyAddr;
        ReplyAddr.S_un.S_addr = pEchoReply->Address;
        printf("\tSent icmp message to %s\n", argv[1]);
        if (dwRetVal > 1) {
            printf("\tReceived %ld icmp message responses\n", dwRetVal);
            printf("\tInformation from the first response:\n"); 
        }    
        else {    
            printf("\tReceived %ld icmp message response\n", dwRetVal);
            printf("\tInformation from this response:\n"); 
        }    
        printf("\t  Received from %s\n", inet_ntoa( ReplyAddr ) );
        printf("\t  Status = %ld\n", 
            pEchoReply->Status);
        printf("\t  Roundtrip time = %ld milliseconds\n", 
            pEchoReply->RoundTripTime);
    }
    else {
        printf("\tCall to IcmpSendEcho failed.\n");
        printf("\tIcmpSendEcho returned error: %ld\n", GetLastError() );
        return 1;
    }
    return 0;
}    
    

Requisitos

Consulte también

Obtener último error

ICMP_ECHO_REPLY

IPAddr

IP_OPTION_INFORMATION

IP_OPTION_INFORMATION32

Icmp6CreateFile

Icmp6ParseReplies

Icmp6SendEcho2

IcmpCloseHandle

IcmpCreateFile

IcmpParseReplies

IcmpSendEcho2

IcmpSendEcho2Ex