|
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 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 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 remote host
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 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 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 remote host. 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 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 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 remote host. 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.
|