The HTTP protocol is the protocol that is the underlying
transport mechanism for the modern world wide web. The protocol
is well documented and widely implemented. While the use of the
protocol is generally associated with the web, its uses can be
extended to many other areas where a stateless, transactional
protocol may be appropriate.
This library is fully compliant with HTTP 1.1 as defined in
the draft 5 update of RFC 2068.
The gHTTP library is designed to be simple and easy to use while
still allowing you to get your feet wet at the protocol layer if
you have to. It is also designed with graphical, non-threaded
applications in mind. You should be able to use the library in
your application and never block waiting to send or recieve data
to a remote server. The main thread of execution should always
be available to refresh its display.
Here's a simple example to get you started. This snippit of
code shows how you can go out and get a file off of an HTTP
server. Please note that this code contains no error checking
at all.
As you can see, you can get a lot of work done with very few function calls.
The flow of a HTTP request
HTTP requests, as implemented in gHTTP follow a very simple
pattern. First, you must allocate a new HTTP request object
using the call ghttp_request_new().
The request object is what you will use to set properties for
your request and how you will retrieve the response to your
requests.
Once you have allocated the request object you will need to set
certian properties before actually making the request.
At a minimum, you must set the URI that the request is for. You
can do this using the call ghttp_set_uri(). This function takes the
request object and the uri that is the target of the request.
You can use any http URI as defined by RFC 2396. gHTTP does not
do any other protocols other than HTTP.
For example, the following are examples of valid http URI's:
http://localhost:8080/index.html
http://www.foo.com:80/
http://www.gnome.org
There are a lot of other properties that you can set on a
request. You can set specific headers in the request using
ghttp_set_header(), you can set the
http URI of your proxy host using
ghttp_set_proxy(), or you can set the body of the HTTP
request that you are making using ghttp_set_body(). Other properties that you
can set on a transaction are documented below in the section Request Properties.
Once you have set all of the properties on your request, you
must call ghttp_prepare() on the
request. This will do a hostname lookup on the host that the
resource is for and make some other internal preperations.
Now, you are ready to make the request. Do complete the
request, simply call ghttp_process().
This will connect to the remote server and try to complete your
transaction. If you have set the library to use asynchronous
operation ( see Request Properties
below ) you may need to call this more than once until the
transaction is complete.
Now that you have completed this transaction you can do several
things. If you want to access another resource that is on the
same server you can change the URI and use the same request
object again. For example if you have just completed a
transaction getting the URI http://localhost/index.html and now you want
to get http://localhost/image.gif you
should call ghttp_set_uri() to set the
request object to the new URI, call ghttp_prepare() to propagate any changes,
ghttp_clean() to clean out any old
buffers, and then call ghttp_process()
to run your request. This has the advantage of using an open
connection if it is available and DNS information if it has
already been looked up.
Once you have completed a request you can use several functions
to get the data from the response. You can examine a specific
header in the response using ghttp_get_header(). You can get a handle to
the body of the data using ghttp_get_body() and the associated length
of the body using ghttp_get_body_len(). Remember that the
data in the body of a response is not null-terminated as it can
be data of any type.
Additionally, you can get the actual code that was given in the
response using ghttp_status_code() and
ghttp_reason_phrase().