The Hypertext Transfer Protocol (HTTP) is the most prevalent application protocol used on the Internet today. It was originally used for document retrieval, and has grown into a complex protocol which supports file uploading, script execution, file management and distributed web authoring through extensions such as WebDAV. The SocketTools Hypertext Transfer Protocol control implements version 0.9, 1.0 and 1.1 of the protocol, including features such as support for proxy servers, persistent connections, user-defined header fields and chunked data.
File Transfers
Similar to the interface used with the File Transfer Protocol
control, you can use HTTP to upload and download files. In addition
to the standard method for downloading files, the control supports
two methods for uploading files, using either the PUT or the POST
command. When downloading a file from the server, you can either
store the contents in a local file, or you can copy the data into a
memory buffer that you allocate. Similarly, when uploading files,
you can either specify a local file to upload, or you can provide a
memory buffer that contains the file data to send to the server.
High level methods such as PutFile and GetFile can be used to
transfer files in a single method call. There are also methods such
as OpenFile and CreateFile which provide lower level file I/O
interfaces.
Script Execution
Another common use for HTTP is to execute scripts on the web
server. The application can pass additional data to the script,
which is similar in concept to how arguments are passed to a
command that is entered from the command prompt. This uses the
standard POST command, and the resulting output from the script is
returned back to the application where it can be displayed or
processed. An application can use the Command method to execute the
script and then process the output in code, or can use the higher
level method PostData which will execute the script and return the
output from that script in a single method call.
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 remote host, 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 is to 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 remote host. Next, there is the name of the remote host 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.
Understanding how a URL is constructed will help in understanding how the different methods in the control work together. For example, the remote host name and port number portion of the URL are the values passed to the Connect method to establish the connection. The user name and password values are assigned to the UserName and Password properties to authenticate the client session. And the resource name is passed to the GetData or GetFile methods to transfer it to the local system.
Initialize
Initialize an instance of the class, loading the networking library
and validating the development license. This method must be called
before any properties are changed or any other methods in this
class are called by the application.
Connect
Connect to the remote host, using either a host name or IP address.
This method creates the client session and must be called before
your application attempts to request a resource from the
server.
Disconnect
Disconnect from the server and release the memory allocated for
that client session. After this method is called, the client
session is no longer valid.
Reset
Reset the internal state of the component. This can be useful if
your application wishes to discard any settings made by a user and
return that instance of the class to its default state.
Uninitialize
Unload the networking library and release any resources that have
been allocated for the current process. This is the last method
call that the application should make prior to terminating. This is
only necessary if the application has previously called the
Initialize method.
Using an interface similar to the File Transfer Protocol control, this control provides several methods which can be used to transfer files between the local and remote host. This group of methods is high level, meaning that it is not necessary to actually write the code to read and/or write the file data. The control automatically handles the lower level file I/O and notifies your application of the status of the transfer by periodically generating progress events.
GetData
This method transfers a file from the remote host to the local
system, storing the file data in memory. This can be useful if your
application needs to perform some operation based on the contents
of the file, but does not need to store the file locally.
GetFile
This method transfers a file from the remote host and stores it in
a file on the local system.
PutData
This method creates a file on the remote host containing the data
that you provide. This can be useful if your application wants to
upload dynamically created content without having to create a
temporary file on the local system.
PutFile
This method uploads a file from the local system to the remote host
using the PUT command. Not all servers support this command, and
some may require that the client authenticate prior to calling this
method.
PostFile
This method uploads a file from the local system to the remote host
using the POST command. This enables your application to upload a
file in the same way that a user would when using a form in a web
browser.
The control can also perform some basic file management methods as well as send custom commands to the server. Some web servers also provide more advanced document management methods using WebDAV, an extension to HTTP for distributed document authoring.
GetFileSize
Return the size of a file on the server without actually
downloading the contents of the file. It is important to note that
most servers will only return file size information for actual
documents stored on the server, not for dynamically created content
generated by scripts or web pages which use server-side
includes.
GetFileTime
Return the modification time for the specified file on the server.
This can be used by your application to determine if the file has
been changed since the time that you last uploaded or downloaded
the contents.
DeleteFile
Remove a file from the server. This operation requires that the
current user have the appropriate permissions to delete the file.
Not all servers support the use of this command, and it would
typically require that the client authenticate prior to calling
this method.
Command
This method enables the client to send any command directly to the
server. This is commonly used to issue custom commands to servers
that are configured to use extensions to the standard protocol.
The control also provides methods to execute scripts on the web server and return the output from those scripts back to your application. Your program can pass additional data to the script, typically either as a query string or as form data, which is similar in concept to how arguments are passed to a command that is entered from the command prompt.
GetData
In addition to being used to simply return the contents of a file,
this method can also be used to execute a script on the server and
return the output of that script to your program. Arguments to the
script can be specified by passing them as a query string. For
example, consider the following resource name:
/cgi-bin/test.cgi?data1=value1&data2=value2
This would specify that the script /cgi-bin/test.cgi is to be executed, and two arguments will be passed to that script: data1=value and data2=value2. The ampersand is used to separate the arguments, and they are grouped as pairs of values separated by an equal sign. Note that the actual format and value of the query string depends on how the script is written.
PostData
An alternative method of providing information to a script is to
post data to the script. Instead of the data being part of the
resource name itself, posted data is sent separately and is
provided as input to the script. This is the same method that is
typically used when a user clicks the Submit button on a web-based
form. This method requires the name of the script and the address
of a buffer that contains the data that is to be posted. The
resulting output from the script is returned to the caller in the
same way that the GetData method works.