| |
| HCLIENT CreateHandle( |
| |
UINT nPacketSize, |
|
| |
UINT nTimeToLive, |
|
| |
DWORD dwTimeout, |
|
| |
DWORD dwReserved, |
|
| |
HWND hEventWnd, |
|
| |
UINT uEventMsg |
|
| ); |
The CreateHandle method 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
en route 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 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 method succeeds, the return value is a handle to the client
session. If the method fails, the return value is INVALID_CLIENT. To
get extended error information, call GetLastError.
Remarks
The CreateHandle method 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:
| Value |
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 DisableEvents method.
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
Minimum Desktop Platform: Windows 7 Service Pack 1
Minimum Server Platform: Windows Server 2008 R2 Service Pack 1
Sockets 2.0 update or later.
Header File: cstools11.h
Import Library: csicmv11.lib
See Also
CIcmpClient,
CloseHandle
|
|