Event Handling  

In SocketTools, event notification provides a mechanism for the component 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 server. 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 Blocking property for the control be set to False. This will set the control into a non-blocking mode. All of the networking controls share the same common set of events and all function in a similar way. These events are:


This event is generated whenever a connection to a server has completed. Unlike a blocking connection, when the control is in non-blocking mode, a successful call to the Connect method does not indicate that you are actually connected to the host. Instead, it means that the connection process has been started. Your application will not actually be connected until the OnConnect event fires.


This event is generated whenever the server closes its socket and terminates the connection with your application. Note that this event will not fire when you disconnect from the host by calling the Disconnect method; it only fires when the server closes its connection to you. It is also important to keep in mind that although the server has disconnected from you, there still may be data buffered on your local system, waiting to be read. If you are performing any low-level network I/O, your program should continue to call the Read method until it returns a value of zero, indicating that all of the available data has been read.


This event is generated whenever the server sends data to your application. Once this event has fired, it will not be triggered again until you read at least some of the data that has been sent to you. It is not recommended that any complex operations be performed in the OnError event handler. Applications should update any state variables or user interface objects and exit the handler immediately. Performing another operation using the control in an OnError handler can potentially result in the event handler being called recursively.


This event is generated whenever there is enough memory available in the local send buffers to accommodate some data. It is generated after a connection has completed, which tells your application that it may begin sending data to the server. It will also be generated if a call to the Write method fails with the error that it would cause the application to block. In this case, when the socket is able to send more data, the OnWrite event will fire.

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 OnRead events, which are generated when the server sends data to your application, signaling to you that there is data available to be read. Even though the server may continue sending you more data, another OnRead 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. It is recommended that you do not do excessive processing in an event handler that would cause the thread to block or enter a message loop. This can have a significant negative effect on performance and can lead to unexpected behavior on the part of your application. Instead, it's recommended that you buffer the data that you receive and then process that data after exiting the event handler.

Status related events are different because they do not depend on the value of the Blocking property, and are not directly related to asynchronous network operations. The most typical status event is the OnProgress event, which is used to provide information to the application about the status of a blocking operation, such as file transfer using the File Transfer Protocol control. The most common status events are:


This event is used by the control to inform the application of the status of a command sent to the server. It applies to those protocols which use explicit commands to initiate actions. Examples would be the File Transfer Protocol (FTP) control, Hypertext Transfer Protocol (HTTP) control and Internet Message Access Protocol (IMAP) control. Note that the actual result codes returned by the servers depend on the specific protocol, and can also vary among various server implementations.


This event is used by the control to indicate an error has occurred. This event is only generated when a method is called, never as the result of setting a property value.


This event is used by the control to inform the application of the progress of a blocking operation, such as a file transfer. Note that in some cases, the control may not be able to determine the total amount of data to be transferred, which would prevent a percentage from being calculated. For example, this can occur using the Hypertext Transfer Protocol (HTTP) control if the resource being downloaded is created dynamically on the server, such as an ASP page. In this case, because the server is unable to specify the total size of the resource, the control will not be able to calculate a percentage. Instead, it will simply inform the program of the amount of data copied to the local host up to that point.

These events are typically used to update a user interface. For example, the OnProgress event may be used to update a ProgressBar control, or a warning dialog may be displayed if an OnError event occurs.