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.
| Código devuelto | Descripción |
|---|---|
|
El área de datos transferida a una llamada del sistema es demasiado pequeña. Este error se devuelve si el parámetro ReplySize indica que el búfer al que apunta el parámetro ReplyBuffer es demasiado pequeño. |
|
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 . |
|
Memoria insuficiente para completar la operación. |
|
No se admite la solicitud. Este error se devuelve si no hay ninguna pila IPv4 en el equipo local. |
|
El tamaño del objeto ReplyBuffer especificado en el parámetro ReplySize era demasiado pequeño. |
|
Use FormatMessage para obtener la cadena de mensaje para el error devuelto. |
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
| Cliente mínimo compatible | Windows 2000 Professional [solo aplicaciones de escritorio] |
| Servidor mínimo compatible | Windows 2000 Server [solo aplicaciones de escritorio] |
| 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 |
Consulte también
Comentarios
Próximamente: A lo largo de 2024 iremos eliminando gradualmente GitHub Issues como mecanismo de comentarios sobre el contenido y lo sustituiremos por un nuevo sistema de comentarios. Para más información, vea: https://aka.ms/ContentUserFeedback.
Enviar y ver comentarios de