Função IcmpSendEcho2 (icmpapi.h)
A função IcmpSendEcho2 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 de eco ICMP, se houver.
Sintaxe
IPHLPAPI_DLL_LINKAGE DWORD IcmpSendEcho2(
[in] HANDLE IcmpHandle,
[in, optional] HANDLE Event,
[in, optional] PIO_APC_ROUTINE ApcRoutine,
[in, optional] PVOID ApcContext,
[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
O identificador aberto retornado pela função ICMPCreateFile .
[in, optional] Event
Um evento a ser sinalizado (no máximo uma vez) quando uma resposta ICMP chega. 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 ICMPv4 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 (no máximo uma vez) quando uma resposta ICMP chega ou ocorre um erro.
[in] DestinationAddress
O destino IPv4 da solicitação de eco, 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 .
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 manter pelo menos um ICMP_ECHO_REPLY estrutura, além de RequestSize bytes de dados, além de 8 bytes adicionais de dados (o tamanho de uma mensagem de erro ICMP).
[in] ReplySize
O tamanho alocado, em bytes, do buffer de resposta.
O buffer deve ser grande o suficiente para manter pelo menos um ICMP_ECHO_REPLY estrutura, além de RequestSize bytes de dados, além de 8 bytes adicionais de dados (o tamanho de uma mensagem de erro ICMP).
[in] Timeout
O tempo em milissegundos para aguardar respostas.
Retornar valor
Quando chamada de forma síncrona, a função IcmpSendEcho2 retorna o número de respostas recebidas e armazenadas no ReplyBuffer. Se o valor retornado for zero, para informações de erro estendidas, chame GetLastError.
Quando chamada de forma assíncrona, a função IcmpSendEcho2 retorna zero. Uma chamada subsequente para GetLastError retorna um código de erro estendido 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 é chamada.
Se o valor retornado for zero, para 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_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 IcmpSendEcho2 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 IcmpSendEcho2 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, para informações de erro estendidas, chame GetLastError.
A função IcmpSendEcho2 é 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 IcmpSendEcho2 será chamada de forma assíncrona. O evento especificado no parâmetro Event é sinalizado (no máximo uma vez) quando uma resposta ICMP chega. Use a função CreateEvent ou CreateEventEx para criar esse objeto de evento.
Se o parâmetro ApcRoutine for especificado, a função IcmpSendEcho2 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 (no máximo uma vez) quando 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 (no máximo uma vez) quando 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 IcmpSendEcho2 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.
Observação
PIO_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 AppContext passado para a função IcmpSendEcho2 . Esse parâmetro pode ser usado pelo aplicativo para identificar a solicitação IcmpSendEcho2 à 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 Wdm.h cabeçalho. |
| 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 IcmpSendEcho2 . Se a função de retorno de chamada estiver em uma DLL separada, a DLL deverá ser carregada antes de chamar a função IcmpSendEcho2 .
A função IcmpSendEcho2 é exportada do Iphlpapi.dll.
Para IPv6, use as funções Icmp6CreateFile, Icmp6SendEcho2 e Icmp6ParseReplies .
A diretiva include para o Iphlpapi.h arquivo de cabeçalho deve ser colocada antes da Icmpapi.h do arquivo de cabeçalho.
Exemplo
O exemplo a seguir chama a função IcmpSendEcho2 de forma síncrona. O exemplo envia uma solicitação de eco ICMP para o endereço IP especificado na linha de comando e imprime as informações recebidas da primeira resposta.
#include <winsock2.h>
#include <iphlpapi.h>
#include <icmpapi.h>
#include <stdio.h>
#pragma comment(lib, "iphlpapi.lib")
#pragma comment(lib, "ws2_32.lib")
int __cdecl main(int argc, char **argv)
{
// Declare and initialize variables.
HANDLE hIcmpFile;
unsigned long ipaddr = INADDR_NONE;
DWORD dwRetVal = 0;
DWORD dwError = 0;
char SendData[] = "Data Buffer";
LPVOID ReplyBuffer = NULL;
DWORD ReplySize = 0;
// Validate the parameters.
if (argc != 2) {
printf("usage: %s IP address\n", argv[0]);
return 1;
}
ipaddr = inet_addr(argv[1]);
if (ipaddr == INADDR_NONE) {
printf("usage: %s IP address\n", argv[0]);
return 1;
}
hIcmpFile = IcmpCreateFile();
if (hIcmpFile == INVALID_HANDLE_VALUE) {
printf("\tUnable to open handle.\n");
printf("IcmpCreatefile returned error: %ld\n", GetLastError());
return 1;
}
// Allocate space for a single reply.
ReplySize = sizeof (ICMP_ECHO_REPLY) + sizeof (SendData) + 8;
ReplyBuffer = (VOID *) malloc(ReplySize);
if (ReplyBuffer == NULL) {
printf("\tUnable to allocate memory for reply buffer\n");
return 1;
}
dwRetVal = IcmpSendEcho2(hIcmpFile, NULL, NULL, NULL,
ipaddr, SendData, sizeof (SendData), NULL,
ReplyBuffer, ReplySize, 1000);
if (dwRetVal != 0) {
PICMP_ECHO_REPLY pEchoReply = (PICMP_ECHO_REPLY) ReplyBuffer;
struct in_addr ReplyAddr;
ReplyAddr.S_un.S_addr = pEchoReply->Address;
printf("\tSent icmp message to %s\n", argv[1]);
if (dwRetVal > 1) {
printf("\tReceived %ld icmp message responses\n", dwRetVal);
printf("\tInformation from the first response:\n");
} else {
printf("\tReceived %ld icmp message response\n", dwRetVal);
printf("\tInformation from this response:\n");
}
printf("\t Received from %s\n", inet_ntoa(ReplyAddr));
printf("\t Status = %ld ", pEchoReply->Status);
switch (pEchoReply->Status) {
case IP_DEST_HOST_UNREACHABLE:
printf("(Destination host was unreachable)\n");
break;
case IP_DEST_NET_UNREACHABLE:
printf("(Destination Network was unreachable)\n");
break;
case IP_REQ_TIMED_OUT:
printf("(Request timed out)\n");
break;
default:
printf("\n");
break;
}
printf("\t Roundtrip time = %ld milliseconds\n",
pEchoReply->RoundTripTime);
} else {
printf("Call to IcmpSendEcho2 failed.\n");
dwError = GetLastError();
switch (dwError) {
case IP_BUF_TOO_SMALL:
printf("\tReplyBufferSize too small\n");
break;
case IP_REQ_TIMED_OUT:
printf("\tRequest timed out\n");
break;
default:
printf("\tExtended error returned: %ld\n", dwError);
break;
}
return 1;
}
return 0;
}
Requisitos
| Requisito | Valor |
|---|---|
| Cliente mínimo com suporte | Windows 2000 Professional [aplicativos da área de trabalho | Aplicativos UWP] |
| Servidor mínimo com suporte | Windows 2000 Server [aplicativos da área de trabalho | Aplicativos UWP] |
| Plataforma de Destino | Windows |
| Cabeçalho | icmpapi.h |
| Biblioteca | Iphlpapi.lib |
| DLL | Iphlpapi.dll no Windows Server 2008, Windows Vista, Windows Server 2003 e Windows XP; Icmp.dll no Windows 2000 Server e no Windows 2000 Professional |