In SocketTools, event notification provides a mechanism for the library to inform the application of a change in the status of the current session. Events are generally divided into two general categories, asynchronous network events and status events.

Asynchronous network events occur when a non-blocking connection is established and a network event occurs, such as a connection completing or data arriving from the remote host. Status events are used to indicate a change in status, such as a blocking operation being canceled or the progress of an operation such as a file transfer.

Asynchronous network events require that the program provide a handle to a window that will receive the event message and a user-defined message identifier that will be used to identify the event to the application. Typically the window is an invisible window created specifically for the purpose of processing events, however it can also be a visible window used by the application such as a form or dialog. If the window handle refers to a visible window, it is important to remember that if the window is destroyed, asynchronous event notification will automatically be disabled. In general it is recommended that the application use a private, invisible window if asynchronous network events are required. To enable event handling, each of the networking libraries has a function named EnableEvents which accepts a handle to a window and a unique message identified. There is also a DisableEvents function which will disable event handling. For example, the Hypertext Transfer Protocol library has functions called HttpEnableEvents and HttpDisableEvents. Note that if you initially establish an asynchronous connection, it is not necessary to explicitly call the EnableEvents function for the library since you will already have a non-blocking connection and events will be posted to the specified window.

In addition to posting event notifications to a window, it is also possible to register a callback function that will be called by the library whenever the event occurs. In this case, you would use the RegisterEvent function for the library, where you would specify the event that you wish to register, along with a user-defined parameter that will be passed to the callback function.

In some cases, it is desirable to suspend event handling for a session. To accomplish this, the libraries have a function called FreezeEvents which can be used to suspend and resume event handling. While events are frozen, network events will be queued rather than posted to the notification window. When event handling is resumed, those events will be fired and event handling will resume normally. It is recommended that applications freeze event handling when they are performing some action where it would not be desirable for the event handler to be executed. Examples of where this would be appropriate would be a modal dialog or a message box, where the user must respond before the application continues executing.

An important consideration when it comes to event handling is that all asynchronous network events are level triggered. This means that once an event is fired, it will not be fired again until some action is taken by the application to handle the event. This is most commonly found with "read" events, which are generated when the remote host sends data to your application, signaling to you that there is data available to be read. Even though the remote host may continue sending you more data, another read event will not be generated until you read at least some of the data that has been sent to you. This is done to prevent the application from being flooded with event notifications. However, failure to handle an event can cause event notification to appear to stall. If you determine that you cannot handle an event at the time, you must freeze event handling. You can resume event notification when you are in a position to process events again.

Copyright © 2008 Catalyst Development Corporation. All rights reserved.