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.

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

Confira também

Obter Último Erro

ICMP_ECHO_REPLY

Ipaddr

IP_OPTION_INFORMATION

IP_OPTION_INFORMATION32

Icmp6CreateFile

Icmp6ParseReplies

Icmp6SendEcho2

IcmpCloseHandle

Icmpcreatefile

IcmpParseReplies

IcmpSendEcho2

IcmpSendEcho2Ex