Common Events

Many of the SocketTools components share a common set of events, each with the same general functionality. It is important to note that although events may share the same name, the number and type of arguments may vary from control to control. Be sure to review the Technical Reference documentation for the specific control that you are using.

Event Name Description

OnCancel This event is generated when a blocking operation is canceled

OnCommand This event is generated when the server processes a command issued by the client

OnConnect This event is generated when a connection is established

OnDisconnect This event is generated when a connection is terminated

OnError This event is generated when a control error occurs

OnProgress This event is generated during data transfer

OnRead This event is generated when data is available to be read

OnTimeout This event is generated when a blocking operation times out

OnWrite This event is generated when data can be written to the server

The events generated by the SocketTools controls can be divided into two general categories, asynchronous network events and status notification events. Events such as OnConnect and OnRead are examples of network events which are generated when the control is placed in non-blocking mode. Events such as OnError and OnProgress are examples of notification events which are designed to provide additional status information to your application.

All events have their arguments passed by value as variants. For languages such as Visual Basic, this does not require any special consideration when implementing an event handler. For other languages, you may need to convert the variant into the appropriate data type for your application. For example, in Visual C++ this can be done using the standard macros included in oleauto.h or using a class such as CComVariant. For more information about how to implement an event handler in C++, refer to to the section on Control Event Handling in the Developer's Guide.

When developing your event handlers, it is important to remember that the event mechanism uses Windows messages and requires that the application process those messages. That means that events may not fire correctly if the application is executing code in a tight loop and no messages are being dispatched. Another consideration is that some functions can interfere with the normal operation of events. For example, the MsgBox function in Visual Basic will force event handling to be suspended until the user closes the message box. Single stepping through code in the debugger can also prevent events from being processed normally. To debug code in an event handler, it is recommend that you use methods such as writing diagnostic messages to the immediate (debugging) window or a log file rather than more intrusive measures such as displaying a message box.

OnCancel

The OnCancel event is generated whenever a blocking operation has been canceled using the Cancel method. When this event fires, the component is about to return control to your application, and the blocked method will return with the error stErrorOperationCanceled. It is important to note that you should not perform another blocking operation while inside the event handler. Instead, allow the stack to unwind and return control to the calling function.

OnCommand

The OnCommand event is generated whenever the server has processed a command issued by the client. The event handler is passed two arguments, the numeric result code and a string describing the result of the command. These values correspond to the ResultCode and ResultString properties. This event is typically used by applications to record the responses from a server, either as information for the user or for debugging purposes.

OnConnect

The OnConnect event is a networking event that indicates that the connection request has completed and the client has successfully established a connection with the remote host. This event is only generated when the Blocking property is set to False. If the control is used to establish a non-blocking connection, the application must wait for this event to fire before attempting to perform any other functions.

OnDisconnect

The OnDisconnect event is a networking event that indicates that the remote host has closed its connection to the client. When this event occurs, your program should attempt to read any remaining data and then call the Disconnect method to close its connection to the server. This event is only generated when the Blocking property is set to False.

OnError

The OnError event occurs whenever an error is reported by the control. The event handler is passed two arguments, the numeric error code and a description of the error. These values correspond to the LastError and LastErrorString properties. This event is typically used by applications to record any errors that occur, either as information for the user or for debugging purposes.

OnProgress

The OnProgress event occurs during blocking operations, providing information to the application about the status of the transaction. For example, this event is called periodically during a file transfer so that the program knows how much of the file has been uploaded or downloaded. This event is typically used to update the user interface, such as setting the value of a progress bar control.

OnRead

The OnRead event is a networking event which occurs whenever there is data available to be read. This event is only generated when the Blocking property is set to False and a lower-level method is called which requires the application to read data directly from the server. An important consideration when handling the OnRead event is that this event is level-triggered. This means that the event will only fire once, and will not fire again even if more data arrives, until at least some of the data has been read by the application. This is by design, to prevent the application from being flooded with event messages.

OnTimeout

The OnTimeout event is generated whenever a blocking operation has exceeded the amount of time specified by the Timeout property. When this event fires, the component is about to return control to your application, and the blocked method will return with the error stErrorOperationTimeout. It is important to note that you should not perform another blocking operation while inside the event handler. Instead, allow the stack to unwind and return control to the calling function.

OnWrite

The OnWrite event is a networking event which occurs whenever the server is able to receive more data from the application. This event is only generated when the Blocking property is set to False and a previous call to the Write method failed with the error stErrorOperationWouldBlock.