自制Ping(1) IcmpSendEcho2Ex function

IcmpSendEcho2Ex function IcmpSendEcho2Ex 发送 IPv4 ICMP 请求 , 立即返回 ( 如果 Event 或 ApcRoutine 非空 ) 或等超时后返回 . ReplyBuffer 中存放 ICMP 响应 ( 如果有 ). 语法 DWORD WINAPI IcmpSendEcho2Ex( _In_ HANDLE IcmpHandle, _In_opt_ HANDLE

IcmpSendEcho2Ex function

IcmpSendEcho2Ex 发送IPv4 ICMP请求, 立即返回(如果Event 或ApcRoutine 非空)或等超时后返回. ReplyBuffer中存放ICMP响应(如果有).

语法

DWORD WINAPI IcmpSendEcho2Ex(
 _In_      HANDLE IcmpHandle,
 _In_opt_  HANDLE Event,
 _In_opt_  PIO_APC_ROUTINE ApcRoutine,
 _In_opt_  PVOID ApcContext,
 _In_      IPAddr SourceAddress,
 _In_      IPAddr DestinationAddress,
 _In_      LPVOID RequestData,
 _In_      WORD RequestSize,
 _In_opt_  PIP_OPTION_INFORMATION RequestOptions,
 _Out_     LPVOID ReplyBuffer,
 _In_      DWORD ReplySize,
 _In_      DWORD Timeout
);

参数

IcmpHandle [in]

通过ICMPCreateFile打开的handle

Event [in, optional]

每当收到一个ICMP响应, 就会触发一个event. 如果要指定该参数, 需要一个有效的事件(event). 用CreateEvent 或 CreateEventEx创建一个事件.

更多关于事件的说明, 参见 Event Objects.

ApcRoutine [in, optional]

异步处理函数, 当工作线程处在一个可报警的线程里并且收到ICMP, 则会执行该过程.

必须定义PIO_APC_ROUTINE_DEFINED, 以强制该参数的数据类型为PIO_APC_ROUTINE, 而非FARPROC.

ApcContext [in, optional]

传入ApcRoutine的参数. (每当收到一条ICMP或发生错误)

SourceAddress [in]

发出请求的IPv4(源)地址. IPAddr 类型.

DestinationAddress [in]

请求的IPv4目的地址. IPAddr 类型.

RequestData [in]

要发送的请求中包含的数据.

RequestSize [in]

RequestData (请求数据)的大小, 单位bytes.

RequestOptions [in, optional]

请求的IP头选项, 类型为 IP_OPTION_INFORMATION . 在64位平台上, 该参数类型为 IP_OPTION_INFORMATION32.

如果不需要指定指定IP头选项, 置为NULL.

ReplyBuffer [out]

用来缓存响应数据. 收到返回时, 该值为相应请求信息的一个ICMP_ECHO_REPLY 数组后跟选项和数据. 缓存大小不小于一个ICMP_ECHO_REPLY结构大小加RequestSize 大小. 64位平台对应的是ICMP_ECHO_REPLY32.

缓存大小应至少8个字节(ICMP错误信息大小)加IO_STATUS_BLOCK的大小.

ReplySize [in]

响应缓存分配的大小(字节). 缓存大小应至少为一个ICMP_ECHO_REPLY结构大小加RequestSize大小. 64位平台对应ICMP_ECHO_REPLY32.

缓存大小也应至少为8字节加IO_STATUS_BLOCK结构大小.

Timeout [in]

等待响应返回的最大时间(超时), 单位毫秒.

返回值

当以同步方式调用时, IcmpSendEcho2Ex 会返回ReplyBuffer中收到和存储的响应数. 如果返回值为0, 调用GetLastError获得具体错误信息.

当以异步方式调用时, IcmpSendEcho2Ex 会返回ERROR_IO_PENDING表示正在处理, 结果可以稍后通过事件通知或者ApcRoutine回调获取. 如果返回值为0, 调用GetLastError获得具体错误信息.

如果函数出错, GetLastError获得的错误号可以是下列值:

Return code	Description
ERROR_INVALID_PARAMETER	无效参数. 当IcmpHandle是一个无效handle或ReplySize的值小于ICMP_ECHO_REPLY或ICMP_ECHO_REPLY32时会返回该错误.
ERROR_IO_PENDING	异步处理正在进行中. 调用IcmpSendEcho2Ex异步模式成功时会返回该值, 不是错误.
ERROR_NOT_ENOUGH_MEMORY	内存不足
ERROR_NOT_SUPPORTED	不支持该请求. 如果本地计算机没有IPv4协议栈将返回该错误.
IP_BUF_TOO_SMALL	ReplySize指定的太小.
Other	使用FormatMessage 获得错误信息文本.

备注

IcmpSendEcho2Ex在Win Ser 2008及以上操作系统中可用.

IcmpSendEcho2Ex是IcmpSendEcho2的增强版, 允许用户在请求时指定IPv4源地址. IcmpSendEcho2Ex在计算机有多个网络接口时非常有用.

如果ApcRoutine或Event参数值为NULL时, IcmpSendEcho2Ex将进行同步处理, 等待指定的超时后返回数据, 返回值为含接收并存储在ReplyBuffer的响应数. 如果返回值为0, 调用GetLastError获取更多信息.

当指定了ApcRoutine或Event参数时, IcmpSendEcho2Ex将进行异步处理. ReplyBuffer和ReplySize参数需要接收响应. ICMP响应数据被拷贝进ReplyBuffer, 同时应用程序被通知(若指定了Event参数)或回调函数被调用(若指定了ApcRoutine参数).

应用程序必须使用IcmpParseReplies解析响应数据ReplyBuffer.

如果指定了Event参数, IcmpSendEcho2Ex会进行异步处理. 每当接收到一个ICMP响应时Event便会被通知. 使用CreateEvent创建event对象.

如果指定了ApcRoutine参数, IcmpSendEcho2Ex会进行同步处理. ApcRoutine应指向一个用户自定义的回调函数. 每收到一条ICMP响应ApcRoutine回调函数便会被执行一次. 回调序列化执行的.

如果Event和ApcRoutine都指定了, 会使用Event, 忽略ApcRoutine.

任何异步调用IcmpSendEcho2Ex使用ApcRoutine回调的应用程序, 都必须define PIO_APC_ROUTINE_DEFINED, 来强制ApcRoutine数据类型为PIO_APC_ROUTINE而不是FARPROC.

Note PIO_APC_ROUTINE_DEFINED must bedefined before the Icmpapi.h header file is included.

注意 PIO_APC_ROUTINE_DEFINED必须定义在Icmpapi.h之前.

回调函数ApcRoutine必须定以为如下格式:

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

传入回调函数的参数:

Parameter	Description
IN PVOID ApcContext	通过IcmpSendEcho2Ex的参数ApcContext传入的外部参数, 用于应用程序标识出正在响应的是哪个请求.
IN PIO_STATUS_BLOCK IoStatusBlock	指向IO_STATUS_BLOCK的指针. 包含了关于这次操作的最终完成状态信息. 结构IO_STATUS_BLOCK中的成员Information是返回的响应实际接收的字节数. IO_STATUS_BLOCK在头文件Wdm.h中定义.
IN ULONG Reserved	预留.

回调函数必须和调用的IcmpSendEcho2Ex在同一个进程中实现. 如果回调函数在分离的DLL中, 那么该DLL应该在调用IcmpSendEcho2Ex之前加载.

对于IPv6, 使用Icmp6CreateFile, Icmp6SendEcho2, 和Icmp6ParseReplies.

注意 头文件Iphlpapi.h必须在Icmpapi.h之前.

要求

Minimum supported client	Windows Vista with SP1 [desktop apps only]
Minimum supported server	Windows Server 2008 [desktop apps only]
Header	Icmpapi.h
Library	Iphlpapi.lib
DLL	Iphlpapi.dll