Web Server Connections

Establishing a Connection

In order to access a resource on a web server, it is first necessary to establish a connection. This is done by calling the Connect method and checking the return value to make sure that the connection was successful. To establish that connection, certain information is required. This includes:

The host name or IP address of the server that you wish to connect to. This information may be specified by either setting the HostName property, or by passing the host name as an argument to the Connect method. For example, www.microsoft.com is a valid host name.
The port number of the server that you're connecting to. This can be specified by setting the RemotePort property or passing the port number as an argument to the Connect method. In most cases, the default port number should be used and it is not necessary to specify the port number in your application. However, for servers that are configured to use non-standard port numbers, that information must be provided. Setting the RemotePort property to a value of zero specifies that the default port number should be used.
If a secure, encrypted connection is required, then the Secure property should be set to True. A secure server is one that supports the SSL (Secure Sockets Layer) protocol, or its successor, the TLS (Transport Layer Security) protocol.

HTTP servers may only be accessible through a proxy server in certain circumstances. In that case, a set of properties related to proxies must be specified before connecting. Please see the Technical Reference for further details about the ProxyHost and ProxyPort properties, as well as other information pertaining to connecting through a proxy server.

To establish a connection using the HTTP control, you should call the Connect method and check the return value to ensure that the connection was successful. This can be done one of several ways, and which approach you use largely depends on personal preference and the structure of your program.

Method Arguments

You can call the Connect method with a number of different arguments, all of which are optional. The most common use would look like this:

Dim nError As Long

nError = HttpClient1.Connect(strHostName)
If nError > 0 Then
    MsgBox HttpClient1.LastErrorString, vbExclamation
    Exit Sub
End If

In this example, the strHostName string variable contains the name of the server to connect to. If the function returns a value other than zero, this indicates an error and a message box is used to display the error to the user. Note that if the resource requires authentication, then a username and password can also be passed to the method.

Property Values

Another method is to set the host name using the control's HostName property and then calling the Connect method without any arguments. Here is an example of how that could be done:

Dim nError As Long

HttpClient1.HostName = "www.microsoft.com"

nError = HttpClient1.Connect()
If nError > 0 Then
    MsgBox HttpClient1.LastErrorString, vbExclamation
    Exit Sub
End If

Note that the RemotePort property is not specified, which means that the default port number should be used. If authentication was required, the UserName and Password properties could be set as well. As with the previous example, if the connection fails then the method will return an error code and a message box is displayed to the user.

Uniform Resource Locators

Anyone who has used a web browser is familiar with the Uniform Resource Locator (URL); it is the value that is entered as the address of a website. URLs have a specific format which provides information about the server, the port number and the name of the resource that is being accessed:

http://[username : [password] @] remotehost [:remoteport] / resource [? parameters ]

The first part of the URL identifies the protocol, also known as the scheme, which will be used. With web servers, this will be either http or https for secure connections. If a username and password is required for authentication, then this will be included in the URL before the name of the server. Next, there is the name of the server to connect to, optionally followed by a port number. If no port number is given, then the default port for the protocol will be used. This is followed by the resource, which is usually a path to a file or script on the server. Parameters to the resource may also be specified, called the query string, which are typically used as arguments to a script that is executed on the server.

A third approach to establishing a connection is to specify a URL by setting the URL property and then calling the Connect method without any arguments. By setting the URL property, the control will automatically update the various related properties such as HostName and RemotePort. Here is an example of how this could be done:

Dim nError As Long

HttpClient1.URL = "http://www.microsoft.com/"

nError = HttpClient1.Connect()
If nError > 0 Then
    MsgBox HttpClient1.LastErrorString, vbExclamation
    Exit Sub
End If

If you prefer to use URLs, this approach provides the simplest means of establishing the connection. It should be noted that if the URL property is assigned an invalid value, then the control will throw an exception. If you are using URLs provided by a user, it is strongly recommended that you implement an error handler, otherwise your program may terminate if the user specifies an incorrect or incomplete URL.