|
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 blocking network operation |
| Command |
Send a custom command to the server |
| Connect |
Establish a connection with a server |
| Disconnect |
Terminate the connection with a server |
| Initialize |
Initialize the control and validate the runtime license
key |
| Read |
Return data read from the server |
| Reset |
Reset the internal state of the control |
| Uninitialize |
Uninitialize the control and release any system resources
allocated for the session |
| Write |
Write data to the server |
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
server, 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.
|