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