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.
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.
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.
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 server. 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.
The OnDisconnect event is a networking event that indicates
that the server 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.
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.
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.
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.
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.
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.
|