Compartir a través de


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.

Nota En Windows Server 2003 y Windows XP, el parámetro RequestOptions no es opcional y no debe ser NULL y solo se usan los miembros Ttl y Flags .
 

[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
ERROR_CALL_NOT_IMPLEMENTED
La función no es compatible con este sistema.
ERROR_INSUFFICIENT_BUFFER
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.
ERROR_INVALID_PARAMETER
Uno de los parámetros no es válido. Este error se devuelve si el parámetro IcmpHandle contiene un identificador no válido.
ERROR_IO_PENDING
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.
ERROR_NOT_ENOUGH_MEMORY
No hay suficiente memoria disponible para procesar este comando.
ERROR_NOT_SUPPORTED
No se admite la solicitud. Este error se devuelve si no hay ninguna pila IPv6 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 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.

Tenga en cuentaPIO_APC_ROUTINE_DEFINED debe definirse antes de incluir el archivo de encabezado Icmpapi.h .

 

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:

Parámetro Descripción
IN PVOID ApcContext El parámetro ApcContext pasado a la función Icmp6SendEcho2 . La aplicación puede usar este parámetro para identificar la solicitud Icmp6SendEcho2 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.
 

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:

Parámetro Descripción
IN PVOID ApcContext El parámetro ApcContext pasado a la función Icmp6SendEcho2 . La aplicación puede usar este parámetro para identificar la solicitud Icmp6SendEcho2 a la que responde la función de devolución de llamada.
 

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

Consulte también

CreateEvent

CreateEventEx

Objetos de evento

Obtener último error

ICMPV6_ECHO_REPLY

ICMP_ECHO_REPLY

IP_OPTION_INFORMATION

Icmp6CreateFile

Icmp6ParseReplies

IcmpCloseHandle

IcmpCreateFile

IcmpParseReplies

IcmpSendEcho

IcmpSendEcho2

IcmpSendEcho2Ex

sockaddr