Before getting started with using SocketWrench, there are some general concepts used throughout the documentation which are helpful to understand. If you are new to network programming, you are also encouraged to review the General Concepts section of the Developer's Guide which covers these topics in more detail.

Connections and Sessions

One of the first general concepts that you'll encounter when developing Internet applications is that most programs act as either a client or a server. In simplest terms, a server is a program which is designed to perform specific functions on behalf of another program. A client is a program which is designed to request information from a server and then present that information to a user. It is common for one server to be able to interact with many clients, with each client functioning independently of one another. The interaction between a client and server can be broken down into several discrete steps:

• The client program attempts to connect to the server
• The server program accepts the connection
• The client sends a request to the server to perform some function
• The server processes the request, returning information to the client
• The client receives the information from the server and processes it
• The client disconnects from the server

When a client wants to request information from a server, the first step that it needs to take is to establish a connection. This is someone analogous to calling someone up on the telephone. You pick up the telephone, dial a number and wait for the other person to answer the phone and begin the conversation. With SocketWrench, the Connect method is what is used to begin the process of establishing the connection with the server. The host name or address tells the control what server it should be connecting to, just as the telephone number is used to specify who you want to talk to. The Disconnect method disconnects the program from the server, and is similar to saying goodbye and hanging up the telephone.

This complete process, from establishing the connection to disconnecting from the server, is typically referred to as a session. During a single session, the client may send one request, or it may choose to send several requests before terminating the connection.

Consider a web server such as the one that hosts the Catalyst Development website. That server is responsible for providing clients with the HTML pages and other content that they request. The client could be any web browser, such as Internet Explorer. When you enter an address, such as http://www.catalyst.com, it instructs the web browser to request the index page for the website from the server. The server retrieves the contents of that page from a file on the server, and then sends it back to the client as data. The client receives that data, and then displays it to the user as a web page. That is an example of a client/server session.

Host Names and Ports

Part of establishing a connection with a server is knowing the name of the server to connect to, and the port number for the service it is providing. Host names are strings which can be used to identify a server, similar to how a telephone number is used to specify who it is that you want to call. Everyone who has used a web browser is familiar with host names, such as www.catalyst.com or ftp.microsoft.com. In addition to host names, you can also use Internet addresses which are a series of four numbers separated by periods. For example, 192.168.0.10 would be an Internet address, also referred to as an IP address. The SocketWrench class has two properties, HostName and HostAddress, which can be used to specify the name or address of a server. You can also specify the host name or address as an optional argument to the Connect method, if you prefer.

In addition to a host name or address, a client program also needs to know what port number it should use to establish the connection. You can think of port numbers like the extension for a telephone number. Just as an extension may be used to contact different employees using the same telephone number for a company, the port number may be used to connect to different services available on the same server. Port numbers are a way to distinguish between the different services available, and each protocol has a unique port number assigned to it. For example, a webserver uses port 80 to accept connections, while an FTP server uses port 21. The RemotePort property can be used to specify a port number, or the port number can be passed as an optional argument to the Connect method.

One important thing to keep in mind is that host names and URLs (Uniform Resource Locators) are not the same thing. For example, http://www.catalyst.com is not a valid host name. URLs include information about the protocol, the host name or address, the port number and the resource to access. When using the Connect method or setting the HostName property, make sure that you specify only the host name portion of the URL, such as www.catalyst.com.

Asynchronous Sessions

The SocketWrench .NET class has been designed to work in one of two basic modes of operation, establishing either a synchronous or asynchronous connection. The default mode of operation is synchronous, which is also referred to as a "blocking" connection. In this mode, it will wait for the requested operation to complete on the server or until the timeout period expires. For example, when the Connect method is called, SocketWrench will wait until the connection has completed before returning control to your program and the next statement is executed. The second mode, which is asynchronous or "non-blocking", causes the class to resume execution of your program immediately without waiting for the operation to complete. In that case, your program is notified through events that a particular operation has completed. For example, when the Connect method is called, it will immediately return and when the connection has completed, the OnConnect event will fire.

The class uses the Blocking property to determine if it should operate synchronously or asynchronously. In most cases, it is preferable to use the default mode, which is to establish a synchronous connection. Unless your application is written to specifically handle the various asynchronous network events, there can be unexpected results. For example, consider the following code:

[Visual Basic]
Dim Socket As New SocketTools.SocketWrench
Dim strBuffer As String

If Socket.Connect("www.catalyst.com", 80) Then
    ' Send the GET command to the web server, requesting the
    ' the index page for the site
    Socket.WriteLine("GET /")

    ' Read the response from the server and store it in a
    ' a string buffer
    If Socket.ReadStream(strBuffer, True) Then
        TextBox1.Text = strBuffer
    End If

    ' Disconnect from the server
    Socket.Disconnect()
Else
    ' The connection attempt has failed, display an error
    MsgBox(Socket.LastErrorString, MsgBoxStyle.Exclamation)
    Exit Sub
End If

In this example, SocketWrench being used to establish a connection to the www.catalyst.com webserver. If the connection is successful, then the program sends a command to the server requesting the index page for the site, reads the data returned by the server and displays it in a TextBox control. If the connection attempt fails, a message box is displayed and the subroutine is exited. This code is fairly straight-forward and would work as expected with a synchronous connection where the Blocking property is set to true. However, if an asynchronous connection was used then it is very likely this code would fail unexpectedly. Why? Because the Connect method returns immediately in asynchronous mode, without waiting for the connection to actually complete. In this case, the code following the Connect method would need to be changed and moved out of that code block and into the various event handlers such as OnConnect and OnRead.

When SocketWrench is in blocking mode, the Timeout property is used to determine the amount of time that the control should wait for the operation to complete. The default timeout period is 60 seconds, however this can be set lower or higher as needed. A timeout value of zero means that the class should wait indefinitely, except when establishing a connection. To cancel a blocking operation and resume execution of the program, use the Cancel method.

In general, unless you have a specific need to use SocketWrench in asynchronous mode, we recommend that you use blocking connections. Asynchronous sessions are more complex to code for, have a greater tendency to introduce errors into the logical flow of a program and can be more difficult to debug. If you wish to perform multiple network operations at the same time, it is much more preferable to create multiple threads rather than attempt to manage multiple asynchronous sessions in a single thread. In addition, there is additional overhead imposed when using asynchronous sessions due to the event handling mechanism.

It should also be noted that certain high-level methods will always cause the class to block during execution, regardless of what mode it is in. An example of this is the ReadStream method, which reads an arbitrarily large stream of bytes from the remote host and stores it in a string or byte array buffer. When using SocketWrench in asynchronous mode, you need to make sure that you only use the lower-level methods such as Read and Write, and do not attempt to perform a blocking socket operation inside an asynchronous event handler.

---