| Method Name | Description |
|---|---|
| Accept | Accept a client connection. This is used by server applications. |
| Cancel | Cancels the current blocking socket operation. |
| Connect | Establish a connection with a remote host This is used by client applications. |
| Disconnect | Terminate the connection with the remote host. |
| Initialize | Initialize the class and load the networking interface. |
| Listen | Listen for client connections. This is used by server applications. |
| Read | Read a block of data from the remote host and return it in a string or byte array. |
| ReadLine | Read a line of text from the remote host and return it in a string. |
| Reset | Reset the internal state of the class and terminate any active connections. |
| Uninitialize | Uninitialize the class and release resources allocated for the class instance. |
| Write | Send a block of data to the remote host. |
| WriteLine | Send a line of text to the remote host, terminated with a newline. |
Most methods will return a value of true if they are successful, or a value of false if the method fails for some reason. The error code which specifies the cause of the failure is returned by the LastError property. A human readable 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.
Many of the SocketWrench .NET class methods are similar to those used by the ActiveX control, however the return values have changed in some cases. It is recommended that you review the Technical Reference material for specific information about a particular method.
Note that the way that a method indicates an error condition is affected by the ThrowError property. This allows errors to be handled in one of two ways, depending on the personal preferences of the developer and requirements of the application. If the property is set to true, then methods will throw an exception when an error occurs and it is the responsibility of the application to implement an exception handler. If the property is set to false, then the method will not throw an exception and will simply return a value indicating success or failure. The default value for the property is false.
The Accept method is used by server applications to accept an incoming client connection. After the connection has been accepted, the server may begin to send and receive data on the socket. Typically a new instance of the SocketWrench class is created for each client connection and the handle of the listening server socket is passed as an argument to the Accept method. This allows the server to continue to listen for new connection requests, and the new instance of the class becomes responsible for exchanging data with the client.
The Cancel method cancels the current blocking operation being performed by the class. 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 errorOperationCanceled. 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 Connect method is used to establish a connection with a remote host, and is typically one of the first methods called by the program. There are several overloaded implementations of this method. If no arguments are specified, then the method will use the values of the HostName or HostAddress and RemotePort properties as the default. If the Blocking property is set to true, then the method will return after the connection has been established, or after the timeout period has been exceeded. If the Blocking property is set to false, the method will return immediately and the application must wait for either the OnConnect or OnError event to fire before performing any other operation on the socket.
The Disconnect method terminates the current connection and releases some of the resources allocated by the class 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 class, loading the appropriate networking interface, validating the runtime license key and performing other internal initialization functions. 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 that instance of the class 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 Class Initialization section of the Developer's Guide.
The Listen method is used by server applications to create a socket that will "listen" for incoming client connections. The server would then call the Accept method to accept the connection and begin communicating with the client. If the Blocking property is set to false, the OnAccept event will occur whenever a client attempts to connect with the server.
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. The first argument passed to the method should be a string or byte array which will contain the data that has been read when the method returns. The second argument should be an integer which specifies the amount of data to read, in bytes.
The Read method is different from most other methods in two important ways. Instead of returning true or false, the method returns the number of bytes read. 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.NET, 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. For example, C# requires the use of the ref keyword to pass a variable by reference.
The ReadLine method is used to read a line of text from the socket, up to a terminating carriage return and linefeed sequence. This is similar to reading a line of text from a file, and the method will return false when there is no more data to read or an error has occurred. It is important to keep in mind that this method should only be used with textual data, and it can force the thread to block (even if the Blocking property is set to false) while it buffers data up to the end of line. It is recommended that this method only be used with synchronous socket connections.
The Reset method will reset the internal state of the class instance to its defaults, terminating any connection to a remote host and releasing resources allocated for the session. This method should only be used when the program needs to effectively abort any active connections 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 interface and release those resources which have been allocated by the class. In most cases, it is not necessary to explicitly uninitialize the class because this is handled automatically by the class destructor.
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 different from most other methods because instead of returning true or false, 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.
The WriteLine method is used to send a line of text to the server, terminated with a carriage return and linefeed. This is similar to writing a line of text to a file, and the method will return false if no data can be written to the socket. As with the ReadLine method, this method should only be used with textual data and it can force the thread to block while the data is being written (even if the Blocking property is set to false). It is recommended that this method only be used with synchronous socket connections.