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

Функция Icmp6SendEcho2 отправляет iPv6-запрос на эхо-сообщение ICMPv6 и возвращает либо немедленно (если событие или ApcRoutine не равно NULL) или возвращается после указанного времени ожидания. ResponseBuffer содержит ответ эхо-эхо IPv6 IPv6, если он есть.

Синтаксис

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-адресов не нужно указывать.

Заметка В Windows Server 2003 и Windows XP параметр RequestOptions не является необязательным и не должен иметь значение NULL, а используются только элементы Ttl и Flags .

[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 , может быть одним из следующих значений.

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

Замечания

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

Функция Icmp6SendEcho2 вызывается асинхронно при указании параметров ApcRoutine или Event . При асинхронном вызове параметры ResponseBuffer и ResponseSize необходимы для принятия ответа. Данные ответа ICMP копируются в предоставленный ОтветBuffer , и приложение сигнализирует (когда указан параметр события ) или вызывается функция обратного вызова (при указании параметра ApcRoutine ). Приложение должно проанализировать данные, на которые указывает параметр ReplyBuffer , с помощью функции Icmp6ParseReplies .

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

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

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

В Windows Vista и более поздних версиях любое приложение, которое вызывает функцию Icmp6SendEcho2 асинхронно с помощью параметра ApcRoutine , должно определить PIO_APC_ROUTINE_DEFINED , чтобы принудительно задать тип данных для параметра ApcRoutinePIO_APC_ROUTINE, а не FARPROC.

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

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

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

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

Параметр	Description
IN PVOID ApcContext	Параметр ApcContext , переданный функции Icmp6SendEcho2 . Этот параметр можно использовать приложением для определения запроса Icmp6SendEcho2 , на который отвечает функция обратного вызова.
IN PIO_STATUS_BLOCK IoStatusBlock	Указатель на IO_STATUS_BLOCK. Эта переменная содержит окончательное состояние завершения и сведения об операции. Число байтов, фактически полученных в ответе, возвращается в элементе information структуры IO_STATUS_BLOCK . Структура IO_STATUS_BLOCK определена в файле заголовка Wdm.h .
В ULONG Зарезервировано	Этот параметр зарезервирован.

В 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 параметры, передаваемые функции обратного вызова, включают следующие:

Параметр	Description
IN PVOID ApcContext	Параметр ApcContext , переданный функции Icmp6SendEcho2 . Этот параметр можно использовать приложением для определения запроса Icmp6SendEcho2 , на который отвечает функция обратного вызова.

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

Для IPv4 используйте функции IcmpCreateFile, IcmpSendEcho, IcmpSendEcho2, IcmpSendEcho2Ex и IcmpParseReplies.

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

Требования

Требование	Ценность
Минимальный поддерживаемый клиент	Windows XP [классические приложения \| Приложения UWP]
минимальный поддерживаемый сервер	Windows Server 2003 [классические приложения \| Приложения UWP]
целевая платформа	Виндоус
Header	icmpapi.h
Library	Iphlpapi.lib
DLL	Iphlpapi.dll

См. также

IP_OPTION_INFORMATION

Обратная связь

Были ли сведения на этой странице полезными?

Last updated on 2025-11-26