| Event Name | Description |
|---|---|
| OnAccept | This event is generated when a remote host connects with the server. |
| OnCancel | This event is generated when a blocking operation is canceled. |
| OnConnect | This event is generated when a client 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 SocketWrench .NET 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 class instance 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 event arguments are packaged in a class derived from EventArgs, and passed to the caller along with an argument that specifies the instance of the class that generated the event. For more information about how to implement an event handler, refer to to the section on Event Handling in the Developer's Guide.
When developing your event handlers, it is important to remember that the underlying 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.
The OnAccept event is generated whenever a remote host (client) attempts to connect with your server application. The Blocking property must be set to false and the Listen method must be called to enable the socket to listen for client connections. An instance of the AcceptEventArgs class is passed to the event handler. The class has a public property named Handle which specifies the handle of the socket which is listening for connections. This value is passed to the Accept method in order to accept the connection, allowing the server to begin communicating with the client.
The OnCancel event is generated whenever a blocking operation has been canceled using the Cancel method. When this event fires, the class is about to return control to your application, and the blocked method will return with the error errorOperationCanceled. 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 method.
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 class is used to establish a non-blocking connection, the application must wait for this event to fire before attempting to perform any other functions.
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.
It is important to note that a failure to check for any remaining data in the socket receive buffers in the OnDisconnect event handler can result in unexpected data loss. It is recommended that you call the Read method until it returns a value of zero, which indicates that there is no more data available to be read. The IsReadable property can also be used to determine if there is any data available to be read.
The OnError event occurs whenever an error is reported by the class. An instance of the ErrorEventArgs class is passed to the event handler. The class has two public properties, Error and Description, which return the numeric error code and a human readable 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.
The OnProgress event occurs during blocking operations when the ReadStream, StoreStream and WriteStream methods are called, providing information to the application about the status of the data transfer. This event is typically used to update the user interface, such as setting the value of a progress bar control.
The OnRead event is a networking event which occurs whenever there is data available to be read from the socket. This event is only generated when the Blocking property is set to false. 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 one byte of data has been read by the application. This is by design, to prevent the application from being flooded with event messages.
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 class is about to return control to your application, and the blocked method will return with the error errorOperationTimeout. 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 method.
The OnWrite event is a networking event which occurs whenever the remote host is ready to receive more data from your application. This event is only generated under one of two circumstances, and only when the Blocking property is set to false. The first is when a connection has initially been established, the OnWrite event will occur immediately after the OnConnect event. The second case is when a previous call to the Write method failed with the error errorOperationWouldBlock, indicating that no more data could be written to the socket at that time because the send buffer was full.