Compartilhar via


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

Confira também