Compartilhar via


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.

Nota No Windows Server 2003 e no Windows XP, o parâmetro RequestOptions não é opcional e não deve ser NULL e apenas os membros Ttl e Flags são usados.
 

[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
ERROR_CALL_NOT_IMPLEMENTED
Não há suporte a esta função neste sistema.
ERROR_INSUFFICIENT_BUFFER
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.
ERROR_INVALID_PARAMETER
Um dos parâmetros é inválido. Esse erro será retornado se o parâmetro IcmpHandle contiver um identificador inválido.
ERROR_IO_PENDING
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.
ERROR_NOT_ENOUGH_MEMORY
Não há memória suficiente disponível para processar esse comando.
ERROR_NOT_SUPPORTED
A solicitação não terá suporte. Esse erro será retornado se nenhuma pilha IPv6 estiver no computador local.
IP_BUF_TOO_SMALL
O tamanho do ReplyBuffer especificado no parâmetro ReplySize era muito pequeno.
Outros
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.

ObservePIO_APC_ROUTINE_DEFINED deve ser definido antes que o arquivo de cabeçalho Icmpapi.h seja incluído.

 

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:

Parâmetro Descrição
IN PVOID ApcContext O parâmetro ApcContext passado para a função Icmp6SendEcho2 . Esse parâmetro pode ser usado pelo aplicativo para identificar a solicitação Icmp6SendEcho2 à qual a função de retorno de chamada está respondendo.
IN PIO_STATUS_BLOCK IoStatusBlock Um ponteiro para um IO_STATUS_BLOCK. Essa variável contém o status de conclusão final e informações sobre a operação. O número de bytes realmente recebidos na resposta é retornado no membro Informações do struct IO_STATUS_BLOCK .

A estrutura IO_STATUS_BLOCK é definida no arquivo de cabeçalho Wdm.h .

IN ULONG Reserved Esse parâmetro é reservado.
 

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:

Parâmetro Descrição
IN PVOID ApcContext O parâmetro ApcContext passado para a função Icmp6SendEcho2 . Esse parâmetro pode ser usado pelo aplicativo para identificar a solicitação Icmp6SendEcho2 à qual a função de retorno de chamada está respondendo.
 

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

Confira também

CreateEvent

CreateEventEx

Objetos de evento

Obter Último Erro

ICMPV6_ECHO_REPLY

ICMP_ECHO_REPLY

IP_OPTION_INFORMATION

Icmp6CreateFile

Icmp6ParseReplies

IcmpCloseHandle

Icmpcreatefile

IcmpParseReplies

IcmpSendEcho

IcmpSendEcho2

IcmpSendEcho2Ex

Sockaddr