|
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, network events and status events. It is important to
note that it is not required that applications implement handlers
for any of the events generated by the scripting components. In
scripting environments where there is no user interface, event
handlers are not needed at all. In environments like the Windows
Scripting Host, their use is completely optional, depending on the
needs of the program and the preference of the developer.
Network events occur when a network operation, such as
establishing a connection to a server, has completed. There are two
general networking events which can be generated by the scripting
components:
OnConnect
This event is generated whenever a connection to a remote host
has completed. This can be used by an application to update its
user interface or perform some other operation when the component
has been connected. It is not recommended that you perform any
complex operations in the OnConnect method, and simply use it to
update any state variables or user interface objects in your
program. If you have an OnConnect event handler implemented, when
that event handler exits the Connect method will return and
execution of your program will resume at that point.
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.
Status related events are different because they are not
directly related to networking operations, instead they provide
information about the current status of the component. The most
typical status event is the OnProgress event, which is used to
provide information to the application about the progress of the
current operation, such as file transfer using the File Transfer
Protocol component. The most common status events are:
OnCancel
This event is generated whenever the Cancel method for the
component is called, which is used to terminate the current
operation. For example, if the File Transfer Protocol component is
being used to download a file, the Cancel method will abort the
transfer. The OnCancel event will be generated, and when the event
handler exits, the method will return with an error code indicating
that the transfer was canceled. Note that because this indicates an
error condition, both the OnCancel event will be generated,
followed by the OnError event.
OnCommand
This event is used by the component 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) component,
Hypertext Transfer Protocol (HTTP) component and Internet Message
Access Protocol (IMAP) component. 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 component 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. Two arguments are
passed to the OnError event handler, a numeric error code and a
description of the error which can be displayed to a user. 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 component in an
OnError handler can potentially result in the event handler being
called recursively.
OnProgress
This event is used by the component to inform the application of
the progress of the current operation, such as a file transfer.
Note that in some cases, the component 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) component 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 component will not be able to
calculate a percentage. Instead, it will simply inform the program
of the amount of data copied up to that point.
OnTimeout
This event is generated whenever the current operation times out
waiting for a response from the remote host. The amount of time
that the component will wait is controlled by the Timeout property,
and in most cases the default timeout period is sixty seconds. When
an operation times out, the OnTimeout event will be generated, and
when the event handler exits, the method will return with an error
code indicating that the operation timed out. As with the OnCancel
event, because this event indicates an error condifition, both the
OnTimeout event will be generated, followed by the OnError
event.
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.
|