Функция IcmpSendEcho (icmpapi.h)
Функция 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 , может иметь одно из следующих значений.
| Код возврата | Описание |
|---|---|
|
Область данных, переданная в системный вызов, слишком мала. Эта ошибка возвращается, если параметр ReplySize указывает, что буфер, на который указывает параметр ReplyBuffer , слишком мал. |
|
В функцию передан недопустимый параметр. Эта ошибка возвращается, если параметр IcmpHandle содержит недопустимый дескриптор. Эта ошибка также может быть возвращена, если параметр ReplySize задает значение, меньшее размера структуры ICMP_ECHO_REPLY . |
|
Недостаточно памяти для выполнения операции. |
|
Запрос не поддерживается. Эта ошибка возвращается, если на локальном компьютере нет стека IPv4. |
|
Размер объекта 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 Профессиональная |