|
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:
OnConnect
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.
OnDisconnect
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.
OnRead
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.
OnWrite
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:
OnCommand
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.
OnError
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.
OnProgress
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.
|