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