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

Статья
08/24/2023

Функция IcmpSendEcho2Ex отправляет эхо-запрос IPv4 ICMP и возвращает либо немедленно (если event или ApcRoutine имеет значение, отличное от NULL), либо возвращается по истечении указанного времени ожидания. ReplyBuffer содержит ответы ICMP, если таковые есть.

Синтаксис

IPHLPAPI_DLL_LINKAGE DWORD IcmpSendEcho2Ex(
  [in]           HANDLE                 IcmpHandle,
  [in, optional] HANDLE                 Event,
  [in, optional] PIO_APC_ROUTINE        ApcRoutine,
  [in, optional] PVOID                  ApcContext,
  [in]           IPAddr                 SourceAddress,
  [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, optional] Event

Событие, которое будет сигнализировать при поступлении ответа ICMP. Если указан этот параметр, требуется дескриптор допустимого объекта события. Для создания этого объекта события используйте функцию CreateEvent или CreateEventEx .

Дополнительные сведения об использовании событий см. в разделе Объекты событий.

[in, optional] ApcRoutine

Подпрограмма, вызываемая, когда вызывающий поток находится в оповещенном потоке и поступает ответ ICMP. PIO_APC_ROUTINE_DEFINED необходимо определить для принудительного PIO_APC_ROUTINE типа данных для этого параметра, а не FARPROC.

[in, optional] ApcContext

Необязательный параметр, передаваемый подпрограмме обратного вызова, указанной в параметре ApcRoutine при поступлении ответа ICMP или возникновении ошибки.

[in] SourceAddress

Исходный адрес IPv4, по которому отправляется эхо-запрос. Этот адрес имеет форму структуры IPAddr .

[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 данных.

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

[in] ReplySize

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

[in] Timeout

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

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

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

При асинхронном вызове функция IcmpSendEcho2Ex возвращает ERROR_IO_PENDING, чтобы указать, что операция выполняется. Результаты можно получить позже при вызове события, указанного в параметре Event , или функции обратного вызова в параметре ApcRoutine .

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

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

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

Функция IcmpSendEcho2Ex — это расширенная версия функции IcmpSendEcho2 , которая позволяет пользователю указать исходный IPv4-адрес, по которому будет выполнен запрос ICMP. Функция IcmpSendEcho2Ex полезна в случаях, когда компьютер имеет несколько сетевых интерфейсов.

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

Функция IcmpSendEcho2Ex вызывается асинхронно при указании параметров ApcRoutine или Event . При асинхронном вызове для принятия ответа требуются параметры ReplyBuffer и ReplySize . Данные ответа ICMP копируются в предоставленный ReplyBuffer , и приложение получает сигнал (при указании параметра Event ) или вызывается функция обратного вызова (при указании параметра ApcRoutine ). Приложение должно проанализировать данные, на которые указывает параметр ReplyBuffer , с помощью функции IcmpParseReplies .

Если указан параметр Event , функция IcmpSendEcho2Ex вызывается асинхронно. Событие, указанное в параметре Event, сигнализируется при поступлении ответа ICMP. Используйте функцию CreateEvent для создания этого объекта события.

Если указан параметр ApcRoutine , функция IcmpSendEcho2Ex вызывается асинхронно. Параметр ApcRoutine должен указывать на определяемую пользователем функцию обратного вызова. Функция обратного вызова, указанная в параметре ApcRoutine , вызывается при поступлении ответа ICMP. Вызов функции обратного вызова, указанной в параметре ApcRoutine , сериализуется.

Если указаны параметры Event и ApcRoutine , то событие, указанное в параметре Event , сигнализируется при поступлении ответа ICMP, но функция обратного вызова, указанная в параметре ApcRoutine , игнорируется .

Любое приложение, которое асинхронно вызывает функцию IcmpSendEcho2Ex с помощью параметра ApcRoutine, должно определить PIO_APC_ROUTINE_DEFINED принудительного PIO_APC_ROUTINE, а не FARPROC.

Обратите вниманиеPIO_APC_ROUTINE_DEFINED необходимо определить перед включением файла заголовка Icmpapi.h .

Функция обратного вызова, на которую указывает ApcRoutine , должна быть определена как функция типа VOID со следующим синтаксисом:

typedef
VOID WINAPI
(*PIO_APC_ROUTINE) (
    IN PVOID ApcContext,
    IN PIO_STATUS_BLOCK IoStatusBlock,
    IN ULONG Reserved
    );

В функцию обратного вызова передаются следующие параметры:

Параметр	Описание
IN PVOID ApcContext	Параметр ApcContext , передаваемый в функцию IcmpSendEcho2Ex . Этот параметр может использоваться приложением для идентификации запроса IcmpSendEcho2Ex , на который отвечает функция обратного вызова.
IN PIO_STATUS_BLOCK IoStatusBlock	Указатель на IO_STATUS_BLOCK. Эта переменная содержит окончательное состояние завершения и сведения об операции. Количество байтов, фактически полученных в ответе, возвращается в элементе Informationструктуры IO_STATUS_BLOCK . Структура IO_STATUS_BLOCK определяется в файле заголовка Wdm.h .
IN ULONG Reserved	Этот параметр зарезервирован.

Функция обратного вызова, указанная в параметре ApcRoutine , должна быть реализована в том же процессе, что и приложение, вызывающее функцию IcmpSendEcho2Ex . Если функция обратного вызова находится в отдельной библиотеке DLL, то библиотека DLL должна быть загружена перед вызовом функции IcmpSendEcho2Ex .

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

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

Требования


Минимальная версия клиента	Windows Vista с пакетом обновления 1 (SP1) [только классические приложения]
Минимальная версия сервера	Windows Server 2008 [только классические приложения]
Целевая платформа	Windows
Header	icmpapi.h
Библиотека	Iphlpapi.lib
DLL	Iphlpapi.dll