Función IcmpSendEcho2 (icmpapi.h)
La función IcmpSendEcho2 envía una solicitud de eco ICMP IPv4 y devuelve inmediatamente (si Event o ApcRoutine no es NULL) o devuelve después del tiempo de espera especificado. ReplyBuffer contiene las respuestas de eco ICMP, si las hay.
Sintaxis
IPHLPAPI_DLL_LINKAGE DWORD IcmpSendEcho2(
[in] HANDLE IcmpHandle,
[in, optional] HANDLE Event,
[in, optional] PIO_APC_ROUTINE ApcRoutine,
[in, optional] PVOID ApcContext,
[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, optional] Event
Evento que se va a indicar (como máximo una vez) cuando llega una respuesta ICMP. Si se especifica este parámetro, se requiere un identificador para un objeto de evento válido. Use la función CreateEvent o CreateEventEx para crear este objeto de evento.
Para obtener más información sobre el uso de eventos, vea Objetos de evento.
[in, optional] ApcRoutine
La rutina a la que se llama cuando el subproceso que realiza la llamada está en un subproceso alertable y llega una respuesta ICMPv4. PIO_APC_ROUTINE_DEFINED deben definirse para forzar el tipo de datos para que este parámetro PIO_APC_ROUTINE en lugar de FARPROC.
[in, optional] ApcContext
Parámetro opcional pasado a la rutina de devolución de llamada especificada en el parámetro ApcRoutine (como máximo una vez) cuando llega una respuesta ICMP o se produce un error.
[in] DestinationAddress
Destino IPv4 de la solicitud de eco, en forma de una estructura IPAddr .
[in] RequestData
Puntero a un búfer que contiene los 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 estructura IP_OPTION_INFORMATION .
Este parámetro puede ser NULL si no es necesario especificar ninguna opción de encabezado IP.
[out] ReplyBuffer
Puntero a un búfer para contener las respuestas a la solicitud. Tras la devolución, el búfer contiene una matriz de estructuras de ICMP_ECHO_REPLY seguidas de opciones y datos.
El búfer debe ser lo suficientemente grande como para contener al menos una estructura de ICMP_ECHO_REPLY , además de RequestSize bytes de datos, además de 8 bytes adicionales de datos (el tamaño de un mensaje de error ICMP).
[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 , además de RequestSize bytes de datos, además de 8 bytes adicionales de datos (el tamaño de un mensaje de error ICMP).
[in] Timeout
Tiempo en milisegundos para esperar respuestas.
Valor devuelto
Cuando se llama de forma sincrónica, la función IcmpSendEcho2 devuelve el número de respuestas recibidas y almacenadas en ReplyBuffer. Si el valor devuelto es cero, para obtener información de error extendida, llame a GetLastError.
Cuando se llama de forma asincrónica, la función IcmpSendEcho2 devuelve cero. Una llamada posterior a GetLastError devuelve el código de error extendido ERROR_IO_PENDING para indicar que la operación está en curso. Los resultados se pueden recuperar más adelante cuando se llama al evento especificado en el parámetro Event o a la función de devolución de llamada en el parámetro ApcRoutine .
Si el valor devuelto es cero, para obtener información de error extendida, llame a GetLastError.
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.
| Código devuelto | Descripción |
|---|---|
| ERROR_INVALID_PARAMETER | Se pasó un parámetro no válido a la función. Este error se devuelve si el parámetro IcmpHandle contiene un identificador no válido. Este error también se puede devolver si el parámetro ReplySize especifica un valor menor que el tamaño de una estructura de ICMP_ECHO_REPLY . |
| ERROR_IO_PENDING | La operación está en curso. Este valor lo devuelve una llamada asincrónica correcta a IcmpSendEcho2 y no es una indicación de un error. |
| ERROR_NOT_ENOUGH_MEMORY | Memoria insuficiente para completar la operación. |
| ERROR_NOT_SUPPORTED | No se admite la solicitud. Este error se devuelve si no hay ninguna pila IPv4 en el equipo local. |
| IP_BUF_TOO_SMALL | El tamaño del replyBuffer especificado en el parámetro ReplySize era demasiado pequeño. |
| Otros | Use FormatMessage para obtener la cadena de mensaje del error devuelto. |
Comentarios
La función IcmpSendEcho2 se llama sincrónicamente si los parámetros ApcRoutine o Event son NULL. Cuando se llama de forma sincrónica, el valor devuelto contiene el número de respuestas recibidas y almacenadas en ReplyBuffer después de esperar el tiempo especificado en el parámetro Timeout . Si el valor devuelto es cero, para obtener información de error extendida, llame a GetLastError.
La función IcmpSendEcho2 se llama de forma asincrónica cuando se especifican los parámetros ApcRoutine o Event . Cuando se llama de forma asincrónica, se requieren los parámetros ReplyBuffer y ReplySize para aceptar la respuesta. Los datos de respuesta icMP se copian en el replyBuffer proporcionado y la aplicación se señala (cuando se especifica el parámetro Event ) o se llama a la función de devolución de llamada (cuando se especifica el parámetro ApcRoutine ). La aplicación debe analizar los datos a los que apunta el parámetro ReplyBuffer mediante la función IcmpParseReplies .
Si se especifica el parámetro Event , la función IcmpSendEcho2 se llama asincrónicamente. El evento especificado en el parámetro Event se señala (como máximo una vez) cuando llega una respuesta ICMP. Use la función CreateEvent o CreateEventEx para crear este objeto de evento.
Si se especifica el parámetro ApcRoutine , la función IcmpSendEcho2 se llama de forma asincrónica. El parámetro ApcRoutine debe apuntar a una función de devolución de llamada definida por el usuario. Se llama a la función de devolución de llamada especificada en el parámetro ApcRoutine (como máximo una vez) cuando llega una respuesta ICMP. La invocación de la función de devolución de llamada especificada en el parámetro ApcRoutine se serializa.
Si se especifican los parámetros Event y ApcRoutine , el evento especificado en el parámetro Event se señala (como máximo una vez) cuando llega una respuesta ICMP, pero se omite la función de devolución de llamada especificada en el parámetro ApcRoutine .
Cualquier aplicación que llame a la función IcmpSendEcho2 de forma asincrónica mediante el parámetro ApcRoutine debe definir PIO_APC_ROUTINE_DEFINED para forzar el tipo de datos del parámetro ApcRoutine a PIO_APC_ROUTINE en lugar de FARPROC.
Nota
PIO_APC_ROUTINE_DEFINED debe definirse antes de que se incluya el archivo de encabezado Icmpapi.h .
La función de devolución de llamada a la que apunta ApcRoutine debe definirse como una función de tipo VOID con la sintaxis siguiente:
typedef
VOID WINAPI
(*PIO_APC_ROUTINE) (
IN PVOID ApcContext,
IN PIO_STATUS_BLOCK IoStatusBlock,
IN ULONG Reserved
);
Los parámetros pasados a la función de devolución de llamada incluyen lo siguiente:
| Parámetro | Descripción |
|---|---|
| IN PVOID ApcContext | El parámetro AppContext pasado a la función IcmpSendEcho2 . La aplicación puede usar este parámetro para identificar la solicitud IcmpSendEcho2 a la que responde la función de devolución de llamada. |
| IN PIO_STATUS_BLOCK IoStatusBlock | Puntero a un IO_STATUS_BLOCK. Esta variable contiene el estado de finalización final e información sobre la operación. El número de bytes recibidos realmente en la respuesta se devuelve en el miembro Information del IO_STATUS_BLOCK struct. La estructura IO_STATUS_BLOCK se define en el archivo de Wdm.h encabezado. |
| IN ULONG Reserved | Este parámetro está reservado. |
La función de devolución de llamada especificada en el parámetro ApcRoutine debe implementarse en el mismo proceso que la aplicación que llama a la función IcmpSendEcho2 . Si la función de devolución de llamada está en un archivo DLL independiente, el archivo DLL debe cargarse antes de llamar a la función IcmpSendEcho2 .
La función IcmpSendEcho2 se exporta desde Iphlpapi.dll.
Para IPv6, use las funciones Icmp6CreateFile, Icmp6SendEcho2 e Icmp6ParseReplies .
La directiva include del Iphlpapi.h archivo de encabezado debe colocarse antes de la del archivo de Icmpapi.h encabezado.
Ejemplo
En el ejemplo siguiente se llama a la función IcmpSendEcho2 de forma sincrónica. El ejemplo 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;
DWORD dwError = 0;
char SendData[] = "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;
}
// Allocate space for a single reply.
ReplySize = sizeof (ICMP_ECHO_REPLY) + sizeof (SendData) + 8;
ReplyBuffer = (VOID *) malloc(ReplySize);
if (ReplyBuffer == NULL) {
printf("\tUnable to allocate memory for reply buffer\n");
return 1;
}
dwRetVal = IcmpSendEcho2(hIcmpFile, NULL, NULL, NULL,
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 ", pEchoReply->Status);
switch (pEchoReply->Status) {
case IP_DEST_HOST_UNREACHABLE:
printf("(Destination host was unreachable)\n");
break;
case IP_DEST_NET_UNREACHABLE:
printf("(Destination Network was unreachable)\n");
break;
case IP_REQ_TIMED_OUT:
printf("(Request timed out)\n");
break;
default:
printf("\n");
break;
}
printf("\t Roundtrip time = %ld milliseconds\n",
pEchoReply->RoundTripTime);
} else {
printf("Call to IcmpSendEcho2 failed.\n");
dwError = GetLastError();
switch (dwError) {
case IP_BUF_TOO_SMALL:
printf("\tReplyBufferSize too small\n");
break;
case IP_REQ_TIMED_OUT:
printf("\tRequest timed out\n");
break;
default:
printf("\tExtended error returned: %ld\n", dwError);
break;
}
return 1;
}
return 0;
}
Requisitos
| Requisito | Value |
|---|---|
| Cliente mínimo compatible | Windows 2000 Professional [aplicaciones de escritorio | Aplicaciones para UWP] |
| Servidor mínimo compatible | Windows 2000 Server [aplicaciones de escritorio | Aplicaciones para UWP] |
| Plataforma de destino | Windows |
| Encabezado | icmpapi.h |
| Library | Iphlpapi.lib |
| Archivo DLL | Iphlpapi.dll en Windows Server 2008, Windows Vista, Windows Server 2003 y Windows XP; Icmp.dll en Windows 2000 Server y Windows 2000 Professional |