Downloading Resources

A web resource is a general term that applies to any document, image or other file which can be accessed through a web server. It also refers to applets or scripts which can be downloaded and executed on the client, or programs which are executed on the server and return data to the client.

The SocketTools HTTP control provides several methods which makes it easy to access a resource on a web server, and either store that resource in memory or as a file on the local system. For the first example, consider a program which requests some data from a server and stores the response in a string:

Dim strDocument As String
Dim nLength As Long
Dim nError As Long

HttpClient1.URL = "http://api.sockettools.com/test"

nError = HttpClient1.Connect()
If nError = 0 Then
    nError = HttpClient1.GetData(HttpClient1.Resource, strDocument, nLength)
    HttpClient1.Disconnect
End If

In this example, the URL property is assigned to the complete URL of the resource to retrieve and then the Connect method is called without any arguments. This tells the control that you want to use the information specified in the URL rather than explicitly specify the host name, port number and so on. If the Connect method returns zero, then that means no error has occurred, so the next step is to call the GetData method.

The first argument to the GetData method is the resource portion of the URL, which is returned by the Resource property. The second argument is the string buffer that will contain the data when the method returns. The GetData also supports two more arguments. An optional third argument is a variable which will contain the amount of data copied into the string buffer. It is not required that you specify this argument, and is included primarily as a convenience.

The optional fourth argument is a numeric value which determines if text resources should be automatically converted to use the standard Windows conventions for text files. This can be important because the default behavior for the control is to return the resource data exactly as it is sent by the server. For text-based resources like HTML documents, this can present a problem if the document on the server uses a different convention to indicate the end-of-line. On UNIX based servers, the end-of-line character is a single linefeed, while on Windows based systems, the end-of-line is a carriage-return and linefeed pair. Rather than writing code to go through the data and perform that conversion if necessary, you can tell the GetData method that you want it to automatically convert any text resources. For example:

nError = HttpClient1.GetData(HttpClient1.Resource, strDocument, _
                             nLength, httpTransferConvert)

In this case, if the resource is a text document, then it will automatically convert the data to use the Windows conventions for text files if necessary. It is important to note that if the resource is not a text file (for example, an image file) then this option does nothing. That being the case, why not perform the conversion as the default? The reason is that many web servers are configured to treat resources which don't have a known MIME content type as text by default. For example, consider a resource like "/files/record.dat" where there isn't a standard MIME type for a file with a .dat extension. In this case, many web servers will incorrectly tell the client that the resource is text, even if that file actually contains non-text data. If the GetData method automatically performed this conversion, then it could potentially corrupt the data. By making the conversion an explicit option, it allows you to tell the control that you know the resource you're requesting is textual and should be converted. Otherwise, it simply provides you with the data exactly as it was returned by the server.

If you want to store the resource on the local system rather than in a buffer in memory, then you can use the GetFile method instead of GetData. The code would be virtually identical except for the different method call:

Dim nError As Long

HttpClient1.URL = "http://sockettools.com/"

nError = HttpClient1.Connect()
If nError = 0 Then
    nError = HttpClient1.GetFile(strFileName, HttpClient1.Resource)
    HttpClient1.Disconnect
End If

The GetFile method requires two arguments, the name of the file to create or overwrite on the local system and the resource to retrieve from the server. There is also an optional third argument which allows you to specify if text resources should be automatically converted, just as with the GetData method.

If you would like to provide some visual feedback to your user with the status of the resource being downloaded, you can implement an event handler for the OnProgress event. For example, if you had a standard ProgressBar control on the form, you could simply write code such as this:

Private Sub HttpClient1_OnProgress(ByVal BytesTotal As Variant, _
                                   ByVal BytesCopied As Variant, _
                                   ByVal Percent As Variant)
    ProgressBar1.Value = Percent
End Sub

As the resource is being retrieved using either the GetData or GetFile methods, the OnProgress event will be periodically fired. In this case, the ProgressBar control is updated using the percentage of the transfer that has completed.