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 reading a stream of bytes from the socket and storing it in a file. Note that asynchronous network events require that the Blocking property be set to false. The following events can be generated when SocketTools is in non-blocking mode:
OnConnect
This event is generated whenever a connection to a remote host has completed. Unlike a blocking connection, when the component 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.
OnDisconnect
This event is generated whenever the remote host 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 remote host closes its connection to you. It is also important to keep in mind that although the remote host 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.
OnRead
This event is generated whenever the remote host sends data to your application. Once this event has fired, it will not be triggered again until you read at least one byte of data that has been sent to you. It is recommended that you attempt to read and buffer all of the data that is available to be read in the socket. When the Read method returns a value less than or equal to zero, you should exit the event handler.
OnWrite
This event is generated whenever there is enough memory available in the local send buffers to accommodate some data. It is generated immediately after a connection has completed, which tells your application that it may begin sending data to the remote host. It will also be generated if a call to the Write method fails with the error that it would cause the thread to block. In this case, when the socket is able to accept 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 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 OnRead event will not be generated until you read at least one byte 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 downloading a file from the server using the GetFile method. The possible status events are:
OnCancel
This event is used by the class to indicate that a blocking network operation has been canceled by a call to the Cancel method. It is important to note that when the Cancel method is called, the blocking socket operation will not immediately fail. An internal flag is set which causes the blocking operation to exit with an error. This means that the application cannot cancel an operation and immediately perform some other blocking function. Instead it must allow the calling stack to unwind, returning back to the blocking operation before making any further function calls. The OnCancel event handler should only be used for notification purposes or updating the internal state of the application. It is not recommended that you perform any network operations inside this event handler.
OnError
This event is used by the class 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. The OnError event handler should only be used for notification purposes or updating the internal state of the application. It is not recommended that you perform any network operations inside this event handler.
OnProgress
This event is used by the class to inform the application of the progress of a blocking operation, such as a file transfer. Note that in some cases, the class may not be able to determine the total amount of data to be transferred, which would prevent a percentage from being calculated. In this case, because the server is unable to specify the total size of the resource, the class 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.
OnTimeout
This event is used by the class to indicate a blocking operation has timed-out. A timeout period is specified by setting the Timeout property to a value greater than zero. The OnTimeout event handler should only be used for notification purposes or updating the internal state of the application. It is not recommended that you perform any network operations inside this event handler.
Status 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 message may be displayed if an OnError event occurs.