Função IcmpSendEcho2Ex (icmpapi.h)

A função IcmpSendEcho2Ex envia uma solicitação de eco ICMP IPv4 e retorna imediatamente (se Event ou ApcRoutine não for NULL) ou retorna após o tempo limite especificado. O ReplyBuffer contém as respostas ICMP, se houver.

Sintaxe

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

Um identificador aberto retornado pela função ICMPCreateFile .

[in, optional] Event

Um evento a ser sinalizado sempre que uma resposta ICMP 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 ICMP chega. 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.

[in, optional] ApcContext

Um parâmetro opcional passado para a rotina de retorno de chamada especificada no parâmetro ApcRoutine sempre que uma resposta ICMP chega ou ocorre um erro.

[in] SourceAddress

O endereço de origem IPv4 no qual emitir a solicitação de eco. Esse endereço está na forma de uma estrutura IPAddr .

[in] DestinationAddress

O endereço de destino IPv4 para a solicitação de eco. Esse endereço está na forma de uma estrutura IPAddr .

[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 IP da 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 manter as respostas à solicitação. Após o retorno, o buffer contém uma matriz de estruturas de ICMP_ECHO_REPLY seguidas por opções e dados. O buffer deve ser grande o suficiente para conter pelo menos uma estrutura ICMP_ECHO_REPLY mais os bytes requestSize 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] ReplySize

O tamanho alocado, em bytes, do buffer de resposta. O buffer deve ser grande o suficiente para conter pelo menos um ICMP_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.

Valor retornado

Quando chamada de forma síncrona, a função IcmpSendEcho2Ex retorna o número de respostas recebidas e armazenadas no ReplyBuffer. Se o valor retornado for zero, chame GetLastError para obter informações de erro estendidas.

Quando chamada de forma assíncrona, a função IcmpSendEcho2Ex retorna ERROR_IO_PENDING para indicar que a operação está em andamento. Os resultados podem ser recuperados posteriormente quando o evento especificado nos sinais de parâmetro Event ou a função de retorno de chamada no parâmetro ApcRoutine for chamado.

Se o valor retornado for zero, chame GetLastError para obter informações de erro estendidas.

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_INVALID_PARAMETER
Um parâmetro inválido foi passado para a função. Esse erro será retornado se o parâmetro IcmpHandle contiver um identificador inválido. Esse erro também poderá ser retornado se o parâmetro ReplySize especificar um valor menor que o tamanho de uma estrutura ICMP_ECHO_REPLY .
ERROR_IO_PENDING
A operação está em andamento. Esse valor é retornado por uma chamada assíncrona bem-sucedida para IcmpSendEcho2Ex e não é uma indicação de um erro.
ERROR_NOT_ENOUGH_MEMORY
Não há memória disponível suficiente para concluir a operação.
ERROR_NOT_SUPPORTED
A solicitação não terá suporte. Esse erro será retornado se nenhuma pilha IPv4 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 IcmpSendEcho2Ex está disponível no Windows Server 2008 e posterior.

A função IcmpSendEcho2Ex é uma versão aprimorada da função IcmpSendEcho2 que permite que o usuário especifique o endereço de origem IPv4 no qual emitir a solicitação ICMP. A função IcmpSendEcho2Ex é útil nos casos em que um computador tem vários adaptadores de rede.

A função IcmpSendEcho2Ex 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 IcmpSendEcho2Ex é 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 IcmpParseReplies .

Se o parâmetro Event for especificado, a função IcmpSendEcho2Ex será chamada de forma assíncrona. O evento especificado no parâmetro Event é sinalizado sempre que uma resposta ICMP chega. Use a função CreateEvent para criar esse objeto de evento.

Se o parâmetro ApcRoutine for especificado, a função IcmpSendEcho2Ex 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 ICMP 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 ICMP chegar, mas a função de retorno de chamada especificada no parâmetro ApcRoutine será ignorada.

Qualquer aplicativo que chame a função IcmpSendEcho2Ex 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.

 

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
    );

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 IcmpSendEcho2Ex . Esse parâmetro pode ser usado pelo aplicativo para identificar a solicitação IcmpSendEcho2Ex à 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.
 

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 IcmpSendEcho2Ex . Se a função de retorno de chamada estiver em uma DLL separada, a DLL deverá ser carregada antes de chamar a função IcmpSendEcho2Ex .

Para IPv6, use as funções Icmp6CreateFile, Icmp6SendEcho2 e Icmp6ParseReplies .

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

   
Cliente mínimo com suporte Windows Vista com SP1 [somente aplicativos da área de trabalho]
Servidor mínimo com suporte Windows Server 2008 [somente aplicativos da área de trabalho]
Plataforma de Destino Windows
Cabeçalho icmpapi.h
Biblioteca Iphlpapi.lib
DLL Iphlpapi.dll

Confira também

CreateEvent

CreateEventEx

Objetos event

Obter Último Erro

Icmpcreatefile

ICMP_ECHO_REPLY

Ipaddr

IP_OPTION_INFORMATION

IP_OPTION_INFORMATION32

Icmp6CreateFile

Icmp6ParseReplies

Icmp6SendEcho2

IcmpParseReplies

IcmpSendEcho

IcmpSendEcho2