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