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