Función Icmp6SendEcho2 (icmpapi.h)
La función Icmp6SendEcho2 envía una solicitud de eco ICmPv6 ICMPv6 y devuelve inmediatamente (si Event o ApcRoutine no es NULL) o devuelve después del tiempo de espera especificado. ReplyBuffer contiene la respuesta de eco IPv6 ICMPv6, si existe.
Sintaxis
IPHLPAPI_DLL_LINKAGE DWORD Icmp6SendEcho2(
[in] HANDLE IcmpHandle,
[in, optional] HANDLE Event,
[in, optional] PIO_APC_ROUTINE ApcRoutine,
[in, optional] PVOID ApcContext,
[in] sockaddr_in6 *SourceAddress,
[in] sockaddr_in6 *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 Icmp6CreateFile.
[in, optional] Event
Evento que se va a indicar cada vez que llega una respuesta ICMPv6. 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 que realiza la llamada está en un subproceso alertable y llega una respuesta ICMPv6. En Windows Vista y versiones posteriores, se debe definir PIO_APC_ROUTINE_DEFINED para forzar el tipo de datos para que este parámetro PIO_APC_ROUTINE en lugar de FARPROC.
En Windows Server 2003 y Windows XP, PIO_APC_ROUTINE_DEFINED no se debe definir para forzar el tipo de datos de este parámetro a FARPROC.
[in, optional] ApcContext
Un parámetro opcional pasado a la rutina de devolución de llamada especificada en el parámetro ApcRoutine cada vez que llega una respuesta ICMPv6 o se produce un error.
[in] SourceAddress
Dirección de origen IPv6 en la que se va a emitir la solicitud de eco, en forma de estructura sockaddr .
[in] DestinationAddress
Dirección de destino IPv6 de la solicitud de eco, en forma de estructura sockaddr .
[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 IPv6 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 que contiene las respuestas a la solicitud. Tras la devolución, el búfer contiene una estructura de ICMPV6_ECHO_REPLY seguida del cuerpo del mensaje de los datos de respuesta de respuesta de eco ICMPv6. El búfer debe ser lo suficientemente grande como para contener al menos una estructura de ICMPV6_ECHO_REPLY más el número de bytes de datos especificados en el parámetro RequestSize . 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, en bytes, del búfer de respuesta al que apunta el parámetro ReplyBuffer . Este búfer debe ser lo suficientemente grande como para contener al menos una estructura ICMPV6_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. Este parámetro solo se usa si la función Icmp6SendEcho2 se llama sincrónicamente. Por lo tanto, este parámetro no se usa si el parámetro ApcRoutine o Event no son NULL.
Valor devuelto
Cuando se llama de forma sincrónica, devuelve el número de respuestas que se reciben y almacenan en ReplyBuffer.
Cuando se llama de forma asincrónica, indica que la operación está en curso devolviendo ERROR_IO_PENDING. Puede recuperar el resultado de número de respuestas más adelante, cuando se llama al evento especificado en el parámetro Event o cuando se llama a la función de devolución de llamada en el parámetro ApcRoutine .
Si el valor de número de respuestas (sincrónico o asincrónico) 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 |
|---|---|
|
La función no es compatible con este sistema. |
|
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. |
|
Uno de los parámetros no es válido. Este error se devuelve si el parámetro IcmpHandle contiene un identificador no válido. |
|
La operación está en curso. Este valor lo devuelve una llamada asincrónica correcta a Icmp6SendEcho2 y no es una indicación de un error. |
|
No hay suficiente memoria disponible para procesar este comando. |
|
No se admite la solicitud. Este error se devuelve si no hay ninguna pila IPv6 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 Icmp6SendEcho2 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 Icmp6SendEcho2 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 Icmp6ParseReplies .
Si se especifica el parámetro Event , la función Icmp6SendEcho2 se llama de forma asincrónica. El evento especificado en el parámetro Event se señala cada vez que llega una respuesta ICMPv6. Use la función CreateEvent para crear este objeto de evento.
Si se especifica el parámetro ApcRoutine , se llama a la función Icmp6SendEcho2 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 ICMPv6. 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 ICMPv6, pero se omite la función de devolución de llamada especificada en el parámetro ApcRoutine .
En Windows Vista y versiones posteriores, cualquier aplicación que llame a la función Icmp6SendEcho2 de forma asincrónica mediante el parámetro ApcRoutine debe definir PIO_APC_ROUTINE_DEFINED para forzar el tipo de datos para que el parámetro ApcRoutinePIO_APC_ROUTINE en lugar de FARPROC.
En Windows Vista y versiones posteriores, 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
);
En Windows Vista y versiones posteriores, los parámetros pasados a la función de devolución de llamada incluyen lo siguiente:
En Windows Server 2003 y Windows XP, cualquier aplicación que llame a la función Icmp6SendEcho2 de forma asincrónica mediante el parámetro ApcRoutine no debe definir PIO_APC_ROUTINE_DEFINED forzar el tipo de datos del parámetro ApcRoutine a FARPROC en lugar de PIO_APC_ROUTINE.
En Windows Server 2003 y Windows XP, 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
(*FARPROC) (
IN PVOID ApcContext,
);
En Windows Server 2003 y Windows XP, 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 Icmp6SendEcho2 . 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 Icmp6SendEcho2 .
Para IPv4, use las funciones IcmpCreateFile, IcmpSendEcho, IcmpSendEcho2, IcmpSendEcho2Ex e IcmpParseReplies .
Tenga en cuenta que la directiva include para el archivo de encabezado Iphlpapi.h debe colocarse antes del archivo de encabezado Icmpapi.h .
Requisitos
| Requisito | Value |
|---|---|
| Cliente mínimo compatible | Windows XP [aplicaciones de escritorio | aplicaciones para UWP] |
| Servidor mínimo compatible | Windows Server 2003 [aplicaciones de escritorio | aplicaciones para UWP] |
| Plataforma de destino | Windows |
| Encabezado | icmpapi.h |
| Library | Iphlpapi.lib |
| Archivo DLL | Iphlpapi.dll |