Annotation of libwww/Library/src/HTReq.html, revision 2.39
2.1 frystyk 1: <HTML>
2: <HEAD>
2.39 ! 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>
262: Max number of Retrys for a Down Load
263: </H2>
264: <P>
2.1 frystyk 265: Automatic reload can happen in two situations:
266: <UL>
2.30 frystyk 267: <LI>
268: The server sends a redirection response
269: <LI>
270: The document has expired
2.1 frystyk 271: </UL>
2.30 frystyk 272: <P>
273: In order to avoid the Library going into an infinite loop, it is necessary
274: to keep track of the number of automatic reloads. Loops can occur if the
275: server has a reload to the same document or if the server sends back a Expires
276: header which has already expired. The default maximum number of automatic
277: reloads is 6.
2.1 frystyk 278: <PRE>
279: extern BOOL HTRequest_setMaxRetry (int newmax);
280: extern int HTRequest_maxRetry (void);
281: extern BOOL HTRequest_retry (HTRequest *request);
282: </PRE>
2.30 frystyk 283: <H2>
284: Retry Request After
285: </H2>
286: <P>
287: Some services, for example HTTP, can in case they are unavailable at the
288: time the request is issued send back a time and date stamp to the client
289: telling when they are expected to back online. In case a request results
290: in a HT_RETRY status, the application can use any time indicated in this
291: field to retry the request at a later time. The Library does not initiate
292: any request on its own - it's for the application to do. The time returned
293: by this function is in calendar time or -1 if not available.
2.1 frystyk 294: <PRE>
295: extern time_t HTRequest_retryTime (HTRequest * request);
296: </PRE>
2.30 frystyk 297: <H2>
298: Accept Headers
299: </H2>
300: <P>
301: The Accept family of headers is an important part of HTTP handling the format
302: negotiation. The Library supports both a global set of accept headers that
303: are used in <EM>all</EM> HTTP requests and a local set of accept headers
304: that are used in specific requests only. The global ones are defined in the
305: <A HREF="HTFormat.html">Format Manager</A>.
306: <P>
307: Each request can have its local set of accept headers that either are added
308: to the global set or replaces the global set of accept headers. Non of the
309: headers <EM>have</EM> to be set. If the global set is sufficient for all
310: requests then this us perfectly fine. If the parameter "override" is set
311: then only local accept headers are used, else <EM>both</EM> local and global
312: headers are used.
313: <H3>
314: Content Types
315: </H3>
316: <P>
317: The <EM>local</EM> list of specific conversions which the format manager
318: can do in order to fulfill the request. It typically points to a list set
319: up on initialisation time for example by <A HREF="HTInit.html">HTInit()</A>.
320: There is also a <A HREF="HTFormat.html#z17"><EM>global</EM></A> list of
321: conversions which contains a generic set of possible conversions.
2.1 frystyk 322: <PRE>
2.8 frystyk 323: extern void HTRequest_setConversion (HTRequest *request, HTList *type, BOOL override);
324: extern HTList * HTRequest_conversion (HTRequest *request);
2.1 frystyk 325: </PRE>
2.30 frystyk 326: <H3>
327: Content Encodings
328: </H3>
329: <P>
2.1 frystyk 330: The list of encodings acceptable in the output stream.
331: <PRE>
332: extern void HTRequest_setEncoding (HTRequest *request, HTList *enc, BOOL override);
333: extern HTList * HTRequest_encoding (HTRequest *request);
334: </PRE>
2.30 frystyk 335: <H3>
336: Content Transfer Encodings
337: </H3>
338: <P>
2.28 frystyk 339: The list of transfer encodings acceptable in the output stream.
340: <PRE>
341: extern void HTRequest_setTransfer (HTRequest *request, HTList *cte, BOOL override);
342: extern HTList * HTRequest_transfer (HTRequest *request);
343: </PRE>
2.30 frystyk 344: <H3>
345: Content Languages
346: </H3>
347: <P>
2.1 frystyk 348: The list of (human) language values acceptable in the response. The default
349: is all languages.
350: <PRE>
351: extern void HTRequest_setLanguage (HTRequest *request, HTList *lang, BOOL override);
352: extern HTList * HTRequest_language (HTRequest *request);
353: </PRE>
2.30 frystyk 354: <H3>
355: Content Charsets
356: </H3>
357: <P>
2.1 frystyk 358: The list of charsets accepted by the application
359: <PRE>
360: extern void HTRequest_setCharset (HTRequest *request, HTList *charset, BOOL override);
361: extern HTList * HTRequest_charset (HTRequest *request);
362: </PRE>
2.30 frystyk 363: <H2>
364: Handling Metainformation (RFC822 Headers)
365: </H2>
366: <P>
367: The Library supports a large set of headers that can be sent along with a
368: request (or a response for that matter). All headers can be either disabled
369: or enabled using bit flags that are defined in the following.
370: <H3>
371: <A NAME="gnhd">General HTTP Header Mask</A>
372: </H3>
373: <P>
374: There are a few header fields which have general applicability for both request
375: and response mesages, but which do not apply to the communication parties
376: or theentity being transferred. This mask enables and disables these headers.
377: If the bit is not turned on they are not sent. All headers are optional and
378: the default value is <EM>NO GENERAL HEADERS</EM>
2.1 frystyk 379: <PRE>
380: typedef enum _HTGnHd {
2.16 frystyk 381: HT_G_DATE = 0x1,
382: HT_G_FORWARDED = 0x2,
383: HT_G_MESSAGE_ID = 0x4,
384: HT_G_MIME = 0x8,
385: HT_G_CONNECTION = 0x10,
2.38 frystyk 386: HT_G_PRAGMA_NO_CACHE= 0x20
2.1 frystyk 387: } HTGnHd;
388:
2.16 frystyk 389: #define DEFAULT_GENERAL_HEADERS HT_G_CONNECTION
2.1 frystyk 390:
391: extern void HTRequest_setGnHd (HTRequest *request, HTGnHd gnhd);
392: extern void HTRequest_addGnHd (HTRequest *request, HTGnHd gnhd);
393: extern HTGnHd HTRequest_gnHd (HTRequest *request);
394: </PRE>
2.30 frystyk 395: <H3>
396: <A NAME="rqhd">Request Headers</A>
397: </H3>
398: <P>
399: The request header fields allow the client to pass additional information
400: about the request (and about the client itself) to the server. All headers
401: are optional but the default value is all request headers if present
402: <EM>except</EM> <CODE>From</CODE> and <CODE>Pragma</CODE>.
2.1 frystyk 403: <PRE>
404: typedef enum _HTRqHd {
2.16 frystyk 405: HT_C_ACCEPT_TYPE = 0x1,
406: HT_C_ACCEPT_CHAR = 0x2,
407: HT_C_ACCEPT_ENC = 0x4,
408: HT_C_ACCEPT_LAN = 0x8,
2.37 frystyk 409: HT_C_AUTH = 0x10,
410: HT_C_FROM = 0x20,
2.16 frystyk 411: HT_C_HOST = 0x40,
2.37 frystyk 412: HT_C_IMS = 0x80,
413: HT_C_IF_MATCH = 0x100,
414: HT_C_IF_NONE_MATCH = 0x200,
415: HT_C_IF_RANGE = 0x400,
416: HT_C_IF_UNMOD_SINCE = 0x800,
417: HT_C_MAX_FORWARDS = 0x1000,
418: HT_C_PROXY_AUTH = 0x2000,
419: HT_C_RANGE = 0x4000,
420: HT_C_REFERER = 0x8000,
421: HT_C_USER_AGENT = 0x10000
2.1 frystyk 422: } HTRqHd;
423:
2.16 frystyk 424: #define DEFAULT_REQUEST_HEADERS \
2.37 frystyk 425: HT_C_ACCEPT_TYPE + HT_C_ACCEPT_CHAR + \
426: HT_C_ACCEPT_ENC + HT_C_ACCEPT_LAN + HT_C_AUTH + \
427: HT_C_HOST + HT_C_REFERER + HT_C_USER_AGENT
2.1 frystyk 428:
429: extern void HTRequest_setRqHd (HTRequest *request, HTRqHd rqhd);
430: extern void HTRequest_addRqHd (HTRequest *request, HTRqHd rqhd);
431: extern HTRqHd HTRequest_rqHd (HTRequest *request);
432: </PRE>
2.30 frystyk 433: <H3>
434: <A NAME="rshd">Response Headers</A>
435: </H3>
436: <P>
437: The response header fields allow the server to pass additional information
438: about the response (and about the server itself) to the client. All headers
439: are optional.
2.16 frystyk 440: <PRE>
441: typedef enum _HTRsHd {
2.37 frystyk 442: HT_S_AGE = 0x1,
443: HT_S_LOCATION = 0x2,
444: HT_S_PROXY_AUTH = 0x4,
445: HT_S_PUBLIC = 0x8,
446: HT_S_RETRY_AFTER = 0x10,
447: HT_S_SERVER = 0x20,
448: HT_S_VARY = 0x40,
449: HT_S_WARNING = 0x80,
450: HT_S_WWW_AUTH = 0x100
2.16 frystyk 451: } HTRsHd;
452:
453: #define DEFAULT_RESPONSE_HEADERS HT_S_SERVER
454:
455: extern void HTRequest_setRsHd (HTRequest * request, HTRsHd rshd);
456: extern void HTRequest_addRsHd (HTRequest * request, HTRsHd rshd);
2.17 frystyk 457: extern HTRsHd HTRequest_rsHd (HTRequest * request);
2.16 frystyk 458: </PRE>
2.30 frystyk 459: <H3>
460: <A NAME="enhd">Entity Header Mask</A>
461: </H3>
462: <P>
463: The entity headers contain information about the object sent in the HTTP
464: transaction. See the <A HREF="HTAnchor.html">Anchor module</A>, for the storage
465: of entity headers. This flag defines which headers are to be sent in a request
466: together with an entity body. All headers are optional but the default value
467: is <EM>ALL ENTITY HEADERS IF PRESENT</EM>
2.1 frystyk 468: <PRE>
469: typedef enum _HTEnHd {
2.37 frystyk 470: HT_E_ALLOW = 0x1,
471: HT_E_CONTENT_BASE = 0x2,
472: HT_E_CONTENT_ENCODING = 0x4,
473: HT_E_CONTENT_LANGUAGE = 0x8,
474: HT_E_CONTENT_LENGTH = 0x10,
475: HT_E_CONTENT_LOCATION = 0x20,
476: HT_E_CONTENT_MD5 = 0x40,
477: HT_E_CONTENT_RANGE = 0x80,
478: HT_E_CTE = 0x100, /* Content-Transfer-Encoding */
479: HT_E_CONTENT_TYPE = 0x200,
480: HT_E_DERIVED_FROM = 0x400,
481: HT_E_ETAG = 0x800,
482: HT_E_EXPIRES = 0x1000,
483: HT_E_LAST_MODIFIED = 0x2000,
484: HT_E_LINK = 0x4000,
485: HT_E_TITLE = 0x8000,
486: HT_E_URI = 0x10000,
487: HT_E_VERSION = 0x20000
2.1 frystyk 488: } HTEnHd;
489:
490: #define DEFAULT_ENTITY_HEADERS 0xFFFF /* all */
491:
492: extern void HTRequest_setEnHd (HTRequest *request, HTEnHd enhd);
493: extern void HTRequest_addEnHd (HTRequest *request, HTEnHd enhd);
494: extern HTEnHd HTRequest_enHd (HTRequest *request);
495: </PRE>
2.30 frystyk 496: <H3>
497: Referer Field
498: </H3>
499: <P>
500: If this parameter is set then a `Referer: <parent address> can be generated
501: in the request to the server, see
502: <A HREF="http://www.w3.org/pub/WWW/Protocols/">Referer field in a HTTP
2.7 frystyk 503: Request</A>
2.1 frystyk 504: <PRE>
505: extern void HTRequest_setParent (HTRequest *request, HTParentAnchor *parent);
506: extern HTParentAnchor * HTRequest_parent (HTRequest *request);
507: </PRE>
2.30 frystyk 508: <H3>
509: Extra Headers
510: </H3>
511: <P>
512: Extra header information can be send along with a request using this variable.
513: The text is sent as is so it must be preformatted with <CRLF> line
514: terminators. This will get changed at some point so that you can register
515: a header together with a handler in the MIME parser.
516: <PRE>
2.34 eric 517: extern void HTRequest_setGenerator (HTRequest *request, HTList *gens,
518: BOOL override);
2.30 frystyk 519: extern HTList * HTRequest_generator (HTRequest *request, BOOL *override);
2.34 eric 520: </PRE>
2.37 frystyk 521: <P>
522: MIMEParsers get their own type which is optimized for static and regex parser
523: strings.
2.34 eric 524: <PRE>
525: typedef struct _HTMIMEParseSet HTMIMEParseSet;
526: extern void HTRequest_setMIMEParseSet (HTRequest *request,
527: HTMIMEParseSet * parseSet, BOOL local);
528: extern HTMIMEParseSet * HTRequest_MIMEParseSet (HTRequest *request,
529: BOOL * pLocal);
530: </PRE>
2.30 frystyk 531: <H2>
532: Sending data to the Network
533: </H2>
534: <P>
2.33 frystyk 535: Multiple Request objects can be connected in order to create a
536: <A HREF="../User/Architecture/PostWeb.html">PostWeb</A> for sending data
537: from one location (source) to another (destination). Request objects are
538: bound together by connecting the output stream of the source with the input
539: stream of the destination requst. The connection can be done directly so
540: that the output from the source is exactly what is sent to the destination
541: or there can be a conversion between the two streams so that we can do
542: conversions on the fly while copying data. This is in fact the way we use
543: for building a proxy server.
544: <P>
2.30 frystyk 545: The Library supports two ways of posting a data object to a remote destination:
546: Input comes from a socket descriptor or from memory. In the case where you
547: want to <EM>copy</EM> a URL, for example from local file system <EM>or</EM>
548: from a remote HTTP server then you must use the
2.33 frystyk 549: <A HREF="../User/Architecture/PostWeb.html">PostWeb design</A>. This model
2.30 frystyk 550: operates by using at least two request objects which gets linked to eachother
2.33 frystyk 551: as part of the PostWeb model. However, if you are posting from memory, we
2.30 frystyk 552: only use <EM>one</EM> request object to perform the operation. In order to
553: do this, the application must register a callback function that can be called
554: when the <A HREF="HTTP.c">HTTP client module</A> is ready for accepting data.
555: be included as part of the body and/or as extra metainformation. In the latter
556: case you need to register a callback function of the following type using
557: the methods provided in the next section.
2.9 frystyk 558: <PRE>
2.21 frystyk 559: typedef int HTPostCallback (HTRequest * request, HTStream * target);
2.33 frystyk 560:
561: extern void HTRequest_setPostCallback (HTRequest * request, HTPostCallback * cbf);
562: extern HTPostCallback * HTRequest_postCallback (HTRequest * request);
2.9 frystyk 563: </PRE>
2.39 ! frystyk 564:
! 565: The Entity Anchor is either the anchor directly associated with the
! 566: Request object or the post anchor associated with the object. The
! 567: purpose of the entity anchor is if we are to send data to a remote
! 568: server then we get the metainformation using the entity anchor.
! 569:
! 570: <PRE>
! 571: extern BOOL HTRequest_setEntityAnchor (HTRequest * request, HTParentAnchor * anchor);
! 572: extern HTParentAnchor * HTRequest_entityAnchor (HTRequest * request);
! 573: </PRE>
! 574:
2.30 frystyk 575: <H3>
576: Input Stream
577: </H3>
578: <P>
579: The input stream is to be used to put data <EM>to</EM> the network. Normally
580: each protocol sets the input stream in order to generate the protocol headers
581: while making a request.
2.27 frystyk 582: <PRE>
583: extern void HTRequest_setInputStream (HTRequest * request, HTStream * input);
584: extern HTStream *HTRequest_inputStream (HTRequest * request);
585: </PRE>
2.33 frystyk 586: <H3>
587: Is This Request part of a Post Web?
588: </H3>
589: <P>
590: Check to see if this request object is part of a Post Web.
591: <PRE>
592: extern BOOL HTRequest_isPostWeb (HTRequest * request);
593: </PRE>
594: <H3>
595: Source of a Request
596: </H3>
597: <P>
598: A request may have a source in which is another request object that as output
599: stream has the input stream of this request object.
600: <PRE>
601: extern BOOL HTRequest_setSource (HTRequest * request, HTRequest * source);
602: extern HTRequest * HTRequest_source (HTRequest * request);
603: </PRE>
2.30 frystyk 604: <H2>
605: Streams From Network to Application
606: </H2>
607: <H3>
608: Default Output Stream
609: </H3>
610: <P>
2.1 frystyk 611: The output stream is to be used to put data down to as they come in
2.30 frystyk 612: <B>from</B> the network and back to the application. The default value is
613: <CODE>NULL</CODE> which means that the stream goes to the user (display).
2.1 frystyk 614: <PRE>
615: extern void HTRequest_setOutputStream (HTRequest *request, HTStream *output);
2.6 frystyk 616: extern HTStream *HTRequest_outputStream (HTRequest *request);
2.1 frystyk 617: </PRE>
2.37 frystyk 618: <H3>
619: Has Output Stream been Connected to Channel?
620: </H3>
621: <P>
622: Has output stream been connected to the channel? If not then we must free
623: it explicitly when deleting the request object
624: <PRE>extern void HTRequest_setOutputConnected (HTRequest * request, BOOL mode);
625: extern BOOL HTRequest_outputConnected (HTRequest * request);
626: </PRE>
2.30 frystyk 627: <P>
628: The desired format of the output stream. This can be used to get unconverted
629: data etc. from the library. If <CODE>NULL</CODE>, then
630: <A HREF="HTFormat.html#FormatTypes">WWW_PRESENT</A> is default value.
2.1 frystyk 631: <PRE>
632: extern void HTRequest_setOutputFormat (HTRequest *request, HTFormat format);
2.6 frystyk 633: extern HTFormat HTRequest_outputFormat (HTRequest *request);
2.1 frystyk 634: </PRE>
2.30 frystyk 635: <H3>
636: Debug Stream
637: </H3>
638: <P>
639: All object bodies sent from the server with status codes different from
640: <CODE>200 OK</CODE> will be put down this stream. This can be used for
641: redirecting body information in status codes different from "200 OK" to for
642: example a debug window. If the value is NULL (default) then the stream is
643: not set up.
2.1 frystyk 644: <PRE>
645: extern void HTRequest_setDebugStream (HTRequest *request, HTStream *debug);
2.6 frystyk 646: extern HTStream *HTRequest_debugStream (HTRequest *request);
2.1 frystyk 647: </PRE>
2.30 frystyk 648: <P>
649: The desired format of the error stream. This can be used to get unconverted
650: data etc. from the library. The default value if <CODE>WWW_HTML</CODE> as
651: a character based only has one WWW_PRESENT.
2.1 frystyk 652: <PRE>
653: extern void HTRequest_setDebugFormat (HTRequest *request, HTFormat format);
2.6 frystyk 654: extern HTFormat HTRequest_debugFormat (HTRequest *request);
2.1 frystyk 655: </PRE>
2.33 frystyk 656: <H2>
657: <A NAME="before">Net before and after calls</A>
658: </H2>
2.30 frystyk 659: <P>
2.33 frystyk 660: The request object may have it's own before and after callbacks. These may
661: override or suplement the global set in <A HREF="HTNet.html">HTNet</A>.
2.26 hallam 662: <PRE>
663: extern void HTRequest_setBefore (HTRequest *request, HTList *befores,
664: BOOL override);
665: extern HTList * HTRequest_before (HTRequest *request, BOOL *override);
666: extern void HTRequest_setAfter (HTRequest *request, HTList *afters,
667: BOOL override);
668: extern HTList * HTRequest_after (HTRequest *request, BOOL *override);
669: </PRE>
2.30 frystyk 670: <H2>
671: <A NAME="context">Context Swapping</A>
672: </H2>
673: <P>
674: In multi threaded applications it is often required to keep track of the
675: context of a request so that when the Library returns a result of a request,
676: it can be put into the context it was in before the request was first passed
677: to the Library. This call back function allows the application to do this.
2.1 frystyk 678: <PRE>
679: typedef int HTRequestCallback (HTRequest * request, void *param);
680:
681: extern void HTRequest_setCallback (HTRequest *request, HTRequestCallback *cb);
682: extern HTRequestCallback *HTRequest_callback (HTRequest *request);
683: </PRE>
2.30 frystyk 684: <P>
685: The callback function can be passed an arbitrary pointer (the void part)
686: which can describe the context of the current request structure. If such
687: context information is required then it can be set using the following methods:
2.1 frystyk 688: <PRE>
689: extern void HTRequest_setContext (HTRequest *request, void *context);
690: extern void *HTRequest_context (HTRequest *request);
2.20 frystyk 691: </PRE>
2.30 frystyk 692: <H2>
693: Preemptive or Non-preemptive Access
694: </H2>
695: <P>
696: A access scheme is defined with a default for using either preemptive (blocking
697: I/O) or non-premitve (non-blocking I/O). This is basically a result of the
698: implementation of the protocol module itself. However, if non-blocking I/O
699: is the default then some times it is nice to be able to set the mode to blocking
700: instead. For example when loading the first document (the home page) then
701: blocking can be used instead of non-blocking.
2.1 frystyk 702: <PRE>
2.18 frystyk 703: extern void HTRequest_setPreemptive (HTRequest *request, BOOL mode);
704: extern BOOL HTRequest_preemptive (HTRequest *request);
2.1 frystyk 705: </PRE>
2.30 frystyk 706: <H2>
707: Priority Management
708: </H2>
709: <P>
710: The request can be assigned an initial priority which then gets inherited
711: by all HTNet objects and other requests objects created as a result of this
712: one. You can also assign a separate priority to an indicidual HTNet object
713: by using the methods in the <A HREF="HTNet.html">Net manager</A>.
2.9 frystyk 714: <PRE>
715: extern HTPriority HTRequest_priority (HTRequest * request);
716: extern BOOL HTRequest_setPriority (HTRequest * request, HTPriority priority);
2.14 frystyk 717: </PRE>
2.30 frystyk 718: <H2>
719: Binding to an Anchor Object
720: </H2>
721: <P>
2.33 frystyk 722: Every request object has an <A HREF="HTAnchor.html">anchor</A> associated
723: with it. The anchor normally lives until the application terminates but a
724: request object only lives as long as the request is being serviced.
2.30 frystyk 725: <PRE>
726: extern void HTRequest_setAnchor (HTRequest *request, HTAnchor *anchor);
727: extern HTParentAnchor * HTRequest_anchor (HTRequest *request);
728: </PRE>
729: <H2>
2.33 frystyk 730: Binding to a Net Object
2.30 frystyk 731: </H2>
732: <P>
733: If a request is actually going on the net then the <A HREF="HTNet.html">Net
2.33 frystyk 734: Manager</A> is contacted to handle the request. The Net manager creates a
2.30 frystyk 735: HTNEt object and links it to the Request object. You can get to the HTNet
736: object using the following functions.
2.14 frystyk 737: <PRE>
738: extern HTNet * HTRequest_net (HTRequest * request);
739: extern BOOL HTRequest_setNet (HTRequest * request, HTNet * net);
2.9 frystyk 740: </PRE>
2.30 frystyk 741: <H2>
742: Format Negotiation
743: </H2>
744: <P>
745: When accessing the local file system, the Library is capable of performing
746: content negotioation as described by the HTTP protocol. This is mainly for
747: server applications, but some client applications might also want to use
748: content negotiation when accessing the local file system. This method enables
749: or disables content negotiation - the default value is <EM>ON</EM>.
2.1 frystyk 750: <PRE>
751: extern void HTRequest_setNegotiation (HTRequest *request, BOOL mode);
752: extern BOOL HTRequest_negotiation (HTRequest *request);
753: </PRE>
2.30 frystyk 754: <H2>
2.33 frystyk 755: Should we Issue a full HTTP Request-URI?
2.31 frystyk 756: </H2>
757: <P>
758: In early versions of HTTP, the request sent to the remote server varies whether
759: we use a proxy or go directly to the origin server. The default value is
760: <EM>OFF</EM>.
761: <PRE>
2.32 frystyk 762: extern void HTRequest_setFullURI (HTRequest *request, BOOL mode);
763: extern BOOL HTRequest_fullURI (HTRequest *request);
2.31 frystyk 764: </PRE>
765: <H2>
2.33 frystyk 766: Error Object
2.30 frystyk 767: </H2>
768: <P>
769: Errors are like almost anything kept in lists and a error list can be associated
770: with a request using the following functions. In order to make life easier,
2.33 frystyk 771: there are also some easy mapping functions to the
772: <A HREF="HTError.html">HTError object</A>, so that you can add an error directly
773: to a request object.
2.1 frystyk 774: <PRE>
2.10 frystyk 775: extern HTList * HTRequest_error (HTRequest * request);
776: extern void HTRequest_setError (HTRequest * request, HTList * list);
777: </PRE>
2.30 frystyk 778: <P>
779: These are the cover functions that go directly to the
2.33 frystyk 780: <A HREF="HTError.html">Error Object</A>
2.10 frystyk 781: <PRE>
782: extern BOOL HTRequest_addError (HTRequest * request,
783: HTSeverity severity,
784: BOOL ignore,
785: int element,
786: void * par,
787: unsigned int length,
788: char * where);
789:
790: extern BOOL HTRequest_addSystemError (HTRequest * request,
791: HTSeverity severity,
792: int errornumber,
793: BOOL ignore,
794: char * syscall);
2.1 frystyk 795: </PRE>
2.30 frystyk 796: <H2>
797: Bytes Read or Written in a Request
798: </H2>
799: <P>
800: This function returns the bytes read in the current request. For a deeper
801: description of what the current request is, please read the user's guide.
802: This function can be used in for example the <A HREF="HTAlert.html">HTAlert
803: module</A> to give the number of bytes read or written in a progress message.
2.1 frystyk 804: <PRE>
2.19 frystyk 805: extern long HTRequest_bytesRead (HTRequest * request);
806: extern long HTRequest_bytesWritten (HTRequest * request);
2.1 frystyk 807: </PRE>
2.30 frystyk 808: <H2>
2.33 frystyk 809: Internal Request Objects
2.30 frystyk 810: </H2>
811: <P>
2.33 frystyk 812: The library may under certain circumstances create its own Request objects.
813: These are all handled internal and does not show up on the application side
814: at all.
2.1 frystyk 815: <PRE>
2.33 frystyk 816: extern BOOL HTRequest_setInternal (HTRequest * request, BOOL mode);
817: extern BOOL HTRequest_internal (HTRequest * request);
2.1 frystyk 818: </PRE>
819: <PRE>
820: #endif /* HTREQ_H */
821: </PRE>
2.30 frystyk 822: <P>
823: <HR>
2.27 frystyk 824: <ADDRESS>
2.39 ! frystyk 825: @(#) $Id: HTReq.html,v 2.38 1996/07/08 19:10:54 frystyk Exp $
2.27 frystyk 826: </ADDRESS>
2.30 frystyk 827: </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