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