Función IcmpSendEcho2Ex (icmpapi.h)
La función IcmpSendEcho2Ex 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 ICMP, si las hay.
Sintaxis
IPHLPAPI_DLL_LINKAGE DWORD IcmpSendEcho2Ex(
[in] HANDLE IcmpHandle,
[in, optional] HANDLE Event,
[in, optional] PIO_APC_ROUTINE ApcRoutine,
[in, optional] PVOID ApcContext,
[in] IPAddr SourceAddress,
[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 cada vez que llega una respuesta ICMP. Si se especifica este parámetro, 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 eventos.
[in, optional] ApcRoutine
La rutina a la que se llama cuando el subproceso de llamada está en un subproceso alertable y llega una respuesta ICMP. PIO_APC_ROUTINE_DEFINED debe definirse para forzar que el tipo de datos de este parámetro PIO_APC_ROUTINE en lugar de FARPROC.
[in, optional] ApcContext
Parámetro opcional que se pasa a la rutina de devolución de llamada especificada en el parámetro ApcRoutine cada vez que llega una respuesta ICMP o se produce un error.
[in] SourceAddress
Dirección de origen IPv4 en la que se va a emitir la solicitud de eco. Esta dirección tiene la forma de una estructura IPAddr .
[in] DestinationAddress
Dirección de destino IPv4 para la solicitud de eco. Esta dirección tiene la 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 . En una plataforma de 64 bits, este parámetro tiene el formato para 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
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 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) más espacio para una estructura de IO_STATUS_BLOCK .
[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) más espacio para una estructura de IO_STATUS_BLOCK .
[in] Timeout
El tiempo, en milisegundos, para esperar respuestas.
Valor devuelto
Cuando se llama de forma sincrónica, la función IcmpSendEcho2Ex devuelve el número de respuestas recibidas y almacenadas en ReplyBuffer. Si el valor devuelto es cero, llame a GetLastError para obtener información de error extendida.
Cuando se llama de forma asincrónica, la función IcmpSendEcho2Ex devuelve 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, llame a GetLastError para obtener información de error extendida.
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 |
|---|---|
|
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 . |
|
La operación está en curso. Este valor lo devuelve una llamada asincrónica correcta a IcmpSendEcho2Ex y no es una indicación de un error. |
|
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 replyBuffer especificado en el parámetro ReplySize era demasiado pequeño. |
|
Use FormatMessage para obtener la cadena de mensaje del error devuelto. |
Comentarios
La función IcmpSendEcho2Ex está disponible en Windows Server 2008 y versiones posteriores.
La función IcmpSendEcho2Ex es una versión mejorada de la función IcmpSendEcho2 que permite al usuario especificar la dirección de origen IPv4 en la que emitir la solicitud ICMP. La función IcmpSendEcho2Ex es útil en los casos en los que un equipo tiene varias interfaces de red.
La función IcmpSendEcho2Ex 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, llame a GetLastError para obtener información de error extendida.
La función IcmpSendEcho2Ex 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 se señala la aplicación (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 IcmpSendEcho2Ex se llama de forma asincrónica. El evento especificado en el parámetro Event se señala cada vez que llega una respuesta ICMP. Use la función CreateEvent para crear este objeto de evento.
Si se especifica el parámetro ApcRoutine , la función IcmpSendEcho2Ex 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 cada vez que 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 cada vez que llega una respuesta ICMP, pero la función de devolución de llamada especificada en el parámetro ApcRoutine se omite .
Cualquier aplicación que llame a la función IcmpSendEcho2Ex 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.
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:
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 IcmpSendEcho2Ex . 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 IcmpSendEcho2Ex .
Para IPv6, use las funciones Icmp6CreateFile, Icmp6SendEcho2 e Icmp6ParseReplies .
Tenga en cuenta que la directiva include para el archivo de encabezado Iphlpapi.h debe colocarse antes del archivo de encabezado Icmpapi.h .
Requisitos
| Cliente mínimo compatible | Windows Vista con SP1 [solo aplicaciones de escritorio] |
| Servidor mínimo compatible | Windows Server 2008 [solo aplicaciones de escritorio] |
| Plataforma de destino | Windows |
| Encabezado | icmpapi.h |
| Library | Iphlpapi.lib |
| Archivo DLL | Iphlpapi.dll |