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