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