Quick Start Concepts

Before getting started with using the controls, there are some general concepts used throughout the documentation which the developer should 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. In SocketTools, 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 control's 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 SocketTools website. That server is responsible for providing clients with the web pages and other content that they request. The client could be any browser, such as Microsoft Edge or Google Chrome. When you enter an address, such as http://sockettools.com, it instructs the browser to request the index page for the website from the server. The server retrieves the contents of that page and sends it back to the client as data. The client receives that data and displays it to the user. This 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 sockettools.com or 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 SocketTools controls have 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 web server uses port 80 to accept connections, while an FTP server uses port 21. In most cases, it is not necessary to explicitly specify a port number because the SocketTools components will automatically select the correct port number for the protocol being used. However, in some cases servers are configured to use non-standard port numbers. 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://sockettools.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 sockettools.com. Note that the File Transfer Protocol (FTP) and Hypertext Transfer Protocol (HTTP) controls do provide a URL property which can be assigned a URL string and the control will automatically parse the URL and set the corresponding HostName and RemotePort properties to their correct values. Refer to the Technical Reference for more information.

Asynchronous Sessions

The SocketTools controls have 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, the control 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, the control 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 control 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 control 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:

Dim nError As Long

nError = FtpClient1.Connect("ftp.microsoft.com")
If nError = 0 Then
    nError = FtpClient1.Login()
End If

If nError > 0 Then
    MsgBox FtpClient1.LastErrorString, vbExclamation
    Exit Sub
End If

In this example, the FTP control is being used to establish a connection to ftp.microsoft.com. If no error is returned, then the program attempts to login the user. If an error does occur, 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 the control was set to use an asynchronous connection 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 Login method would need to be moved out of that code block and into the OnConnect event handler.

When the control 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 in most cases is 20 seconds, however this can be set lower or higher as needed. 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 the control in asynchronous mode, we recommend that you always 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. For languages such as Visual C++ and Visual Basic.NET which support multithreading, it is 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 control to block during execution, regardless of what mode the control is using. An example of this is the GetFile method in the FTP and HTTP controls, which downloads a file from the server to the local system. To use the control in asynchronous mode, you are limited to using the lower-level methods such as OpenFile.