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