Функция IcmpSendEcho (icmpapi.h)

Статья
08/24/2023

Функция IcmpSendEcho отправляет эхо-запрос IPv4 ICMP и возвращает ответы эха. Вызов возвращается по истечении времени ожидания или заполнении буфера ответов.

Синтаксис

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
);

Параметры

[in] IcmpHandle

Открытый дескриптор, возвращаемый функцией IcmpCreateFile .

[in] DestinationAddress

Адрес назначения IPv4 для эхо-запроса в виде структуры IPAddr .

[in] RequestData

Указатель на буфер, содержащий данные для отправки в запросе.

[in] RequestSize

Размер (в байтах) буфера данных запроса, на который указывает параметр RequestData .

[in, optional] RequestOptions

Указатель на параметры заголовка IP-адреса для запроса в виде структуры IP_OPTION_INFORMATION . На 64-разрядной платформе этот параметр имеет вид для структуры IP_OPTION_INFORMATION32 .

Этот параметр может иметь значение NULL , если не нужно указывать параметры заголовка IP-адресов.

[out] ReplyBuffer

Буфер для хранения ответов на эхо-запрос. После возврата буфер содержит массив ICMP_ECHO_REPLY структур, за которыми следуют параметры и данные для ответов. Буфер должен быть достаточно большим, чтобы вместить по крайней мере одну ICMP_ECHO_REPLY структуру и байты данных RequestSize .

[in] ReplySize

Выделенный размер буфера ответов в байтах. Буфер должен быть достаточно большим, чтобы вместить по крайней мере одну ICMP_ECHO_REPLY структуру и байты данных RequestSize .

Этот буфер также должен быть достаточно большим, чтобы вместить еще 8 байт данных (размер сообщения об ошибке ICMP).

[in] Timeout

Время ожидания ответов (в миллисекундах).

Возвращаемое значение

Функция IcmpSendEcho возвращает количество ICMP_ECHO_REPLY структур, хранящихся в ReplyBuffer. Состояние каждого ответа содержится в структуре . Если возвращаемое значение равно нулю, вызовите Метод GetLastError для получения дополнительных сведений об ошибке.

Если функция завершается сбоем, расширенный код ошибки, возвращаемый Командлетом GetLastError , может иметь одно из следующих значений.

Код возврата	Описание
ERROR_INSUFFICIENT_BUFFER	Область данных, переданная в системный вызов, слишком мала. Эта ошибка возвращается, если параметр ReplySize указывает, что буфер, на который указывает параметр ReplyBuffer , слишком мал.
ERROR_INVALID_PARAMETER	В функцию передан недопустимый параметр. Эта ошибка возвращается, если параметр IcmpHandle содержит недопустимый дескриптор. Эта ошибка также может быть возвращена, если параметр ReplySize задает значение, меньшее размера структуры ICMP_ECHO_REPLY .
ERROR_NOT_ENOUGH_MEMORY	Недостаточно памяти для выполнения операции.
ERROR_NOT_SUPPORTED	Запрос не поддерживается. Эта ошибка возвращается, если на локальном компьютере нет стека IPv4.
IP_BUF_TOO_SMALL	Размер объекта ReplyBuffer , указанный в параметре ReplySize , был слишком мал.
Другое	Используйте FormatMessage , чтобы получить строку сообщения для возвращенной ошибки.

Функция IcmpSendEcho отправляет эхо-запрос ICMP по указанному адресу и возвращает количество полученных и сохраненных ответов в ReplyBuffer. Функция IcmpSendEcho является синхронной функцией и возвращается после ожидания времени, указанного в параметре Timeout для ответа. Если возвращаемое значение равно нулю, вызовите Метод GetLastError для получения дополнительных сведений об ошибке.

Функции IcmpSendEcho2 и IcmpSendEcho2Ex — это улучшенная версия IcmpSendEcho , поддерживающая асинхронную операцию. Функция IcmpSendEcho2Ex также позволяет указать исходный IP-адрес. Эта функция полезна на компьютерах с несколькими сетевыми интерфейсами.

Для IPv6 используйте функции Icmp6CreateFile, Icmp6SendEcho2 и Icmp6ParseReplies .

Функция IcmpSendEcho экспортируется из Icmp.dll в Windows 2000. Функция IcmpSendEcho экспортируется из Iphlpapi.dll в Windows XP и более поздних версиях. Не рекомендуется использовать эту функцию для проверки версий Windows. Приложения, требующие переносимости с этой функцией в Windows 2000, Windows XP, Windows Server 2003 и более поздних версиях Windows, не должны статически связываться с файлом Icmp.lib или Iphlpapi.lib . Вместо этого приложение должно проверка наличие IcmpSendEcho в Iphlpapi.dll с вызовами LoadLibrary и GetProcAddress. В противном случае приложение должно проверка наличие IcmpSendEcho в Icmp.dll с вызовами LoadLibrary и GetProcAddress.

Обратите внимание, что директива include для файла заголовка Iphlpapi.h должна быть помещена перед файлом заголовка Icmpapi.h .

Примеры

В следующем примере отправляется эхо-запрос ICMP на IP-адрес, указанный в командной строке, и выводится информация, полученная из первого ответа.

#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;
}

Требования


Минимальная версия клиента	Windows 2000 Professional [только классические приложения]
Минимальная версия сервера	Windows 2000 Server [только классические приложения]
Целевая платформа	Windows
Header	icmpapi.h
Библиотека	Iphlpapi.lib
DLL	Iphlpapi.dll в Windows Server 2008, Windows Vista, Windows Server 2003 и Windows XP; Icmp.dll в Windows 2000 Server и Windows 2000 Профессиональная