Função IcmpSendEcho (icmpapi.h)
A função IcmpSendEcho envia uma solicitação de eco ICMP IPv4 e retorna todas as respostas de resposta de eco. A chamada retorna quando o tempo limite expirou ou o buffer de resposta é preenchido.
Sintaxe
IPHLPAPI_DLL_LINKAGE DWORD IcmpSendEcho(
[in] HANDLE IcmpHandle,
[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] DestinationAddress
O endereço de 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 . Em uma plataforma de 64 bits, esse parâmetro está no formato 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 buffer para armazenar todas as respostas à solicitação de eco. Após o retorno, o buffer contém uma matriz de estruturas ICMP_ECHO_REPLY seguidas pelas opções e dados das respostas. O buffer deve ser grande o suficiente para conter pelo menos um ICMP_ECHO_REPLY estrutura mais os bytes de dados RequestSize .
[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 os bytes de dados 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).
[in] Timeout
O tempo, em milissegundos, para aguardar respostas.
Valor retornado
A função IcmpSendEcho retorna o número de estruturas ICMP_ECHO_REPLY armazenadas no ReplyBuffer. O status de cada resposta está contido na estrutura . Se o valor retornado for zero, chame GetLastError para obter informações adicionais de erro.
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 |
|---|---|
|
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 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 . |
|
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 IcmpSendEcho envia uma solicitação de eco ICMP para o endereço especificado e retorna o número de respostas recebidas e armazenadas no ReplyBuffer. A função IcmpSendEcho é uma função síncrona e retorna depois de aguardar o tempo especificado no parâmetro Timeout para uma resposta. Se o valor retornado for zero, chame GetLastError para obter informações de erro estendidas.
As funções IcmpSendEcho2 e IcmpSendEcho2Ex são uma versão aprimorada do IcmpSendEcho que dá suporte à operação assíncrona. A função IcmpSendEcho2Ex também permite que o endereço IP de origem seja especificado. Esse recurso é útil em computadores com vários adaptadores de rede.
Para IPv6, use as funções Icmp6CreateFile, Icmp6SendEcho2 e Icmp6ParseReplies .
A função IcmpSendEcho é exportada do Icmp.dll no Windows 2000. A função IcmpSendEcho é exportada do Iphlpapi.dll no Windows XP e posterior. A verificação de versão do Windows não é recomendada para usar essa função. Aplicativos que exigem portabilidade com essa função no Windows 2000, Windows XP, Windows Server 2003 e versões posteriores do Windows não devem vincular estaticamente ao arquivo Icmp.lib ou Iphlpapi.lib . Em vez disso, o aplicativo deve marcar para a presença de IcmpSendEcho no Iphlpapi.dll com chamadas para LoadLibrary e GetProcAddress. Caso contrário, o aplicativo deve marcar para a presença de IcmpSendEcho no Icmp.dll com chamadas para LoadLibrary e GetProcAddress.
Observe que a diretiva include para o arquivo de cabeçalho Iphlpapi.h deve ser colocada antes do arquivo de cabeçalho Icmpapi.h .
Exemplos
O exemplo a seguir 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;
char SendData[32] = "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;
}
ReplySize = sizeof(ICMP_ECHO_REPLY) + sizeof(SendData);
ReplyBuffer = (VOID*) malloc(ReplySize);
if (ReplyBuffer == NULL) {
printf("\tUnable to allocate memory\n");
return 1;
}
dwRetVal = IcmpSendEcho(hIcmpFile, 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\n",
pEchoReply->Status);
printf("\t Roundtrip time = %ld milliseconds\n",
pEchoReply->RoundTripTime);
}
else {
printf("\tCall to IcmpSendEcho failed.\n");
printf("\tIcmpSendEcho returned error: %ld\n", GetLastError() );
return 1;
}
return 0;
}
Requisitos
| Cliente mínimo com suporte | Windows 2000 Professional [somente aplicativos da área de trabalho] |
| Servidor mínimo com suporte | Windows 2000 Server [somente aplicativos da área de trabalho] |
| 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 |