|
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 library 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 API used with the File Transfer Protocol library,
you can use HTTP to upload and download files. In addition to the
standard method for downloading files, the library 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 functions such as HttpPutFile and HttpGetFile can be
used to transfer files in a single function call. There are also
functions such as HttpOpenFile and HttpCreateFile 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 HttpCommand function to
execute the script and then process the output in code, or can use
the higher level function HttpPostData which will execute the
script and return the output from that script in a single function
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 functions in the library work
together. For example, the remote host name and port number portion
of the URL are the values passed to the HttpConnect function to
establish the connection. The user name and password values are
passed to the HttpAuthenticate function to authenticate the client
session. And the resource name is passed to the HttpGetData or
HttpGetFile functions to transfer it to the local system.
The first step that your application must take is to initialize
the library and then establish a connection. The following
functions are available for use by your application:
HttpInitialize
Initialize the library and load the Windows Sockets library for the
current process. This must be the first function call that the
application makes before calling the other HTTP API functions.
HttpConnect
Establish a connection to the server. This function will return a
handle to a client session which is used in subsequent calls to the
HTTP API.
HttpProxyConnect
A variation on the standard connection, this function can be used
to connect to an HTTP server through a proxy server. The library
provides support for standard CERN type proxies as well as
tunneling proxies that are commonly used with secure SSL
connections.
HttpAuthenticate
If the server requires the client to authenticate prior to
accessing a resource, this function can be called to provide the
user name and password. This is commonly used to restrict access to
certain areas of a website to authenticated users only. Although it
is permitted to authenticate immediately after connecting to a
server, it is not required. An application can wait until the
server returns an error indicating that authentication is required
to access the resource. It can call this function at that time, and
then re-request the resource. This is how most browsers work. This
function may be called more than once during a session if the
client needs to change the current user name and/or password being
used to authenticate access to the server.
HttpDisconnect
Disconnect from the server and release any resources that have been
allocated for the client session. After this function is called,
the client handle is no longer valid.
HttpUninitialize
Unload the Windows Sockets library and release any resources that
have been allocated for the current process. This is the last
function call that the application should make prior to
terminating.
Using an API similar to the File Transfer Protocol library, this
library provides several functions which can be used to transfer
files between the local and remote host. This group of functions is
high level, meaning that it is not necessary to actually write the
code to read and/or write the file data. The library automatically
handles the lower level file I/O and notifies your application of
the status of the transfer by periodically generating progress
events.
HttpGetData
This function 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.
HttpGetFile
This function transfers a file from the remote host and stores it
in a file on the local system.
HttpPutData
This function 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.
HttpPutFile
This function 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 function.
HttpPostFile
This function 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.
File Management
The library can also perform some basic file management
functions as well as send custom commands to the server. Some web
servers also provide more advanced document management functions
using WebDAV, an extension to HTTP for distributed document
authoring.
HttpGetFileSize
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.
HttpGetFileTime
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.
HttpDeleteFile
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 function.
HttpCommand
This function 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 library also provides functions 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.
HttpGetData
In addition to being used to simply return the contents of a file,
this function 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.
HttpPostData
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 function 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 HttpGetData works.
|