欢迎您访问程序员文章站本站旨在为大家提供分享程序员计算机编程知识!
您现在的位置是: 首页  >  数据库

自制Ping(1) IcmpSendEcho2Ex function

程序员文章站 2022-05-07 14:28:00
...

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_REPLYICMP_ECHO_REPLY32时会返回该错误.

ERROR_IO_PENDING

异步处理正在进行中. 调用IcmpSendEcho2Ex异步模式成功时会返回该值, 不是错误.

ERROR_NOT_ENOUGH_MEMORY

内存不足

ERROR_NOT_SUPPORTED

不支持该请求. 如果本地计算机没有IPv4协议栈将返回该错误.

IP_BUF_TOO_SMALL

ReplySize指定的太小.

Other

使用FormatMessage 获得错误信息文本.

备注

IcmpSendEcho2ExWin Ser 2008及以上操作系统中可用.

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

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

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

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

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

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

如果EventApcRoutine都指定了, 会使用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