Función IcmpSendEcho2Ex (icmpapi.h)

Artículo
08/24/2023

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
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 IcmpSendEcho2Ex 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 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.

Tenga en cuentaPIO_APC_ROUTINE_DEFINED debe definirse antes de incluir 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 ApcContext pasado a la función IcmpSendEcho2Ex . La aplicación puede usar este parámetro para identificar la solicitud IcmpSendEcho2Ex 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 encabezado Wdm.h .
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 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