| |
| INT RegisterEvent( |
| |
UINT nEventId, |
|
| |
WHOISEVENTPROC lpEventProc, |
|
| |
DWORD_PTR dwParam |
|
| ); |
The RegisterEvent method registers an event handler
for the specified event.
Parameters
- nEventId
- An unsigned integer which specifies which event should be
registered with the specified callback function. One of the
following values may be used:
| Value |
Description |
| WHOIS_EVENT_CONNECT |
The connection to the server has completed. |
| WHOIS_EVENT_DISCONNECT |
The server has closed the connection to the client. The
client should read any remaining data and disconnect. |
| WHOIS_EVENT_READ |
Data is available to read by the calling process. No
additional messages will be posted until the client has read at
least some of the data. This event is only generated if the
client is in asynchronous mode. |
| WHOIS_EVENT_WRITE |
The client can now write data. This notification is sent
after a connection has been established, or after a previous
attempt to write data has failed because it would result in a
blocking operation. This event is only generated if the client is
in asynchronous mode. |
| WHOIS_EVENT_TIMEOUT |
The network operation has exceeded the specified timeout
period. The client application may attempt to retry the
operation, or may disconnect from the server and report an error
to the user. |
| WHOIS_EVENT_CANCEL |
The current operation has been canceled. Under most
circumstances the client should disconnect from the server and
re-connect if needed. After an operation has been canceled, the
server may abort the connection or refuse to accept further
commands from the client. |
- lpEventProc
- Specifies the procedure-instance address of the application
defined callback function. For more information about the callback
function, see the description of the WhoisEventProc callback
function. If this parameter is NULL, the callback for the specified
event is disabled.
- dwParam
- A user-defined integer value that is passed to the callback
function. If the application targets the x86 (32-bit) platform, this
parameter must be a 32-bit unsigned integer. If the application
targets the x64 (64-bit) platform, this parameter must be a 64-bit
unsigned integer.
Return Value
If the method succeeds, the return value is zero. If the method
fails, the return value is WHOIS_ERROR. To get extended error
information, call GetLastError.
Remarks
The RegisterEvent method associates a
callback function with a specific event. The event handler is an
WhoisEventProc function that is invoked when the event
occurs. Arguments are passed to the function to identify the client
session, the event type and the user-defined value specified when the
event handler is registered. If the event occurs because of an error
condition, the error code will be provided to the handler.
The callback function specified by the lpEventProc
parameter must be declared using the __stdcall
calling convention. This ensures the arguments passed to the event
handler are pushed on to the stack in the correct order. Failure to
use the correct calling convention will corrupt the stack and cause
the application to terminate abnormally.
The dwParam parameter is commonly used to identify the
class instance which is associated with the event that has occurred.
Applications will cast the this pointer to a
DWORD_PTR value when calling this function, and then the event handler
will cast it back to a pointer to the class instance. This gives the
handler access to the class member variables and methods.
Requirements
Minimum Desktop Platform: Windows 7 Service Pack 1
Minimum Server Platform: Windows Server 2008 R2 Service Pack 1
Header File: cstools11.h
Import Library: cswhov11.lib
See Also
DisableEvents,
EnableEvents,
FreezeEvents,
WhoisEventProc
|
|