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