Функция Icmp6SendEcho2 (icmpapi.h)
Функция Icmp6SendEcho2 отправляет эхо-запрос IPv6 ICMPv6 и возвращает либо немедленно (если event или ApcRoutine не равно NULL), либо возвращается после указанного времени ожидания. ReplyBuffer содержит эхо-ответ IPv6 ICMPv6, если он есть.
Синтаксис
IPHLPAPI_DLL_LINKAGE DWORD Icmp6SendEcho2(
[in] HANDLE IcmpHandle,
[in, optional] HANDLE Event,
[in, optional] PIO_APC_ROUTINE ApcRoutine,
[in, optional] PVOID ApcContext,
[in] sockaddr_in6 *SourceAddress,
[in] sockaddr_in6 *DestinationAddress,
[in] LPVOID RequestData,
[in] WORD RequestSize,
[in, optional] PIP_OPTION_INFORMATION RequestOptions,
[out] LPVOID ReplyBuffer,
[in] DWORD ReplySize,
[in] DWORD Timeout
);
Параметры
[in] IcmpHandle
Открытый дескриптор, возвращенный Icmp6CreateFile.
[in, optional] Event
Событие, которое должно быть сигнальным при поступлении ответа ICMPv6. Если указан этот параметр, для него требуется дескриптор допустимого объекта события. Используйте функцию CreateEvent или CreateEventEx , чтобы создать этот объект события.
Дополнительные сведения об использовании событий см. в разделе Объекты событий.
[in, optional] ApcRoutine
Подпрограмма, вызываемая, когда вызывающий поток находится в потоке с оповещением и поступает ответ ICMPv6. В Windows Vista и более поздних версиях необходимо определить PIO_APC_ROUTINE_DEFINED , чтобы принудить тип данных для этого параметра PIO_APC_ROUTINE , а не FARPROC.
В Windows Server 2003 и Windows XP не следует определять PIO_APC_ROUTINE_DEFINED для принудительного применения типа данных для этого параметра в FARPROC.
[in, optional] ApcContext
Необязательный параметр, передаваемый в подпрограмму обратного вызова, указанную в параметре ApcRoutine , всякий раз, когда поступает ответ ICMPv6 или возникает ошибка.
[in] SourceAddress
Исходный адрес IPv6, по которому отправляется эхо-запрос, в виде структуры sockaddr .
[in] DestinationAddress
Адрес назначения IPv6 эхо-запроса в виде структуры sockaddr .
[in] RequestData
Указатель на буфер, содержащий данные для отправки в запросе.
[in] RequestSize
Размер (в байтах) буфера данных запроса, на который указывает параметр RequestData .
[in, optional] RequestOptions
Указатель на параметры заголовка IPv6 для запроса в виде структуры IP_OPTION_INFORMATION . На 64-разрядной платформе этот параметр находится в форме для структуры IP_OPTION_INFORMATION32 .
Этот параметр может иметь значение NULL, если не нужно указывать параметры ip-заголовка.
[out] ReplyBuffer
Указатель на буфер для хранения ответов на запрос. После возврата буфер содержит структуру ICMPV6_ECHO_REPLY , за которой следует текст сообщения из данных ответа эха ICMPv6. Буфер должен быть достаточно большим, чтобы вместить по крайней мере одну ICMPV6_ECHO_REPLY структуру, а также количество байтов данных, указанное в параметре RequestSize . Этот буфер также должен быть достаточно большим, чтобы вместить еще 8 байт данных (размер сообщения об ошибке ICMP) и пространство для IO_STATUS_BLOCK структуры.
[in] ReplySize
Размер (в байтах) буфера ответов, на который указывает параметр ReplyBuffer . Этот буфер должен быть достаточно большим, чтобы вместить по крайней мере одну ICMPV6_ECHO_REPLY структуру и байты RequestSize данных. Этот буфер также должен быть достаточно большим, чтобы вместить еще 8 байт данных (размер сообщения об ошибке ICMP) и пространство для IO_STATUS_BLOCK структуры.
[in] Timeout
Время ожидания ответов (в миллисекундах). Этот параметр используется, только если функция Icmp6SendEcho2 вызывается синхронно. Поэтому этот параметр не используется, если параметр ApcRoutine или Event не имеет значения NULL.
Возвращаемое значение
При синхронном вызове возвращает количество ответов, полученных и сохраненных в ReplyBuffer.
При асинхронном вызове указывает, что операция выполняется, возвращая ERROR_IO_PENDING. Результат числа ответов можно получить позже, когда событие, указанное в параметре Event , сигнализирует, или при вызове функции обратного вызова в параметре ApcRoutine .
Если значение (синхронное или асинхронное) число ответов равно нулю, для расширенной информации об ошибке вызовите Метод GetLastError.
Если функция завершается сбоем, расширенный код ошибки, возвращаемый GetLastError , может иметь одно из следующих значений.
| Код возврата | Описание |
|---|---|
|
Эта функция не поддерживается в этой системе. |
|
Область данных, передаваемая в системный вызов, слишком мала. Эта ошибка возвращается, если параметр ReplySize указывает, что буфер, на который указывает параметр ReplyBuffer , слишком мал. |
|
Один из параметров недопустим. Эта ошибка возвращается, если параметр IcmpHandle содержит недопустимый дескриптор. |
|
Операция выполняется. Это значение возвращается при успешном асинхронном вызове Icmp6SendEcho2 и не указывает на ошибку. |
|
Недостаточно памяти для обработки этой команды. |
|
Запрос не поддерживается. Эта ошибка возвращается, если на локальном компьютере нет стека IPv6. |
|
Размер Объекта ReplyBuffer , указанный в параметре ReplySize , был слишком мал. |
|
Используйте FormatMessage , чтобы получить строку сообщения для возвращаемой ошибки. |
Комментарии
Функция Icmp6SendEcho2 вызывается синхронно, если параметры ApcRoutine или Event имеют значение NULL. При синхронном вызове возвращаемое значение содержит количество ответов, полученных и сохраненных в ReplyBuffer после ожидания времени, указанного в параметре Timeout . Если возвращаемое значение равно нулю, вызовите Метод GetLastError для получения расширенных сведений об ошибке.
Функция Icmp6SendEcho2 вызывается асинхронно при указании параметров ApcRoutine или Event . При асинхронном вызове для принятия ответа требуются параметры ReplyBuffer и ReplySize . Данные ответа ICMP копируются в предоставленный ReplyBuffer , и приложение получает сигнал (при указании параметра Event ) или вызывается функция обратного вызова (при указании параметра ApcRoutine ). Приложение должно проанализировать данные, на которые указывает параметр ReplyBuffer , с помощью функции Icmp6ParseReplies .
Если указан параметр Event , функция Icmp6SendEcho2 вызывается асинхронно. Событие, указанное в параметре Event, получает сигнал при поступлении ответа ICMPv6. Используйте функцию CreateEvent для создания этого объекта события.
Если указан параметр ApcRoutine , функция Icmp6SendEcho2 вызывается асинхронно. Параметр ApcRoutine должен указывать на определяемую пользователем функцию обратного вызова. Функция обратного вызова, указанная в параметре ApcRoutine , вызывается при поступлении ответа ICMPv6. Вызов функции обратного вызова, указанной в параметре ApcRoutine , сериализуется.
Если указаны параметры Event и ApcRoutine , событие, указанное в параметре Event , получает сигнал при поступлении ответа ICMPv6, но функция обратного вызова, указанная в параметре ApcRoutine , игнорируется .
В Windows Vista и более поздних версиях любое приложение, которое асинхронно вызывает функцию Icmp6SendEcho2 с помощью параметра ApcRoutine, должно определять PIO_APC_ROUTINE_DEFINED, чтобы принудительно PIO_APC_ROUTINE, а не FARPROC.
В Windows Vista и более поздних версиях функция обратного вызова, на которую указывает ApcRoutine , должна быть определена как функция типа VOID со следующим синтаксисом:
typedef
VOID WINAPI
(*PIO_APC_ROUTINE) (
IN PVOID ApcContext,
IN PIO_STATUS_BLOCK IoStatusBlock,
IN ULONG Reserved
);
В Windows Vista и более поздних версиях в функцию обратного вызова передаются следующие параметры:
В Windows Server 2003 и Windows XP любое приложение, которое асинхронно вызывает функцию Icmp6SendEcho2 с помощью параметра ApcRoutine , не должно определять PIO_APC_ROUTINE_DEFINED принудительного применения типа данных для параметра ApcRoutine в FARPROC , а не PIO_APC_ROUTINE.
В Windows Server 2003 и Windows XP функция обратного вызова, на которую указывает ApcRoutine , должна быть определена как функция типа VOID со следующим синтаксисом:
typedef
VOID WINAPI
(*FARPROC) (
IN PVOID ApcContext,
);
В Windows Server 2003 и Windows XP в функцию обратного вызова передаются следующие параметры:
Функция обратного вызова, указанная в параметре ApcRoutine , должна быть реализована в том же процессе, что и приложение, вызывающее функцию Icmp6SendEcho2 . Если функция обратного вызова находится в отдельной библиотеке DLL, ее следует загрузить перед вызовом функции Icmp6SendEcho2 .
Для IPv4 используйте функции IcmpCreateFile, IcmpSendEcho, IcmpSendEcho2, IcmpSendEcho2Ex и IcmpParseReplies .
Обратите внимание, что директива include для файла заголовка Iphlpapi.h должна быть помещена перед файлом заголовка Icmpapi.h .
Требования
| Требование | Значение |
|---|---|
| Минимальная версия клиента | Windows XP [классические приложения | Приложения UWP] |
| Минимальная версия сервера | Windows Server 2003 [классические приложения | Приложения UWP] |
| Целевая платформа | Windows |
| Header | icmpapi.h |
| Библиотека | Iphlpapi.lib |
| DLL | Iphlpapi.dll |