Annotation of libwww/Library/src/HTReq.html, revision 2.71
2.69 kirschpi 1: <html>
2: <head>
3: <meta http-equiv="Content-Type" content="text/html">
2.40 frystyk 4: <!-- Changed by: Henrik Frystyk Nielsen, 15-Jul-1996 -->
2.69 kirschpi 5: <title>W3C Sample Code Library libwww Request Class</title>
6: </head>
7:
8: <body>
9: <h1>The Request Class</h1>
10: <pre>/*
2.1 frystyk 11: ** (c) COPYRIGHT MIT 1995.
12: ** Please first read the full copyright statement in the file COPYRIGH.
2.69 kirschpi 13: */</pre>
14:
15: <p>Libwww is based on a request/response paradigm and the Request class
16: defines "<i>an operation to be performed on a URL</i>". The request object is
17: the main entry point for an application to issue a request to the Library -
18: all operations on a URL <i>must</i> use a Request object. The request object
2.31 frystyk 19: is application independent in that both servers and clients use the same
20: Request class. Examples of requests passed to the Library are a client
2.69 kirschpi 21: application issuing a <b>GET</b> request on a HTTP URL, or a server issuing a
22: load on a local file URL. The only difference is that the client gets the
23: input from a user whereas the server gets the input via the network.</p>
24:
25: <p>A request object is created with a default set of parameters which are
26: applicable for many URL requests but the class defines a huge set of methods
27: that an be used to customize a request for a particular purpose. Example of
28: things that you can define is natural language, media types, what RFC 822
29: headers to use, whether the request should be refreshed from cache etc.
30: Scroll down and see the set of parameters you can tune.</p>
31:
32: <p>A request object is registered in the library by issuing an operation on a
33: URL - for example <b>PUT</b>, <b>POST</b>, or <b>DELETE</b>. You can find
34: many higher level "request issuing functions" in the <a
35: href="HTAccess.html">Access module</a> - the methods defined by the Request
36: class itself are very low level but can of course be used directly if
37: needed.</p>
38:
39: <p>Whereas the lifetime of the URL (in form of an anchor) often is very long
40: (for example as long as the application is running), the lifetime of a
41: request is limited to the time it takes to service the request. The core does
42: not automatically delete any request object created by the application - it
43: is for the application to do. In many cases a request object can be deleted
44: when any of the <a href="HTNet.html#callout">termination callback
45: functions</a> are called but the application may keep request objects around
46: longer than that</p>
47:
48: <p>The Library can accept an unlimited number of simultaneous requests passed
49: by the application. One of the main functions of the Library core is to
50: handle any number of ongoing requests in an intelligent manner by limiting
51: the number of active request to the fit the available resources as defined by
52: the application. This is described in more detail in the <a
53: href="HTNet.html">HTNet module</a>.</p>
54:
55: <p>This module is implemented by <a href="HTReqMan.c">HTReqMan.c</a>, and it
56: is a part of the <a href="http://www.w3.org/Library/"> W3C Sample Code
57: Library</a>.</p>
58: <pre>#ifndef HTREQ_H
2.1 frystyk 59: #define HTREQ_H
60:
2.20 frystyk 61: typedef long HTRequestID;
2.1 frystyk 62: typedef struct _HTRequest HTRequest;
63:
2.29 frystyk 64: #include "HTEvent.h"
2.1 frystyk 65: #include "HTList.h"
2.23 frystyk 66: #include "HTAssoc.h"
2.1 frystyk 67: #include "HTFormat.h"
68: #include "HTStream.h"
2.10 frystyk 69: #include "HTError.h"
2.1 frystyk 70: #include "HTNet.h"
2.31 frystyk 71: #include "HTUser.h"
2.69 kirschpi 72: #include "HTResponse.h"</pre>
73:
74: <h2><a name="Creation">Creation and Deletion Methods</a></h2>
75:
76: <p>The request object is intended to live as long as the request is still
77: active, but can be deleted as soon as it has terminated, for example in one
78: of the request termination callback functions as described in the <a
79: href="HTNet.html">Net Manager</a>. Only the anchor object stays around after
80: the request itself is terminated.</p>
81:
82: <h3>Create new Object</h3>
83:
84: <p>Creates a new request object with a default set of options -- in most
85: cases it will need some information added which can be done using the methods
86: in this module, but it will work as is for a simple request.</p>
87: <pre>extern HTRequest * HTRequest_new (void);</pre>
88:
89: <h3>Clear a Request Object</h3>
90:
91: <p>Clears all protocol specific information so that the request object can be
2.68 kahan 92: used for another request. It should be used with care as application specific
2.69 kirschpi 93: information is <b>not</b> re-initialized. Returns YES if OK, else NO.</p>
94: <pre>extern BOOL HTRequest_clear (HTRequest * me);</pre>
95:
96: <h3>Create a duplicate</h3>
97:
98: <p>Creates a new HTRequest object as a duplicate of the src request. Returns
99: YES if OK, else NO</p>
100: <pre>extern HTRequest * HTRequest_dup (HTRequest * src);</pre>
101:
102: <h4>Create a duplicate for Internal use</h4>
103:
104: <p>Creates a new HTRequest object as a duplicate of the src request. The
105: difference to the HTRequest_dup function is that we don't copy the
106: error_stack and other information that the application keeps in its copy of
107: the request object. Otherwise it will be freed multiple times. Returns YES if
108: OK, else NO</p>
109: <pre>extern HTRequest * HTRequest_dupInternal (HTRequest * src);
2.66 frystyk 110:
111: extern BOOL HTRequest_setInternal (HTRequest * request, BOOL mode);
2.69 kirschpi 112: extern BOOL HTRequest_internal (HTRequest * request);</pre>
113:
114: <h3>Delete Object</h3>
115:
116: <p>This function deletes the object and cleans up the memory.</p>
117: <pre>extern void HTRequest_delete (HTRequest * request);</pre>
118:
119: <h2><a name="Issuing">Issuing a Request</a></h2>
120:
121: <p>These are the "<i>basic request methods</i>" provided directly by the
122: Request class. This is a very low level API as the caller must have set up
123: the request object before passing it to libwww. There are two versions: one
124: for issuing client requests and one for issuing server requests. You will
125: probably most often use the client version, but, in fact, libwww can also
126: deal with incoming connections. You can find many higher level issuing
127: functions in the <a href="HTAccess.html">HTAccess module</a>. If you like,
128: you can of course use this directly!</p>
129: <pre>extern BOOL HTLoad (HTRequest * request, BOOL recursive);
130: extern BOOL HTServe(HTRequest * request, BOOL recursive);</pre>
131:
132: <h2><a name="Killing">Killing a Request</a></h2>
133:
134: <p>This function kills this particular request, see <a
135: href="HTNet.html">HTNet module</a> for a function that kills them all. If you
136: know that you are pipelining requests (typically the case for GUI browsers,
137: robots etc.) then it is often not enough to just kill a single request as the
138: whole pipeline gets affected. Therefore, in that case you MUST call the
139: <tt><a href="HTHost.html#Pipeline">HTHost_killPipe</a></tt> function
140: instead,</p>
141: <pre>extern BOOL HTRequest_kill(HTRequest * request);</pre>
142:
143: <p>Note that you can get to the HTHost object via the <a
144: href="HTNet.html">HTNet object</a> which you can <a href="#HTNet">get by
145: calling HTRequest_net(...)</a>.</p>
146:
147: <h2><a name="Relations">Relations to Other Libwww Objects</a></h2>
148:
149: <p>The Request object is linked to a set of other libwww objects - here's how
150: to get to these objects...</p>
151:
152: <h3><a name="Anchor">Binding to an Anchor Object</a></h3>
153:
154: <p>Every request object has an <a href="HTAnchor.html">anchor</a> associated
2.66 frystyk 155: with it. The anchor normally lives until the application terminates but a
156: request object only lives as long as the request is being serviced. If the
2.69 kirschpi 157: anchor that we have requested is a child anchor then we always load the
158: parent anchor; after the load jump to the location. A child anchor is a an
159: anchor which points to a subpart of the document (has a "#" in the URL).</p>
160: <pre>extern void HTRequest_setAnchor (HTRequest *request, HTAnchor *anchor);
2.66 frystyk 161: extern HTParentAnchor * HTRequest_anchor (HTRequest *request);
162:
2.69 kirschpi 163: extern HTChildAnchor * HTRequest_childAnchor (HTRequest * request);</pre>
164:
165: <h3><a name="User">Binding to a User Profile</a></h3>
166:
167: <p>Each request is associated with a <a href="HTUser.html">User profile</a>
2.66 frystyk 168: which contains information about the local host name, email address of the
169: user, news server etc. A request object is created with a default "generic
2.69 kirschpi 170: user" but can be assigned a specific user at any time.</p>
171: <pre>extern BOOL HTRequest_setUserProfile (HTRequest * request, HTUserProfile * up);
172: extern HTUserProfile * HTRequest_userProfile (HTRequest * request);</pre>
173:
174: <h3><a name="HTNet">Binding to a Net Object</a></h3>
175:
176: <p>If a request is actually going on the net then the <a
177: href="HTNet.html">Net Manager</a> is contacted to handle the request. The Net
178: manager creates a HTNEt object and links it to the Request object. You can
179: get to the HTNet object using the following functions.</p>
180: <pre>extern HTNet * HTRequest_net (HTRequest * request);
181: extern BOOL HTRequest_setNet (HTRequest * request, HTNet * net);</pre>
182:
183: <p>Note that you can go from the HTNet object to the <a
184: href="HTHost.html">HTHost</a> object by calling <tt>HTNet_host(...)</tt>.</p>
185:
186: <h3><a name="Response">Binding to a Response Object</a></h3>
187:
188: <p>If a request is actually going on the net and we are getting a response
189: back then we also create a <a href="HTResponse.html">HTResponse object</a>
190: and bind it to the request object. Once we know what to do with the response,
191: we may transfer the information to the anchor object.</p>
192: <pre>extern HTResponse * HTRequest_response (HTRequest * request);
193: extern BOOL HTRequest_setResponse (HTRequest * request, HTResponse * response);</pre>
194:
195: <h2><a name="Method">Set the Method for the Request</a></h2>
196:
197: <p>The Method is the operation to be executed on the requested object. The
198: default set if the set of operations defined by the HTTP protocol, that is
199: "GET", "HEAD", "PUT", "POST", "LINK", "UNLINK", and "DELETE" but many of
200: these can be used in other protocols as well. The important thing is to think
201: of the requested element as an object on which you want to perform an
202: operation. Then it is for the specific protocol implementation to try and
203: carry this operation out. However, not all operations can be implemented (or
204: make sense) in all protocols.</p>
205:
206: <p>Methods are handled by the <a href="HTMethod.html">Method Module</a>, and
207: the default value is "GET".</p>
208: <pre>extern void HTRequest_setMethod (HTRequest *request, HTMethod method);
209: extern HTMethod HTRequest_method (HTRequest *request);</pre>
210:
211: <h2><a name="Priority">Priority Management</a></h2>
212:
213: <p>The request can be assigned an initial priority which then gets inherited
214: by all <a href="HTNet.html">HTNet objects</a> and other requests objects
215: created as a result of this one. You can also assign a separate priority to
216: an indicidual HTNet object by using the methods in the <a
217: href="HTNet.html">Net manager</a>.</p>
218: <pre>extern HTPriority HTRequest_priority (HTRequest * request);
219: extern BOOL HTRequest_setPriority (HTRequest * request, HTPriority priority);</pre>
220:
221: <h2><a name="Pipelining">Pipelining Managament</a></h2>
222:
223: <p>Libwww supports HTTP/1.1 pipelining which greatly optimizes HTTP's
224: behavior over TCP. libwww also tries very hard to minimize the number of TCP
225: packets sent over the network. This is done by buffering outgoing requests
226: until either a minimum amount of data has been collected or a timeout causes
227: a flush to happen. The application can override the output buffering by
228: explicit request a request object to be flushed.</p>
229: <pre>extern BOOL HTRequest_setFlush (HTRequest * me, BOOL mode);
230: extern BOOL HTRequest_flush (HTRequest * me);</pre>
231:
232: <h3>Force the Pipeline to be Flushed Immediately</h3>
233:
234: <p>Forcing a fluch immediatly is slightly different as this can be done in
235: "retrospect". That is, if suddenly the application decides on performing a
236: flush after the request was initiated then it can use this function to flush
237: at a later time.</p>
238: <pre>extern int HTRequest_forceFlush (HTRequest * request);</pre>
239:
240: <h2><a name="Error">Dealing with Request Error Messages</a></h2>
241:
242: <p>Errors are, like almost anything, kept in lists. An error list can be
2.68 kahan 243: associated with a request using the following functions. In order to make
2.69 kirschpi 244: life easier, there are also some easy mapping functions to the <a
245: href="HTError.html">HTError object</a>, so that you can add an error directly
246: to a request object.</p>
247: <pre>extern HTList * HTRequest_error (HTRequest * request);
2.47 frystyk 248: extern void HTRequest_setError (HTRequest * request, HTList * list);
2.69 kirschpi 249: extern void HTRequest_deleteAllErrors (HTRequest * request);</pre>
250:
251: <p>These are the cover functions that go directly to the <a
252: href="HTError.html">Error Object</a></p>
253: <pre>extern BOOL HTRequest_addError (HTRequest * request,
2.47 frystyk 254: HTSeverity severity,
255: BOOL ignore,
256: int element,
257: void * par,
258: unsigned int length,
259: char * where);
260:
261: extern BOOL HTRequest_addSystemError (HTRequest * request,
262: HTSeverity severity,
263: int errornumber,
264: BOOL ignore,
2.69 kirschpi 265: char * syscall);</pre>
266:
267: <h2><a name="MaxRetry">Max number of Retrys for a Down Load</a></h2>
268:
269: <p>Automatic reload can happen in two situations:</p>
270: <ul>
271: <li>The server sends a redirection response</li>
272: <li>The document has expired</li>
273: </ul>
274:
275: <p>In order to avoid the Library going into an infinite loop, it is necessary
2.30 frystyk 276: to keep track of the number of automatic reloads. Loops can occur if the
2.69 kirschpi 277: server has a reload to the same document or if the server sends back a
278: Expires header which has already expired. The default maximum number of
279: automatic reloads is 6.</p>
280: <pre>extern BOOL HTRequest_setMaxRetry (int newmax);
2.1 frystyk 281: extern int HTRequest_maxRetry (void);
2.41 frystyk 282:
283: extern int HTRequest_retrys (HTRequest * request);
284: extern BOOL HTRequest_doRetry (HTRequest *request);
2.44 frystyk 285: extern BOOL HTRequest_addRetry (HTRequest * request);
2.62 kahan 286:
287: extern int HTRequest_AAretrys (HTRequest * request);
2.69 kirschpi 288: extern BOOL HTRequest_addAARetry (HTRequest * request);</pre>
289:
290: <h2><a name="MaxForward">Set Max Forwards for TRACE methods</a></h2>
291:
292: <p>The <code>TRACE</code> method is used to invoke a remote,
293: application-layer loop-back of the request message. The final recipient of
294: the request SHOULD reflect the message received back to the client as the
295: entity-body of a 200 (OK) response. The final recipient is either the origin
296: server or the first proxy or gateway to receive a Max-Forwards value of zero
297: (0) in the request. A <code>TRACE</code> request <i>MUST NOT</i> include an
298: entity.</p>
299: <pre>extern BOOL HTRequest_setMaxForwards (HTRequest * request, int maxforwards);
300: extern int HTRequest_maxForwards (HTRequest * request);</pre>
301:
302: <h2><a name="preemptive">Preemptive or Non-preemptive Access</a></h2>
303:
304: <p>An access scheme is defined with a default for using either preemptive
305: (blocking I/O) or non-preemptive (non-blocking I/O). This is basically a
306: result of the implementation of the protocol module itself. However, if
307: non-blocking I/O is the default then some times it is nice to be able to set
308: the mode to blocking instead. For example, when loading the first document
309: (the home page), blocking mode can be used instead of non-blocking.</p>
310: <pre>extern void HTRequest_setPreemptive (HTRequest *request, BOOL mode);
311: extern BOOL HTRequest_preemptive (HTRequest *request);</pre>
312:
313: <h2><a name="conneg">Content Negotiation</a></h2>
314:
315: <p>When accessing the local file system, the Library is capable of performing
2.47 frystyk 316: content negotioation as described by the HTTP protocol. This is mainly for
317: server applications, but some client applications might also want to use
318: content negotiation when accessing the local file system. This method enables
2.69 kirschpi 319: or disables content negotiation - the default value is <em>ON</em>.</p>
320: <pre>extern void HTRequest_setNegotiation (HTRequest *request, BOOL mode);
321: extern BOOL HTRequest_negotiation (HTRequest *request);</pre>
322:
323: <h2><a name="Preconditions">Request Preconditions (HTTP If-* Headers)</a></h2>
324:
325: <p>Should this request use preconditions when doing a <tt>PUT</tt> or a
326: <tt>POST</tt>? These are the "<tt>if-*</tt>" header fields that can be used
2.64 frystyk 327: to avoid version conflicts etc. The default is not to use any preconsitions
2.69 kirschpi 328: (<tt>HT_NO_MATCH</tt>). The <tt>_THIS</tt> versions use etags and/or time
329: stamps and the <tt>_ANY</tt> versions use the "<tt>*</tt>" header field value
330: of the <tt>if-match</tt> and <tt>if-non-match</tt> header fields.</p>
331: <pre>typedef enum _HTPreconditions {
2.64 frystyk 332: HT_NO_MATCH = 0,
333: HT_MATCH_THIS,
334: HT_MATCH_ANY,
335: HT_DONT_MATCH_THIS,
336: HT_DONT_MATCH_ANY
337: } HTPreconditions;
338:
339: extern void HTRequest_setPreconditions (HTRequest * me, HTPreconditions mode);
2.69 kirschpi 340: extern HTPreconditions HTRequest_preconditions (HTRequest * me);</pre>
341:
342: <h2><a name="Parsers">Local MIME header Parsers</a></h2>
343:
344: <p>MIMEParsers get their own type which is optimized for static and regex
345: parser strings.</p>
346: <pre>typedef struct _HTMIMEParseSet HTMIMEParseSet;
2.66 frystyk 347: extern void HTRequest_setMIMEParseSet (HTRequest *request,
348: HTMIMEParseSet * parseSet, BOOL local);
349: extern HTMIMEParseSet * HTRequest_MIMEParseSet (HTRequest *request,
2.69 kirschpi 350: BOOL * pLocal);</pre>
351:
352: <h2><a name="default">Which Default Protocol Header Fields To Use?</a></h2>
353:
354: <p>Libwww supports a large set of headers that can be sent along with a
355: request (or a response for that matter). All headers can be either disabled
356: or enabled using bit flags that are defined in the following. See also the <a
357: href="#extra">section on how to extend the default set of supported header
358: fields</a>.</p>
359:
360: <h3><a name="gnhd">General HTTP Header Mask</a></h3>
361:
362: <p>There are a few header fields which have general applicability for both
363: request and response mesages, but which do not apply to the communication
364: parties or theentity being transferred. This mask enables and disables these
365: headers. If the bit is not turned on they are not sent.</p>
366: <pre>typedef enum _HTGnHd {
2.45 frystyk 367: HT_G_CC = 0x1,
368: HT_G_CONNECTION = 0x2,
369: HT_G_DATE = 0x4,
370: HT_G_PRAGMA_NO_CACHE= 0x8,
371: HT_G_FORWARDED = 0x10,
372: HT_G_MESSAGE_ID = 0x20,
2.53 frystyk 373: HT_G_MIME = 0x40,
2.54 frystyk 374: HT_G_TRAILER = 0x80,
2.66 frystyk 375: HT_G_TRANSFER = 0x100,
376: HT_G_EXTRA_HEADERS = 0x200
2.1 frystyk 377: } HTGnHd;
378:
2.54 frystyk 379: #define DEFAULT_GENERAL_HEADERS \
2.66 frystyk 380: HT_G_CONNECTION + HT_G_CC + HT_G_TRANSFER + HT_G_TRAILER + \
381: HT_G_EXTRA_HEADERS
2.1 frystyk 382:
383: extern void HTRequest_setGnHd (HTRequest *request, HTGnHd gnhd);
384: extern void HTRequest_addGnHd (HTRequest *request, HTGnHd gnhd);
2.69 kirschpi 385: extern HTGnHd HTRequest_gnHd (HTRequest *request);</pre>
386:
387: <h3><a name="rqhd">Request Headers</a></h3>
388:
389: <p>The request header fields allow the client to pass additional information
2.30 frystyk 390: about the request (and about the client itself) to the server. All headers
391: are optional but the default value is all request headers if present
2.69 kirschpi 392: <em>except</em> <code>From</code> and <code>Pragma</code>.</p>
393: <pre>typedef enum _HTRqHd {
2.16 frystyk 394: HT_C_ACCEPT_TYPE = 0x1,
395: HT_C_ACCEPT_CHAR = 0x2,
396: HT_C_ACCEPT_ENC = 0x4,
2.53 frystyk 397: HT_C_ACCEPT_TE = 0x8,
398: HT_C_ACCEPT_LAN = 0x10,
399: HT_C_AUTH = 0x20, /* Includes proxy authentication */
400: HT_C_EXPECT = 0x40,
401: HT_C_FROM = 0x80,
402: HT_C_HOST = 0x100,
403: HT_C_IMS = 0x200,
404: HT_C_IF_MATCH = 0x400,
2.64 frystyk 405: HT_C_IF_MATCH_ANY = 0x800,
2.63 frystyk 406: HT_C_IF_NONE_MATCH = 0x1000,
2.64 frystyk 407: HT_C_IF_NONE_MATCH_ANY=0x2000,
2.63 frystyk 408: HT_C_IF_RANGE = 0x4000,
409: HT_C_IF_UNMOD_SINCE = 0x8000,
410: HT_C_MAX_FORWARDS = 0x10000,
411: HT_C_RANGE = 0x20000,
412: HT_C_REFERER = 0x40000,
413: HT_C_USER_AGENT = 0x80000
2.1 frystyk 414: } HTRqHd;
415:
2.16 frystyk 416: #define DEFAULT_REQUEST_HEADERS \
2.37 frystyk 417: HT_C_ACCEPT_TYPE + HT_C_ACCEPT_CHAR + \
2.53 frystyk 418: HT_C_ACCEPT_ENC + HT_C_ACCEPT_TE + HT_C_ACCEPT_LAN + HT_C_AUTH + \
419: HT_C_EXPECT + HT_C_HOST + HT_C_REFERER + HT_C_USER_AGENT
2.1 frystyk 420:
421: extern void HTRequest_setRqHd (HTRequest *request, HTRqHd rqhd);
422: extern void HTRequest_addRqHd (HTRequest *request, HTRqHd rqhd);
2.69 kirschpi 423: extern HTRqHd HTRequest_rqHd (HTRequest *request);</pre>
424:
425: <h3><a name="rshd">Response Headers</a></h3>
426:
427: <p>The response header fields allow the server to pass additional information
2.30 frystyk 428: about the response (and about the server itself) to the client. All headers
2.69 kirschpi 429: are optional.</p>
430: <pre>typedef enum _HTRsHd {
2.37 frystyk 431: HT_S_AGE = 0x1,
432: HT_S_LOCATION = 0x2,
433: HT_S_PROXY_AUTH = 0x4,
434: HT_S_PUBLIC = 0x8,
435: HT_S_RETRY_AFTER = 0x10,
436: HT_S_SERVER = 0x20,
437: HT_S_VARY = 0x40,
438: HT_S_WARNING = 0x80,
2.53 frystyk 439: HT_S_WWW_AUTH = 0x100,
440: HT_S_TRAILER = 0x200
2.16 frystyk 441: } HTRsHd;
442:
443: #define DEFAULT_RESPONSE_HEADERS HT_S_SERVER
444:
445: extern void HTRequest_setRsHd (HTRequest * request, HTRsHd rshd);
446: extern void HTRequest_addRsHd (HTRequest * request, HTRsHd rshd);
2.69 kirschpi 447: extern HTRsHd HTRequest_rsHd (HTRequest * request);</pre>
448:
449: <h3><a name="enhd">Entity Header Mask</a></h3>
450:
451: <p>The entity headers contain information about the object sent in the HTTP
452: transaction. See the <a href="HTAnchor.html">Anchor module</a>, for the
453: storage of entity headers. This flag defines which headers are to be sent in
454: a request together with an entity body. All headers are optional but the
455: default value is <em>ALL ENTITY HEADERS IF PRESENT</em></p>
456: <pre>typedef enum _HTEnHd {
2.37 frystyk 457: HT_E_ALLOW = 0x1,
458: HT_E_CONTENT_BASE = 0x2,
459: HT_E_CONTENT_ENCODING = 0x4,
460: HT_E_CONTENT_LANGUAGE = 0x8,
461: HT_E_CONTENT_LENGTH = 0x10,
462: HT_E_CONTENT_LOCATION = 0x20,
463: HT_E_CONTENT_MD5 = 0x40,
464: HT_E_CONTENT_RANGE = 0x80,
465: HT_E_CTE = 0x100, /* Content-Transfer-Encoding */
466: HT_E_CONTENT_TYPE = 0x200,
467: HT_E_DERIVED_FROM = 0x400,
468: HT_E_ETAG = 0x800,
469: HT_E_EXPIRES = 0x1000,
470: HT_E_LAST_MODIFIED = 0x2000,
471: HT_E_LINK = 0x4000,
472: HT_E_TITLE = 0x8000,
473: HT_E_URI = 0x10000,
474: HT_E_VERSION = 0x20000
2.1 frystyk 475: } HTEnHd;
476:
2.66 frystyk 477: #define DEFAULT_ENTITY_HEADERS 0xFFFFFFFF /* all */
2.1 frystyk 478:
479: extern void HTRequest_setEnHd (HTRequest *request, HTEnHd enhd);
480: extern void HTRequest_addEnHd (HTRequest *request, HTEnHd enhd);
2.69 kirschpi 481: extern HTEnHd HTRequest_enHd (HTRequest *request);</pre>
482:
483: <h2><a name="extra">Extending The Default Set Of Header Fields</a></h2>
484:
485: <p>See also how to <a href="#default">set up default header fields</a>. There
486: are three ways to extend the set of headers that are sent in a request:</p>
487: <ol>
488: <li>A simple <a href="HTAssoc.html">association list</a></li>
489: <li>A <a href="HTHeader.html">stream oriented approach where the stream
490: (called a generator)</a> has direct access to the outgoing stream. That
491: is, it can add any header it likes.</li>
492: <li><a href="/Protocols/HTTP/ietf-http-ext/">HTTP extension mechanism</a>
493: which is a much better way for handling extensions.</li>
494: </ol>
495:
496: <h3>1) Simple Association List</h3>
497:
498: <p>Add the (name, value) and it will be converted into MIME header format as
499: name: value. Do NOT add <tt>CRLF</tt> line termination - this is done by the
500: HTTP header generator stream</p>
501: <pre>extern BOOL HTRequest_addExtraHeader (HTRequest * request,
2.66 frystyk 502: char * token, char * value);
503: extern HTAssocList * HTRequest_extraHeader (HTRequest * request);
2.69 kirschpi 504: extern BOOL HTRequest_deleteExtraHeaderAll (HTRequest * request);</pre>
505:
506: <h3>2) Stream Oriented Header Generators</h3>
507:
508: <p>Extra header information can be send along with a request using <a
509: href="HTHeader.html">header generators</a>. The text is sent as is so it must
510: be preformatted with <tt>CRLF</tt> line terminators. You can also register <a
511: href="HTHeader.html">MIME header parsers</a> using the HTHeader module.</p>
512: <pre>extern void HTRequest_setGenerator (HTRequest *request, HTList *gens,
2.66 frystyk 513: BOOL override);
2.69 kirschpi 514: extern HTList * HTRequest_generator (HTRequest *request, BOOL *override);</pre>
515:
516: <h3>3) HTTP Extension Framework</h3>
517:
518: <p>These association lists contain the information that we are to send as
519: HTTP Extension Framework. This is not done yet but you can find some hints in
520: the PEP module</p>
521: <pre>/* TBD */</pre>
522:
523: <h2><a name="Accept">User And Application Preferences Using Accept
524: Headers</a></h2>
525:
526: <p>The Accept family of headers is an important part of HTTP handling the
527: format negotiation. The Library supports both a global set of accept headers
528: that are used in <em>all</em> HTTP requests and a local set of accept headers
2.47 frystyk 529: that are used in specific requests only. The global ones are defined in the
2.69 kirschpi 530: <a href="HTFormat.html">Format Manager</a>.</p>
531:
532: <p>Each request can have its local set of accept headers that either are
533: added to the global set or replaces the global set of accept headers. Non of
534: the headers <em>have</em> to be set. If the global set is sufficient for all
535: requests then this us perfectly fine. If the parameter "override" is set then
536: only local accept headers are used, else <em>both</em> local and global
537: headers are used.</p>
538:
539: <h3>Content Types</h3>
540:
541: <p>The <em>local</em> list of specific conversions which the format manager
542: can do in order to fulfill the request. It typically points to a list set up
543: on initialisation time for example by <a href="HTInit.html">HTInit()</a>.
544: There is also a <a href="HTFormat.html#z17"><em>global</em></a> list of
545: conversions which contains a generic set of possible conversions.</p>
546: <pre>extern void HTRequest_setConversion (HTRequest *request, HTList *type, BOOL override);
547: extern HTList * HTRequest_conversion (HTRequest *request);</pre>
548:
549: <h3>Content Encodings</h3>
550:
551: <p>The list of encodings acceptable in the output stream.</p>
552: <pre>extern void HTRequest_setEncoding (HTRequest *request, HTList *enc, BOOL override);
553: extern HTList * HTRequest_encoding (HTRequest *request);</pre>
554:
555: <h3>Transfer Encodings</h3>
556:
557: <p>The list of transfer encodings acceptable in the output stream.</p>
558: <pre>extern void HTRequest_setTransfer (HTRequest *request, HTList *te, BOOL override);
559: extern HTList * HTRequest_transfer (HTRequest *request);</pre>
560:
561: <h3>Content Languages</h3>
562:
563: <p>The list of (human) language values acceptable in the response. The
564: default is all languages.</p>
565: <pre>extern void HTRequest_setLanguage (HTRequest *request, HTList *lang, BOOL override);
566: extern HTList * HTRequest_language (HTRequest *request);</pre>
567:
568: <h3>Content Charsets</h3>
569:
570: <p>The list of charsets accepted by the application</p>
571: <pre>extern void HTRequest_setCharset (HTRequest *request, HTList *charset, BOOL override);
572: extern HTList * HTRequest_charset (HTRequest *request);</pre>
573:
574: <h2><a name="Cache">HTTP Cache Validation and Cache Control</a></h2>
575:
576: <p>The Library has two concepts of caching: in memory and on file. When
577: loading a document, this flag can be set in order to define who can give a
578: response to the request. The memory buffer is considered to be equivalent to
579: a history buffer. That is, it doesn't not follow the same expiration
580: mechanism that is characteristic for a persistent file cache.</p>
581:
582: <p>You can also set the cache to run in disconnected mode - see the <a
583: href="HTCache.html">Cache manager</a> for more details on how to do this.</p>
584: <pre>typedef enum _HTReload {
2.47 frystyk 585: HT_CACHE_OK = 0x0, /* Use any version available */
586: HT_CACHE_FLUSH_MEM = 0x1, /* Reload from file cache or network */
587: HT_CACHE_VALIDATE = 0x2, /* Validate cache entry */
588: HT_CACHE_END_VALIDATE = 0x4, /* End to end validation */
589: HT_CACHE_RANGE_VALIDATE = 0x8,
2.52 frystyk 590: HT_CACHE_FLUSH = 0x10, /* Force full reload */
591: HT_CACHE_ERROR = 0x20 /* An error occurred in the cache */
2.47 frystyk 592: } HTReload;
593:
594: extern void HTRequest_setReloadMode (HTRequest *request, HTReload mode);
2.69 kirschpi 595: extern HTReload HTRequest_reloadMode (HTRequest *request);</pre>
596:
597: <h2>Default PUT name</h2>
598:
599: <p>When publishing to a server which doesn't accept a URL ending in "/", e.g,
2.67 kahan 600: the default Overview, index page, you can use
2.69 kirschpi 601: <code>HTRequest_setAltPutName</code> to setup the intended URL. If this
2.67 kahan 602: variable is defined, it'll be used during the cache lookup and update
2.69 kirschpi 603: operationsm, so that cache-wise, it will look as if we had published only to
604: "/".</p>
605: <pre>extern char * HTRequest_defaultPutName (HTRequest * me);
2.67 kahan 606: extern BOOL HTRequest_setDefaultPutName (HTRequest * me, char * name);
2.69 kirschpi 607: extern BOOL HTRequest_deleteDefaultPutName (HTRequest * me);</pre>
608:
609: <h3>HTTP Cache Control Directives</h3>
610:
611: <p>The cache control directives are all part of the cache control header and
612: control the behavior of any intermediate cache between the user agent and the
613: origin server. This association list is a list of the connection control
614: directives that are to be sent as part of the <code>Cache-Control</code>
615: header.</p>
616: <pre>extern BOOL HTRequest_addCacheControl (HTRequest * request,
2.47 frystyk 617: char * token, char *value);
618: extern BOOL HTRequest_deleteCacheControlAll (HTRequest * request);
2.69 kirschpi 619: extern HTAssocList * HTRequest_cacheControl (HTRequest * request);</pre>
620:
621: <h2><a name="Date">Date and Time Stamp when Request was Issued</a></h2>
622:
623: <p>The start time when the request was issued may be of value to the cache
624: validation mechanism as described by the HTTP/1.1 specification. The value is
625: automatically set when creating the request headers and sending off the
626: request. The time is a local time.</p>
627: <pre>extern time_t HTRequest_date (HTRequest * request);
628: extern BOOL HTRequest_setDate (HTRequest * request, time_t date);</pre>
629:
630: <h2><a name="Expect">HTTP Expect Directives</a></h2>
631:
632: <p>The Expect request-header field is used to indicate that particular server
633: behaviors are required by the client. A server that does not understand or is
634: unable to comply with any of the expectation values in the Expect field of a
635: request MUST respond with appropriate error status.</p>
636: <pre>extern BOOL HTRequest_addExpect (HTRequest * me,
2.53 frystyk 637: char * token, char * value);
638: extern BOOL HTRequest_deleteExpect (HTRequest * me);
2.69 kirschpi 639: extern HTAssocList * HTRequest_expect (HTRequest * me);</pre>
640:
641: <h2><a name="Partial">Partial Requests and Range Retrievals</a></h2>
642:
643: <p>Libwww can issue range requests in case we have already obtained a part of
644: the entity body. Since all HTTP entities are represented in HTTP messages as
645: sequences of bytes, the concept of a byte range is meaningful for any HTTP
646: entity. (However, not all clients and servers need to support byte-range
2.47 frystyk 647: operations.) Byte range specifications in HTTP apply to the sequence of bytes
648: in the entity-body (not necessarily the same as the message-body). A byte
2.69 kirschpi 649: range operation may specify a single range of bytes, or a set of ranges
650: within a single entity.</p>
651: <pre>extern BOOL HTRequest_addRange (HTRequest * request,
2.47 frystyk 652: char * unit, char * range);
653: extern BOOL HTRequest_deleteRangeAll (HTRequest * request);
2.69 kirschpi 654: extern HTAssocList * HTRequest_range (HTRequest * request);</pre>
655:
656: <h2><a name="Connection">HTTP Connection Control Request Directives</a></h2>
657:
658: <p>The connection control directives are all part of the connection header
659: and control the behavior of this connection. This association list is a list
2.47 frystyk 660: of the connection control directives that are to be sent as part of the
2.69 kirschpi 661: <code>Connection</code> header.</p>
662: <pre>extern BOOL HTRequest_addConnection (HTRequest * request,
2.47 frystyk 663: char * token, char * value);
664: extern BOOL HTRequest_deleteConnection (HTRequest * request);
2.69 kirschpi 665: extern HTAssocList * HTRequest_connection (HTRequest * request);</pre>
666:
667: <h2><a name="Access">HTTP Access Authentication Credentials</a></h2>
668:
669: <p>When a access denied response is returned to the Library, for example from
2.47 frystyk 670: a remote HTTP server, this code is passed back to the application. The
671: application can then decide whether a new request should be established or
672: not. These two methods return the authentication information required to
2.69 kirschpi 673: issue a new request, that is the new anchor and any list of keywords
674: associated with this anchor.</p>
675: <pre>extern BOOL HTRequest_addCredentials (HTRequest * request,
2.47 frystyk 676: char * token, char * value);
677: extern BOOL HTRequest_deleteCredentialsAll (HTRequest * request);
2.69 kirschpi 678: extern HTAssocList * HTRequest_credentials (HTRequest * request);</pre>
679:
680: <h3>Realms</h3>
681:
682: <p>The realm is normally set and used by the authentication filters.</p>
683: <pre>extern BOOL HTRequest_setRealm (HTRequest * request, char * realm);
2.47 frystyk 684: extern const char * HTRequest_realm (HTRequest * request);
2.69 kirschpi 685: extern BOOL HTRequest_deleteRealm (HTRequest * me);</pre>
686:
687: <h2><a name="Referer">HTTP Referer Field</a></h2>
688:
689: <p>If this parameter is set then a `Referer: <parent address> can be
690: generated in the request to the server, see <a
691: href="http://www.w3.org/Protocols/">Referer field in a HTTP Request</a></p>
692: <pre>extern void HTRequest_setParent (HTRequest *request, HTParentAnchor *parent);
693: extern HTParentAnchor * HTRequest_parent (HTRequest *request);</pre>
694:
695: <h2><a name="before">Local BEFORE and AFTER Filters</a></h2>
696:
697: <p>The request object may have it's own before and after <a
698: href="HTFilter.html">filters</a>. These may override or suplement the global
699: set in <a href="HTNet.html">HTNet</a>. The request object itself handles the
700: list element, that is this should not be freed bu the caller.</p>
701:
702: <h3>BEFORE Filters</h3>
703:
704: <p>The BEFORE <a href="HTFilter.html">filters</a> are called just after the
2.47 frystyk 705: request has been passed to the Library but before any request is issued over
2.69 kirschpi 706: the network. A BEFORE can infact stop a request completely from being
707: processed.</p>
708:
709: <h4>Add a local BEFORE Filter</h4>
710:
711: <p>You can add a local <i>BEFORE</i> filter for a single request so that the
712: both the local and global <i>BEFORE</i> filters are called or you can replace
2.47 frystyk 713: the global filters with a local set. Note that the local set can be NULL.
2.69 kirschpi 714: This can be used to effectively disable all <i>BEFORE</i> filters without
715: unregistering the global ones.</p>
716: <pre>extern BOOL HTRequest_addBefore (HTRequest * request, HTNetBefore * filter,
2.47 frystyk 717: const char * tmplate, void * param,
2.48 frystyk 718: HTFilterOrder order, BOOL override);
2.69 kirschpi 719: extern HTList * HTRequest_before (HTRequest * request, BOOL * override);</pre>
720:
721: <h4>Delete a Local BEFORE Filter</h4>
722:
723: <p>You can delete a local BEFORE filter explicitly by passing the filter
724: itself or you can delete all filters which are registered for a certain
725: status code.</p>
726: <pre>extern BOOL HTRequest_deleteBefore (HTRequest * request, HTNetBefore * filter);
727: extern BOOL HTRequest_deleteBeforeAll (HTRequest * request);</pre>
728:
729: <h3>AFTER Filters</h3>
730:
731: <p>You can add a local AFTER filter for a single request so that the both the
732: local and global AFTER filters are called or you can replace the global
733: filters with a local set. Note that the local set can be NULL. This can be
734: used to effectively disable all AFTER filters without unregistering the
735: global ones.</p>
736:
737: <p>AFTER filters can be registered to handle a certain set of return values
2.47 frystyk 738: from the protocol modules, for example explicitly to handle redirection,
739: authentication, etc. You can find all the available codes in the HTNet object
2.69 kirschpi 740: description.</p>
741:
742: <h4>Add a local AFTER Filter</h4>
743: <pre>extern BOOL HTRequest_addAfter (HTRequest * request, HTNetAfter * filter,
2.47 frystyk 744: const char * tmplate, void * param,
2.48 frystyk 745: int status, HTFilterOrder order,
746: BOOL override);
2.69 kirschpi 747: extern HTList * HTRequest_after (HTRequest * request, BOOL * override);</pre>
748:
749: <h4>Delete an AFTER Filter</h4>
750:
751: <p>You can delete a local AFTER filter explicitly by passing the filter
752: itself or you can delete all filters which are registered for a certain
753: status code.</p>
754: <pre>extern BOOL HTRequest_deleteAfter (HTRequest * request, HTNetAfter * filter);
2.47 frystyk 755: extern BOOL HTRequest_deleteAfterStatus (HTRequest * request, int status);
2.69 kirschpi 756: extern BOOL HTRequest_deleteAfterAll (HTRequest * request);</pre>
757:
758: <h2><a name="App2Net">Sending data from App to Network</a></h2>
759:
760: <p>Multiple Request objects can be connected in order to create a <a
761: href="../User/Architecture/PostWeb.html">PostWeb</a> for sending data from
762: one location (source) to another (destination). Request objects are bound
763: together by connecting the output stream of the source with the input stream
764: of the destination requst. The connection can be done directly so that the
765: output from the source is exactly what is sent to the destination or there
766: can be a conversion between the two streams so that we can do conversions on
767: the fly while copying data. This is in fact the way we use for building a
768: proxy server.</p>
769:
770: <p>The Library supports two ways of posting a data object to a remote
771: destination: Input comes from a socket descriptor or from memory. In the case
772: where you want to <em>copy</em> a URL, for example from local file system
773: <em>or</em> from a remote HTTP server then you must use the <a
774: href="../User/Architecture/PostWeb.html">PostWeb design</a>. This model
2.30 frystyk 775: operates by using at least two request objects which gets linked to eachother
2.33 frystyk 776: as part of the PostWeb model. However, if you are posting from memory, we
2.69 kirschpi 777: only use <em>one</em> request object to perform the operation. In order to do
778: this, the application must register a callback function that can be called
779: when the <a href="HTTP.c">HTTP client module</a> is ready for accepting data.
780: be included as part of the body and/or as extra metainformation. In the
781: latter case you need to register a callback function of the following type
782: using the methods provided in the next section.</p>
783: <pre>typedef int HTPostCallback (HTRequest * request, HTStream * target);
2.33 frystyk 784:
785: extern void HTRequest_setPostCallback (HTRequest * request, HTPostCallback * cbf);
2.69 kirschpi 786: extern HTPostCallback * HTRequest_postCallback (HTRequest * request);</pre>
787:
788: <p>The Entity Anchor is either the anchor directly associated with the
789: Request object or the post anchor associated with the object. The purpose of
790: the entity anchor is if we are to send data to a remote server then we get
791: the metainformation using the entity anchor.</p>
792: <pre>extern BOOL HTRequest_setEntityAnchor (HTRequest * request, HTParentAnchor * anchor);
793: extern HTParentAnchor * HTRequest_entityAnchor (HTRequest * request);</pre>
794:
795: <h3>Input Stream</h3>
796:
797: <p>The input stream is to be used to put data <em>to</em> the network.
798: Normally each protocol sets the input stream in order to generate the
799: protocol headers while making a request.</p>
800: <pre>extern void HTRequest_setInputStream (HTRequest * request, HTStream * input);
801: extern HTStream *HTRequest_inputStream (HTRequest * request);</pre>
802:
803: <h3>Is This Request part of a Post Web? (Deprecated)</h3>
804:
805: <p>Check to see if this request object is part of a Post Web.</p>
806: <pre>extern BOOL HTRequest_isPostWeb (HTRequest * request);</pre>
807:
808: <h3>Source of a Request</h3>
809:
810: <p>A request may have a source in which is another request object that as
811: output stream has the input stream of this request object.</p>
812: <pre>extern BOOL HTRequest_setSource (HTRequest * request, HTRequest * source);
813: extern HTRequest * HTRequest_source (HTRequest * request);</pre>
814:
815: <h2><a name="Net2App">Streams From Network to Application</a></h2>
816:
817: <h3>Default Output Stream</h3>
818:
819: <p>The output stream is to be used to put data down to as they come in
820: <b>from</b> the network and back to the application. The default value is
821: <code>NULL</code> which means that the stream goes to the user (display).</p>
822: <pre>extern void HTRequest_setOutputStream (HTRequest *request, HTStream *output);
823: extern HTStream *HTRequest_outputStream (HTRequest *request);</pre>
824:
825: <h3>Default Output Stream Format</h3>
826:
827: <p>The desired format of the output stream. This is used in the <a
828: href="HTFormat.html">stream stack builder</a> to determine which stream to
829: plug in to deal with the data. If <code>NULL</code>, then <a
830: href="HTFormat.html#FormatTypes">WWW_PRESENT</a> is default value.</p>
831: <pre>extern void HTRequest_setOutputFormat (HTRequest *request, HTFormat format);
832: extern HTFormat HTRequest_outputFormat (HTRequest *request);</pre>
833:
834: <h3>Has Output Stream been Connected to Channel? (Deprecated)</h3>
835:
836: <p>Has output stream been connected to the channel? If not then we must free
837: it explicitly when deleting the request object</p>
838: <pre>extern void HTRequest_setOutputConnected (HTRequest * request, BOOL mode);
839: extern BOOL HTRequest_outputConnected (HTRequest * request);</pre>
840:
841: <h3>Default Debug Stream</h3>
842:
843: <p>All object bodies sent from the server with status codes different from
844: <code>200 OK</code> will be put down this stream. This can be used for
2.30 frystyk 845: redirecting body information in status codes different from "200 OK" to for
2.69 kirschpi 846: example a debug window. If the value is NULL (default) then the stream is not
847: set up.</p>
848: <pre>extern void HTRequest_setDebugStream (HTRequest *request, HTStream *debug);
849: extern HTStream *HTRequest_debugStream (HTRequest *request);</pre>
850:
851: <h3>Default Debug Stream Format</h3>
852:
853: <p>The desired format of the error stream. This can be used to get
854: unconverted data etc. from the library. The default value if
855: <code>WWW_HTML</code> as a character based only has one WWW_PRESENT.</p>
856: <pre>extern void HTRequest_setDebugFormat (HTRequest *request, HTFormat format);
857: extern HTFormat HTRequest_debugFormat (HTRequest *request);</pre>
858:
859: <h2><a name="context">Context Swapping</a></h2>
860:
861: <p>In multi threaded applications it is often required to keep track of the
2.30 frystyk 862: context of a request so that when the Library returns a result of a request,
863: it can be put into the context it was in before the request was first passed
2.69 kirschpi 864: to the Library. This call back function allows the application to do this.</p>
865: <pre>typedef int HTRequestCallback (HTRequest * request, void *param);
2.1 frystyk 866:
867: extern void HTRequest_setCallback (HTRequest *request, HTRequestCallback *cb);
2.69 kirschpi 868: extern HTRequestCallback *HTRequest_callback (HTRequest *request);</pre>
869:
870: <p>The callback function can be passed an arbitrary pointer (the void part)
2.30 frystyk 871: which can describe the context of the current request structure. If such
2.69 kirschpi 872: context information is required then it can be set using the following
873: methods:</p>
874: <pre>extern void HTRequest_setContext (HTRequest *request, void *context);
875: extern void *HTRequest_context (HTRequest *request);</pre>
876:
877: <h2><a name="FullURI">Should we Issue a full HTTP Request-URI?</a></h2>
878:
879: <p>In early versions of HTTP, the request sent to the remote server varies
880: whether we use a proxy or go directly to the origin server. The default value
881: is <em>OFF</em> but we use a full request if we are talking to a proxy
882: server.</p>
883: <pre>extern void HTRequest_setFullURI (HTRequest *request, BOOL mode);
884: extern BOOL HTRequest_fullURI (HTRequest *request);</pre>
885:
886: <h2><a name="Proxies">Handling Proxies</a></h2>
887:
888: <p>In case we are using a proxy for this requst then we can register it
889: together with the request object. That way we can find the proxy and look for
890: authentication information, for example in the <a
891: href="HTAAUtil.html">Authentication filter</a>. The string is freed by the
892: Request object on deletion. This is normally handled automatically by the <a
893: href="HTProxy.html">proxy and gateway module</a></p>
894: <pre>extern BOOL HTRequest_setProxy (HTRequest * request, const char * proxy);
2.43 frystyk 895: extern char * HTRequest_proxy (HTRequest * request);
2.69 kirschpi 896: extern BOOL HTRequest_deleteProxy (HTRequest * request);</pre>
897:
898: <p></p>
899:
900: <h2>Message Body Manipulation</h2>
901:
902: <p>An application may use these functions to set and manipulate the request
903: message body. This message body is specially indicate for methods that use
2.71 ! kirschpi 904: small XML message bodies. Once the application defines it, this message body
2.69 kirschpi 905: will be send just after the headers. It <strong> does not</strong> use
906: "<strong>Expect: 100-continue</strong>" header, and the application
907: <strong>should not</strong> try to use both. It's important to remark that
908: "Expect: 100-continue" header is a very importante feature defined in HTTP.
2.71 ! kirschpi 909: It's prevents that, for example, the server must read many unnecessary bytes
2.69 kirschpi 910: from request body. Using "Expect: 100-continue" header, your application
911: safes time and network (see <a
912: href="http://www.ietf.org/rfc/rfc2616.txt">RFC2616</a>, section 8.2.3).
913: Please, if possible, use always HTRequest Entity and entity callback, leave
914: this only for small XML bodies in extension methods (see <a
2.71 ! kirschpi 915: href="HTMethod.html">HTMethod</a>), and when using it, <strong>be very
2.69 kirschpi 916: careful</strong>!</p>
917:
918: <p>When using a message body, the application may define its length and
2.71 ! kirschpi 919: format. If the message body is set and its length is also set and it greater
! 920: than 0, a Content-Lenght header will be added to the request. Similarly, if
! 921: the message body and its type are set, a Content-Type header will be added
! 922: to the request too. Otherwise, those headers will not be included.</p>
2.69 kirschpi 923:
924: <p><strong>Note</strong>: The caller should free the string returned by
925: HTRequest_messageBody function!</p>
2.70 kirschpi 926: <pre>
2.69 kirschpi 927: extern BOOL HTRequest_setMessageBody (HTRequest * request, const char * body);
928: extern BOOL HTRequest_deleteMessageBody (HTRequest * request);
929: extern char * HTRequest_messageBody (HTRequest * request);
930:
931: extern BOOL HTRequest_setMessageBodyLength (HTRequest * request, long int length);
932: extern long int HTRequest_messageBodyLength (HTRequest * request);
933:
934: extern BOOL HTRequest_setMessageBodyFormat (HTRequest * request, HTFormat format);
935: extern HTFormat HTRequest_messageBodyFormat (HTRequest * request);
936:
2.70 kirschpi 937: </pre>
2.69 kirschpi 938:
939: <p></p>
940:
941: <p></p>
942:
943: <h2><a name="Count">Bytes Read or Written in a Request</a></h2>
944:
945: <p>This function returns the bytes read in the current request. For a deeper
2.30 frystyk 946: description of what the current request is, please read the user's guide.
2.69 kirschpi 947: This function can be used in for example the <a href="HTAlert.html">HTAlert
948: module</a> to give the number of bytes read or written in a progress
949: message.</p>
950: <pre>extern long HTRequest_bodyRead (HTRequest * request);
951: extern long HTRequest_bodyWritten (HTRequest * request);</pre>
952:
953: <p>You can also get the total number of bytes read or written including the
954: headers</p>
955: <pre>extern long HTRequest_bytesRead (HTRequest * request);
956: extern long HTRequest_bytesWritten (HTRequest * request);</pre>
957: <pre>#endif /* HTREQ_H */</pre>
958:
959: <p></p>
960: <hr>
961: <address>
2.71 ! kirschpi 962: @(#) $Id: HTReq.html,v 2.70 2002/05/29 16:09:13 kirschpi Exp $
2.69 kirschpi 963: </address>
964: </body>
965: </html>
Webmaster
![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to HTReq.html CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [Public] / libwww / Library / src