|
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 typically uses the standard GET
and POST commands, and the resulting output from the script is
returned back to the application where it can be displayed or
processed. There are several different functions you can use,
depending on the service you're requesting information from. The
HttpPostData function is general-purpose and can be used with
virtually any type of POST request, including submitting binary data.
However, it can require some additional settings such as the content
type and encoding method. The HttpPostJson and HttpPostXml
functions are specifically designed for requests which require JSON or
XML payloads, respectively.
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|https]://[username : [password] @] hostname [:port] / 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, this can 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.
Understanding how a URL is constructed will help in understanding
how the different functions in the library work together. For
example, the server 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 TLS 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 server. 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 server 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 server and stores it in
a file on the local system.
HttpPutData
This function creates a file on the server 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 server
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 server
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 server-side scripts, returning the output 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 which is a PHP script:
/app/test.php?data1=value1&data2=value2
This would specify that the script /app/test.php 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 will be posted. The resulting output from the
script is returned to the caller in the same way that HttpGetData
works.
HttpPostJson and
HttpPostXml
These are specialized versions of the HttpPostData function which
are designed to work with JSON and XML payloads. They will automatically
set the correct content type and encoding for the request. If you are
using the Unicode version of these functions, they will automatically
convert the payload to standard UTF-8 encoding prior to submitting the
data to the server. It is recommended you use these functions when
accessing RESTful API services which expect JSON or XML requests.
HttpSubmitRequest
This is a high-level function which supports either a GET, PUT or POST
request in a single function call. With this function, there is no need
to explicitly connect to the server using HttpConnect. The entire
transaction (i.e.: establishing the connection, submitting the request,
processing the server response and then disconnecting) is handled
automatically. If your application does not need to maintain a persistent
connection to the server, using this function can eliminate a lot of
boilerplate code which would otherwise be required.
|