source: trunk/third/libghttp/doc/ghttp.html @ 15592

Revision 15592, 7.4 KB checked in by ghudson, 24 years ago (diff)
This commit was generated by cvs2svn to compensate for changes in r15591, which included commits to RCS files with non-trunk default branches.
Line 
1<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
2<html>
3  <head>
4    <title>gHTTP library</title>
5    <style type="text/css">
6      BODY { font-family: helvetica; }
7      .COMMENT { color: green; }
8      .HIGHLIGHT { color: blue; }
9      .CODE { font-family: Courier; color: red; }
10    </style>
11  </head>
12
13  <body>
14    <div align=center><h3>libgHTTP</h3></div>
15
16    <h3>Overview</h3>
17
18    <p>
19      The HTTP protocol is the protocol that is the underlying
20      transport mechanism for the modern world wide web.  The protocol
21      is well documented and widely implemented.  While the use of the
22      protocol is generally associated with the web, its uses can be
23      extended to many other areas where a stateless, transactional
24      protocol may be appropriate.
25    </p>
26    <p>
27      This library is fully compliant with HTTP 1.1 as defined in
28      the draft 5 update of RFC 2068.
29    </p>
30    <p>
31      The gHTTP library is designed to be simple and easy to use while
32      still allowing you to get your feet wet at the protocol layer if
33      you have to.  It is also designed with graphical, non-threaded
34      applications in mind.  You should be able to use the library in
35      your application and never block waiting to send or recieve data
36      to a remote server.  The main thread of execution should always
37      be available to refresh its display.
38    </p>
39
40    <hr>
41   
42    <h3>A simple example</h3>
43
44    <p>
45      Here's a simple example to get you started.  This snippit of
46      code shows how you can go out and get a file off of an HTTP
47      server.  Please note that this code contains no error checking
48      at all.
49    </p>
50    <p>
51      <span class="CODE">
52        <span class="COMMENT">/* This is the http request object */</span><br>
53        ghttp_request *request = NULL;<br>
54        <span class="COMMENT">/* Allocate a new empty request object */</span><br>
55        request = ghttp_request_new();<br>
56        <span class="COMMENT">/* Set the URI for the request object */</span><br>
57        ghttp_set_uri(request, "http://localhost:8080/index.html");<br>
58        <span class="COMMENT">/* Close the connection after you are done. */</span><br>
59        ghttp_set_header(request, http_hdr_Connection, "close");<br>
60        <span class="COMMENT">/* Prepare the connection */</span><br>
61        ghttp_prepare(request);<br>
62        <span class="COMMENT">/* Process the request */</span><br>
63        ghttp_process(request);<br>
64        <span class="COMMENT">/* Write out the body.  Note that the body of the request may
65          not be null terminated so we have to be careful of the length. */</span><br>
66        fwrite(ghttp_get_body(request), ghttp_get_body_len(request), 1, stdout);<br>
67        <span class="COMMENT">/* Destroy the request.  This closes any file descriptors that
68          may be open and will free any memory associated with the request. */</span><br>
69        ghttp_request_destroy(request);<br>
70      </span>
71    </p>
72    <p>
73      As you can see, you can get a lot of work done with very few function calls.
74    </p>
75    <hr>
76    <a name="FLOW">
77    <h3>The flow of a HTTP request</h3>
78    <p>
79      HTTP requests, as implemented in gHTTP follow a very simple
80      pattern.  First, you must allocate a new HTTP request object
81      using the call <span class="CODE">ghttp_request_new()</span>.
82      The request object is what you will use to set properties for
83      your request and how you will retrieve the response to your
84      requests.
85    </p>
86    <p>
87      Once you have allocated the request object you will need to set
88      certian properties before actually making the request.
89    </p>
90    <p>
91      At a minimum, you must set the URI that the request is for.  You
92      can do this using the call <span
93      class="CODE">ghttp_set_uri()</span>.  This function takes the
94      request object and the uri that is the target of the request.
95      You can use any http URI as defined by RFC 2396.  gHTTP does not
96      do any other protocols other than HTTP.
97    </p>
98    <p>
99      For example, the following are examples of valid http URI's:
100    </p>
101    <p>
102      <span class="CODE">
103        http://localhost:8080/index.html<br>
104        http://www.foo.com:80/<br>
105        http://www.gnome.org<br>
106      </span>
107    </p>
108    <p>
109      There are a lot of other properties that you can set on a
110      request.  You can set specific headers in the request using
111      <span class="CODE">ghttp_set_header()</span>, you can set the
112      http URI of your proxy host using <span class="CODE">
113      ghttp_set_proxy()</span>, or you can set the body of the HTTP
114      request that you are making using <span
115      class="CODE">ghttp_set_body()</span>.  Other properties that you
116      can set on a transaction are documented below in the section <a
117      href="#PROPERTIES">Request Properties</a>.
118    </p>
119    <p>
120      Once you have set all of the properties on your request, you
121      must call <span class="CODE">ghttp_prepare()</span> on the
122      request.  This will do a hostname lookup on the host that the
123      resource is for and make some other internal preperations.
124    </p>
125    <p>
126      Now, you are ready to make the request.  Do complete the
127      request, simply call <span class="CODE">ghttp_process()</span>.
128      This will connect to the remote server and try to complete your
129      transaction.  If you have set the library to use asynchronous
130      operation ( see <a href="#PROPERTIES">Request Properties</a>
131      below ) you may need to call this more than once until the
132      transaction is complete.
133    </p>
134    <p>
135      Now that you have completed this transaction you can do several
136      things.  If you want to access another resource that is on the
137      same server you can change the URI and use the same request
138      object again.  For example if you have just completed a
139      transaction getting the URI <span
140      class="CODE">http://localhost/index.html</span> and now you want
141      to get <span class="CODE">http://localhost/image.gif</span> you
142      should call <span class="CODE">ghttp_set_uri()</span> to set the
143      request object to the new URI, call <span
144      class="CODE">ghttp_prepare()</span> to propagate any changes,
145      <span class="CODE">ghttp_clean()</span> to clean out any old
146      buffers, and then call <span class="CODE">ghttp_process()</span>
147      to run your request.  This has the advantage of using an open
148      connection if it is available and DNS information if it has
149      already been looked up.
150    </p>
151    <p>
152      Once you have completed a request you can use several functions
153      to get the data from the response.  You can examine a specific
154      header in the response using <span
155      class="CODE">ghttp_get_header()</span>.  You can get a handle to
156      the body of the data using <span
157      class="CODE">ghttp_get_body()</span> and the associated length
158      of the body using <span
159      class="CODE">ghttp_get_body_len()</span>.  Remember that the
160      data in the body of a response is not null-terminated as it can
161      be data of any type.
162    </p>
163    <p>
164      Additionally, you can get the actual code that was given in the
165      response using <span class="CODE">ghttp_status_code()</span> and
166      <span class="CODE">ghttp_reason_phrase()</span>.
167    </p>
168    <hr>
169    <a name="PROPERTIES">
170      <h3>Request Properties</h3>
171    <p>
172     
173    </p>
174    <hr>
175    <address><a href="mailto:blizzard@appliedtheory.com">Christopher Blizzard</a></address>
176<!-- Created: Mon Nov  9 00:45:57 CET 1998 -->
177<!-- hhmts start -->
178Last modified: Sat Nov 14 04:07:56 XXX 1998
179<!-- hhmts end -->
180  </body>
181</html>
Note: See TracBrowser for help on using the repository browser.