| |
| HCLIENT WINAPI IcmpCreateHandle(
|
| |
UINT nPacketSize, |
|
| |
UINT nTimeToLive, |
|
| |
DWORD dwTimeout, |
|
| |
DWORD dwReserved, |
|
| |
HWND hEventWnd, |
|
| |
UINT uEventMsg |
|
| );
|
The IcmpCreateHandle function creates a client handle for
sending and receiving ICMP echo datagrams. If an event notification
window is specified, the client will be notified when a network
event occurs.
Parameters
- nPacketSize
- An unsigned integer which specifies the default packet size
used when generating ICMP echo datagrams. The minimum packet size
is 32 bytes and the maximum size is 65,535 bytes.
- nTimeToLive
- An unsigned integer which specifies the default time-to-live
for ICMP echo datagrams. This determines the maximum number of
times that a packet will be routed from one system to another while
enroute to its destination. The minimum time-to-live value is 1,
the maximum is 255. The recommend value for this parameter is 255,
and typical applications should use a time-to-live value of at
least 30.
- dwTimeout
- An unsigned long integer which specifies the maximum number of
milliseconds to wait before the current operation times out.
- dwReserved
- A reserved parameter. This value should always be zero.
- hEventWnd
- The handle to an asynchronous notification window. This window
receives messages which notify the client when asynchronous network
events occur. If asynchronous event notification is not required,
this parameter may be NULL.
- uEventMsg
- The message identifier that is used when an asynchronous
network event occurs. This value should be greater than WM_USER as
defined in the Windows header files. If the hEventWnd
parameter is NULL, this parameter should be specified as
WM_NULL.
Return Value
If the function succeeds, the return value is a handle to the
client session. If the function fails, the return value is
INVALID_CLIENT. To get extended error information, call
IcmpGetLastError.
Remarks
The IcmpCreateHandle function creates a client handle
that is used with subsequent calls to the library. This library
uses a special type of socket called a raw socket, which is created
to send and receive ICMP echo datagrams. Raw socket support is
optional under the Windows Sockets specification, and may not be
available if a non-standard networking libraries are used or may
only be available to privileged accounts.
If the hEventWnd parameter is not NULL, the client
operates in asynchronous mode and messages will be posted to the
notification window when a network event occurs. When a message is
posted to the window, the low word of the lParam parameter
contains the event identifier. The high word of lParam
contains the low word of the error code, if an error has occurred.
The wParam parameter contains the client handle. One or more
of the following event identifiers may be sent:
| Constant |
Description |
| ICMP_EVENT_ECHO |
The client has generated an ICMP echo datagram and has sent it
to the specified host. If the datagram is received, the remote host
should generate a reply and return it to the sender. |
| ICMP_EVENT_REPLY |
The client has received an ICMP echo reply datagram from the
remote host. At this point the client can collect statistical
information. |
| ICMP_EVENT_TIMEOUT |
The network operation has exceeded the specified timeout
period. The client application may attempt to retry the
operation. |
| ICMP_EVENT_CANCEL |
The current operation has been canceled. TThe client
application may attempt to retry the operation or close the
handle. |
To cancel asynchronous notification and return the client to a
blocking mode, use the IcmpDisableEvents function.
The ability to create and send ICMP echo datagrams is limited to
privileged users. Non-administrator users will receive an error if
they attempt to create a client handle. On Windows NT it is
possible to disable this security check by creating or modifying
the system registry. Microsoft Knowledge Base article 195445 has
additional information and instructions for making this change.
Requirements
Client: Requires Windows 7, Windows Vista or Windows
XP.
Server: Requires Windows Server 2008 or Windows Server
2003.
Header: Include cstools7.h.
Library: Use csicmav7.lib.
See Also
IcmpCloseHandle, IcmpInitialize, IcmpUninitialize
|
|