Função Icmp6SendEcho2 (icmpapi.h)
A função Icmp6SendEcho2 envia uma solicitação de eco IPv6 ICMPv6 e retorna imediatamente (se Event ou ApcRoutine não for NULL) ou retorna após o tempo limite especificado. O ReplyBuffer contém a resposta de eco IPv6 ICMPv6, se houver.
Sintaxe
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
O identificador aberto retornado por Icmp6CreateFile.
[in, optional] Event
Um evento a ser sinalizado sempre que uma resposta ICMPv6 chegar. Se esse parâmetro for especificado, ele exigirá um identificador para um objeto de evento válido. Use a função CreateEvent ou CreateEventEx para criar esse objeto de evento.
Para obter mais informações sobre como usar eventos, consulte Objetos de Evento.
[in, optional] ApcRoutine
A rotina que é chamada quando o thread de chamada está em um thread alertável e uma resposta ICMPv6 chega. No Windows Vista e posteriores, PIO_APC_ROUTINE_DEFINED deve ser definido para forçar o tipo de dados desse parâmetro a PIO_APC_ROUTINE em vez de FARPROC.
No Windows Server 2003 e no Windows XP, PIO_APC_ROUTINE_DEFINED não deve ser definido para forçar o tipo de dados desse parâmetro a FARPROC.
[in, optional] ApcContext
Um parâmetro opcional passado para a rotina de retorno de chamada especificada no parâmetro ApcRoutine sempre que uma resposta ICMPv6 chega ou ocorre um erro.
[in] SourceAddress
O endereço de origem IPv6 no qual emitir a solicitação de eco, na forma de uma estrutura sockaddr .
[in] DestinationAddress
O endereço de destino IPv6 da solicitação de eco, na forma de uma estrutura sockaddr .
[in] RequestData
Um ponteiro para um buffer que contém dados a serem enviados na solicitação.
[in] RequestSize
O tamanho, em bytes, do buffer de dados de solicitação apontado pelo parâmetro RequestData .
[in, optional] RequestOptions
Um ponteiro para as opções de cabeçalho IPv6 para a solicitação, na forma de uma estrutura IP_OPTION_INFORMATION . Em uma plataforma de 64 bits, esse parâmetro está na forma de uma estrutura IP_OPTION_INFORMATION32 .
Esse parâmetro poderá ser NULL se nenhuma opção de cabeçalho IP precisar ser especificada.
[out] ReplyBuffer
Um ponteiro para um buffer para armazenar respostas à solicitação. Após o retorno, o buffer contém uma estrutura ICMPV6_ECHO_REPLY seguida pelo corpo da mensagem dos dados de resposta de eco ICMPv6. O buffer deve ser grande o suficiente para conter pelo menos uma estrutura ICMPV6_ECHO_REPLY mais o número de bytes de dados especificados no parâmetro RequestSize . Esse buffer também deve ser grande o suficiente para conter mais 8 bytes de dados (o tamanho de uma mensagem de erro ICMP) mais espaço para uma estrutura de IO_STATUS_BLOCK .
[in] ReplySize
O tamanho, em bytes, do buffer de resposta apontado pelo parâmetro ReplyBuffer . Esse buffer deve ser grande o suficiente para conter pelo menos um ICMPV6_ECHO_REPLY estrutura mais requestSize bytes de dados. Esse buffer também deve ser grande o suficiente para conter mais 8 bytes de dados (o tamanho de uma mensagem de erro ICMP) mais espaço para uma estrutura de IO_STATUS_BLOCK .
[in] Timeout
O tempo, em milissegundos, para aguardar respostas. Esse parâmetro só será usado se a função Icmp6SendEcho2 for chamada de forma síncrona. Portanto, esse parâmetro não será usado se o parâmetro ApcRoutine ou Event não for NULL.
Retornar valor
Quando chamado de forma síncrona, retorna o número de respostas recebidas e armazenadas no ReplyBuffer.
Quando chamado de forma assíncrona, indica que a operação está em andamento retornando ERROR_IO_PENDING. Você pode recuperar o resultado do número de respostas posteriormente, quando o evento especificado nos sinais do parâmetro Event ou quando a função de retorno de chamada no parâmetro ApcRoutine é chamada.
Se o valor de número de respostas (síncrono ou assíncrono) for zero, para obter informações de erro estendidas, chame GetLastError.
Se a função falhar, o código de erro estendido retornado por GetLastError poderá ser um dos valores a seguir.
| Código de retorno | Descrição |
|---|---|
|
Não há suporte a esta função neste sistema. |
|
A área de dados passada para uma chamada do sistema é muito pequena. Esse erro será retornado se o parâmetro ReplySize indicar que o buffer apontado pelo parâmetro ReplyBuffer é muito pequeno. |
|
Um dos parâmetros é inválido. Esse erro será retornado se o parâmetro IcmpHandle contiver um identificador inválido. |
|
A operação está em andamento. Esse valor é retornado por uma chamada assíncrona bem-sucedida para Icmp6SendEcho2 e não é uma indicação de um erro. |
|
Não há memória suficiente disponível para processar esse comando. |
|
A solicitação não terá suporte. Esse erro será retornado se nenhuma pilha IPv6 estiver no computador local. |
|
O tamanho do ReplyBuffer especificado no parâmetro ReplySize era muito pequeno. |
|
Use FormatMessage para obter a cadeia de caracteres de mensagem para o erro retornado. |
Comentários
A função Icmp6SendEcho2 será chamada de forma síncrona se os parâmetros ApcRoutine ou Event forem NULL. Quando chamado de forma síncrona, o valor retornado contém o número de respostas recebidas e armazenadas em ReplyBuffer depois de aguardar o tempo especificado no parâmetro Timeout . Se o valor retornado for zero, chame GetLastError para obter informações de erro estendidas.
A função Icmp6SendEcho2 é chamada de forma assíncrona quando os parâmetros ApcRoutine ou Event são especificados. Quando chamados de forma assíncrona, os parâmetros ReplyBuffer e ReplySize são necessários para aceitar a resposta. Os dados de resposta ICMP são copiados para o ReplyBuffer fornecido e o aplicativo é sinalizado (quando o parâmetro Event é especificado) ou a função de retorno de chamada é chamada (quando o parâmetro ApcRoutine é especificado). O aplicativo deve analisar os dados apontados pelo parâmetro ReplyBuffer usando a função Icmp6ParseReplies .
Se o parâmetro Event for especificado, a função Icmp6SendEcho2 será chamada de forma assíncrona. O evento especificado no parâmetro Event é sinalizado sempre que uma resposta ICMPv6 chega. Use a função CreateEvent para criar esse objeto de evento.
Se o parâmetro ApcRoutine for especificado, a função Icmp6SendEcho2 será chamada de forma assíncrona. O parâmetro ApcRoutine deve apontar para uma função de retorno de chamada definida pelo usuário. A função de retorno de chamada especificada no parâmetro ApcRoutine é chamada sempre que uma resposta ICMPv6 chega. A invocação da função de retorno de chamada especificada no parâmetro ApcRoutine é serializada.
Se os parâmetros Event e ApcRoutine forem especificados, o evento especificado no parâmetro Event será sinalizado sempre que uma resposta ICMPv6 chegar, mas a função de retorno de chamada especificada no parâmetro ApcRoutine será ignorada.
No Windows Vista e posteriores, qualquer aplicativo que chame Icmp6SendEcho2 função de forma assíncrona usando o parâmetro ApcRoutine deve definir PIO_APC_ROUTINE_DEFINED para forçar o tipo de dados do parâmetro ApcRoutine a PIO_APC_ROUTINE em vez de FARPROC.
No Windows Vista e posteriores, a função de retorno de chamada apontada pela ApcRoutine deve ser definida como uma função do tipo VOID com a seguinte sintaxe:
typedef
VOID WINAPI
(*PIO_APC_ROUTINE) (
IN PVOID ApcContext,
IN PIO_STATUS_BLOCK IoStatusBlock,
IN ULONG Reserved
);
No Windows Vista e posteriores, os parâmetros passados para a função de retorno de chamada incluem o seguinte:
No Windows Server 2003 e no Windows XP, qualquer aplicativo que chame a função Icmp6SendEcho2 de forma assíncrona usando o parâmetro ApcRoutine não deve definir PIO_APC_ROUTINE_DEFINED para forçar o tipo de dados para o parâmetro ApcRoutine para FARPROC em vez de PIO_APC_ROUTINE.
No Windows Server 2003 e no Windows XP, a função de retorno de chamada apontada pelo ApcRoutine deve ser definida como uma função do tipo VOID com a seguinte sintaxe:
typedef
VOID WINAPI
(*FARPROC) (
IN PVOID ApcContext,
);
No Windows Server 2003 e no Windows XP, os parâmetros passados para a função de retorno de chamada incluem o seguinte:
A função de retorno de chamada especificada no parâmetro ApcRoutine deve ser implementada no mesmo processo que o aplicativo que chama a função Icmp6SendEcho2 . Se a função de retorno de chamada estiver em uma DLL separada, a DLL deverá ser carregada antes de chamar a função Icmp6SendEcho2 .
Para IPv4, use as funções IcmpCreateFile, IcmpSendEcho, IcmpSendEcho2, IcmpSendEcho2Ex e IcmpParseReplies .
Observe que a diretiva include para o arquivo de cabeçalho Iphlpapi.h deve ser colocada antes do arquivo de cabeçalho Icmpapi.h .
Requisitos
| Requisito | Valor |
|---|---|
| Cliente mínimo com suporte | Windows XP [aplicativos da área de trabalho | aplicativos UWP] |
| Servidor mínimo com suporte | Windows Server 2003 [aplicativos da área de trabalho | Aplicativos UWP] |
| Plataforma de Destino | Windows |
| Cabeçalho | icmpapi.h |
| Biblioteca | Iphlpapi.lib |
| DLL | Iphlpapi.dll |