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 |
|---|---|
|
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 . |
|
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. |
|
Não há memória disponível suficiente para concluir a operação. |
|
A solicitação não terá suporte. Esse erro será retornado se nenhuma pilha IPv4 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 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.
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:
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 |