|
Many of the SocketTools components share a common set of
methods, each with the same general functionality. It is important
to note that although methods 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.
| Method Name |
Description |
| Cancel
|
Cancels the
current operation |
| Command
|
Send a custom
command to the remote host |
| Connect
|
Establish a
connection with a remote server |
| Disconnect
|
Terminate the
connection with a remote server |
| Initialize
|
Initialize the
control and load the Windows Sockets library |
| Read
|
Return data read
from the remote host |
| Reset
|
Reset the internal
state of the control |
| Uninitialize
|
Uninitialize the
control and unload the Windows Sockets library |
| Write
|
Write data to the
remote host |
All methods expect that the arguments passed to them will be
variants, and the argument will be converted to the appropriate
type by the method. This allows the controls to be easily used by
weakly typed languages, and is generally transparent to the caller
in languages such as Visual Basic. However, in languages such as
Visual C++, you should either use VARIANT types or related classes
such as CComVariant when passing arguments to a method. In most
cases, the arguments should be passed by value to the method,
however there are exceptions where a method returns data to the
caller in one or more arguments. In this case, the caller must pass
the argument by reference. Again, languages such as Visual Basic
will handle this for you transparently. However, some languages
such as FoxPro or PowerBuilder require that you use special syntax
when passing an argument by reference. Refer to the documentation
for your programming language if you have any questions on how to
pass an argument by reference to a method.
Most methods will return a value of zero if they are successful,
or an error code value if the method fails for some reason. This
error code will match the value of the LastError property,
and a description of the error can be obtained by getting the value
of the LastErrorString property. There are some exceptions
to this rule, such as the Read and Write methods which return the
number of bytes read or written, and a value of -1 if there was an
error. These exceptions are noted in the Technical Reference
section for each control.
The Cancel method cancels the current blocking operation
being performed by the control. For example, if the Connect
method has been called, the Cancel method will cancel the
connection attempt. When this happens, the OnCancel event
will fire and the blocking method will return with the error
stErrorOperationCanceled. Once an operation has been canceled, it
is important to allow the application to unwind the stack and
resume execution at the point where the blocking method returns.
For example, you should not call the Cancel method and then
perform another blocking operation in any event handler until after
the blocking method returns.
The Command method is used to send custom commands to the
server, specific to the protocol being used. This provides the
program with a very low level of access to the application
protocol. Typically it is used to take advantage of non-standard
extensions to the protocol or server-specific commands. After
calling the Command method, the program should check the
value of the ResultCode and ResultString properties to determine if
the command was successful or an error occurred.
The Connect method is used to establish a connection with
a remote host, and is typically one of the first methods called by
the program. The method accepts one or more optional arguments,
such as the host name or IP address of the server, the port number,
and in some cases a user name and password. If no arguments are
specified, then the method will use the values of the HostName or
HostAddress, RemotePort, UserName and Password properties as the
default. If the control is in blocking mode, then the method will
return after the connection has been established, or after the
timeout period has been exceeded. If the control is in non-blocking
mode, the method will return immediately and the application must
wait for either the OnConnect or OnError events to
fire.
The Disconnect method terminates the current connection
and releases some of the resources allocated by the control for the
network connection. For every call to the Connect method,
there should be a matching call made to the Disconnect
method when the connection is no longer needed.
The Initialize method explicitly initializes the control,
loading the appropriate networking libraries, validating the
runtime license key and performing other internal initialization
functions. If the control is placed on a form or dialog, then it is
not normally required that a program call this method because the
container (form) will automatically initialize the control for you.
However, if the control is created dynamically using CreateObject
or created using a reference, then your program must call the
Initialize method before setting any properties or calling
any other method. For each call to the Initialize method,
there should be a matching call made to the Uninitialize
method when the control is no longer being used.
If the Initialize method is called without specifying a
valid runtime key, then the program will only execute on a system
that has a valid development license. To redistribute your
application, you must purchase a license and provide a valid
runtime key. For more information, refer to the Control Initialization
section of the Developer's Guide.
The Read method is used to read data returned by the
server in response to a command sent by the client. The type of
data returned depends on the protocol being used and the command
issued to the server. The first argument passed to the method
should be a string or byte array which will contain the data that
has been read. The second argument should be an integer which
specifies the amount of data to read, in bytes. The Read
method is typically only used in conjunction with those methods
which provide lower-level access to the application protocol.
The Read method is different from most other methods in
two important ways. Instead of returning zero or an error code, the
method returns the number of bytes read. If an error occurs, then
the method will return -1. If an error occurs, then the method will
return -1. To determine the cause of the error, check the value of
the LastError property. If there is no more data to be read
and the server has closed its connection to your program, then the
method will return 0.
In addition, the variable which will contain the data must be
passed by reference to the method. In languages like Visual Basic,
this is automatically handled for you. However, other languages may
require you to use a special syntax to indicate that the variable
should be passed by reference rather than by value. Consult the
documentation for your programming language if you have any
questions about how to do this.
The Reset method will reset the internal state of the
control to its defaults, terminating any connection to the server
and releasing resources allocated for the client session. This
method should only be used when the program needs to effectively
abort any connection and return to a known state. In most cases, it
is preferable for the application to use the Disconnect
method to cleanly terminate the session.
The Uninitialize method is used to unload the networking
library and release those resources which have been allocated by
the control. In most cases, it is not necessary to explicitly
uninitialize the control because this is handled automatically when
the control is unloaded from the form or the application
terminates. For each call to the Initialize method, there
should be a matching call made to the Uninitialize method
when the control is no longer being used.
The Write method is used to send data to the server. The
first argument passed to the method should be a string or byte
array which will contain the data to be written. The second
argument should be an integer which specifies the number of bytes
of data in the string or byte array. The Write method is
typically only used in conjunction with those methods which provide
lower-level access to the application protocol.
The Write method is different from most other methods
because instead of returning zero or an error code, the method
returns the number of bytes written. If an error occurs, then the
method will return -1. To determine the cause of the error, check
the value of the LastError property.
|