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