Annotation of libwww/Library/src/HTReq.html, revision 2.65
2.1 frystyk 1: <HTML>
2: <HEAD>
2.40 frystyk 3: <!-- Changed by: Henrik Frystyk Nielsen, 15-Jul-1996 -->
2.51 frystyk 4: <TITLE>W3C Sample Code 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
2.56 frystyk 57: is a part of the <A HREF="http://www.w3.org/Library/"> W3C Sample Code
2.30 frystyk 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.47 frystyk 74: #include "HTResponse.h"
2.1 frystyk 75: </PRE>
2.30 frystyk 76: <H2>
2.31 frystyk 77: Issuing a Request
2.30 frystyk 78: </H2>
79: <P>
2.65 ! frystyk 80: These are the "<I>basic request methods</I>" provided directly by the Request
! 81: class. This is a very low level API as the caller must have set up the request
! 82: object before passing it to libwww. There are two versions: one for issuing
! 83: client requests and one for issuing server requests. You will probably most
! 84: often use the client version but libwww can in fact also deal with incoming
! 85: connections. You can find many higher level issuing functions in the
! 86: <A HREF="HTAccess.html">HTAccess module</A>. If you like, you can of course
! 87: use this directly!
2.1 frystyk 88: <PRE>
2.9 frystyk 89: extern BOOL HTLoad (HTRequest * request, BOOL recursive);
2.65 ! frystyk 90: extern BOOL HTServe(HTRequest * request, BOOL recursive);
2.1 frystyk 91: </PRE>
2.30 frystyk 92: <H2>
2.33 frystyk 93: Killing a Request
94: </H2>
95: <P>
96: This function kills this particular request, see <A HREF="HTNet.html">HTNet
2.61 frystyk 97: module</A> for a function that kills them all. If you know that you are
2.64 frystyk 98: pipelining requests (typically the case for GUI browsers, robots etc.) then
99: it is often not enough to just kill a single request as the whole pipeline
100: gets affected. Therefore, in that case you MUST call the
101: <TT><A HREF="HTHost.html#Pipeline">HTHost_killPipe</A></TT> function instead,
2.33 frystyk 102: <PRE>
103: extern BOOL HTRequest_kill(HTRequest * request);
104: </PRE>
2.61 frystyk 105: <P>
106: Note that you can get to the HTHost object via the <A HREF="HTNet.html">HTNet
107: object</A> which you can <A HREF="#HTNet">get by calling
108: HTRequest_net(...)</A>.
2.33 frystyk 109: <H2>
2.30 frystyk 110: Creation and Deletion Methods
111: </H2>
112: <P>
113: The request object is intended to live as long as the request is still active,
2.31 frystyk 114: but can be deleted as soon as it has terminated, for example in one of the
2.30 frystyk 115: request termination callback functions as described in the
116: <A HREF="HTNet.html">Net Manager</A>. Only the anchor object stays around
117: after the request itself is terminated.
118: <H3>
119: Create new Object
120: </H3>
121: <P>
122: Creates a new request object with a default set of options -- in most cases
123: it will need some information added which can be done using the methods in
124: this module, but it will work as is for a simple request.
2.1 frystyk 125: <PRE>
126: extern HTRequest * HTRequest_new (void);
2.22 frystyk 127: </PRE>
2.30 frystyk 128: <H3>
129: Clear a Request Object
130: </H3>
131: <P>
132: Clears all protocol specific information so that the request object can be
133: used for another request. It should be use with care as application specific
134: information is <B>not</B> re-initialized. Returns YES if OK, else NO.
2.22 frystyk 135: <PRE>
136: extern BOOL HTRequest_clear (HTRequest * me);
2.1 frystyk 137: </PRE>
2.30 frystyk 138: <H3>
139: Create a duplicate
140: </H3>
141: <P>
142: Creates a new HTRequest object as a duplicate of the src request. Returns
143: YES if OK, else NO
2.14 frystyk 144: <PRE>
145: extern HTRequest * HTRequest_dup (HTRequest * src);
146: </PRE>
2.30 frystyk 147: <H4>
148: Create a duplicate for Internal use
149: </H4>
150: <P>
151: Creates a new HTRequest object as a duplicate of the src request. The difference
152: to the HTRequest_dup function is that we don't copy the error_stack and other
153: information that the application keeps in its copy of the request object.
154: Otherwise it will be freed multiple times. Returns YES if OK, else NO
2.19 frystyk 155: <PRE>
156: extern HTRequest * HTRequest_dupInternal (HTRequest * src);
157: </PRE>
2.30 frystyk 158: <H3>
159: Delete Object
160: </H3>
161: <P>
2.1 frystyk 162: This function deletes the object and cleans up the memory.
163: <PRE>
164: extern void HTRequest_delete (HTRequest * request);
165: </PRE>
2.30 frystyk 166: <H2>
2.47 frystyk 167: Date and Time Stamp when Request was Issued
2.31 frystyk 168: </H2>
169: <P>
2.47 frystyk 170: The start time when the request was issued may be of value to the cache
171: validation mechanism as described by the HTTP/1.1 specification. The value
172: is automatically set when creating the request headers and sending off the
173: request. The time is a local time.
174: <PRE>
175: extern time_t HTRequest_date (HTRequest * request);
176: extern BOOL HTRequest_setDate (HTRequest * request, time_t date);
2.31 frystyk 177: </PRE>
178: <H2>
2.30 frystyk 179: Set the Method for the Request
180: </H2>
181: <P>
182: The Method is the operation to be executed on the requested object. The default
183: set if the set of operations defined by the HTTP protocol, that is "GET",
184: "HEAD", "PUT", "POST", "LINK", "UNLINK", and "DELETE" but many of these can
185: be used in other protocols as well. The important thing is to think of the
186: requested element as an object on which you want to perform an operation.
187: Then it is for the specific protocol implementation to try and carry this
188: operation out. However, not all operations can be implemented (or make sense)
189: in all protocols.
190: <P>
191: Methods are handled by the <A HREF="HTMethod.html">Method Module</A>, and
192: the default value is "GET".
2.1 frystyk 193: <PRE>
194: extern void HTRequest_setMethod (HTRequest *request, HTMethod method);
195: extern HTMethod HTRequest_method (HTRequest *request);
196: </PRE>
2.30 frystyk 197: <H2>
2.47 frystyk 198: Priority Management
2.45 frystyk 199: </H2>
200: <P>
2.47 frystyk 201: The request can be assigned an initial priority which then gets inherited
202: by all HTNet objects and other requests objects created as a result of this
203: one. You can also assign a separate priority to an indicidual HTNet object
204: by using the methods in the <A HREF="HTNet.html">Net manager</A>.
2.46 frystyk 205: <PRE>
2.47 frystyk 206: extern HTPriority HTRequest_priority (HTRequest * request);
207: extern BOOL HTRequest_setPriority (HTRequest * request, HTPriority priority);
2.45 frystyk 208: </PRE>
209: <H2>
2.50 frystyk 210: Pipelining Managament
211: </H2>
212: <P>
213: Libwww supports HTTP/1.1 pipelining which greatly optimizes HTTP's behavior
214: over TCP. libwww also tries very hard to minimize the number of TCP packets
215: sent over the network. This is done by buffering outgoing requests until
216: either a minimum amount of data has been collected or a timeout causes a
217: flush to happen. The application can override the output buffering by explicit
218: request a request object to be flushed.
219: <PRE>
220: extern BOOL HTRequest_setFlush (HTRequest * me, BOOL mode);
221: extern BOOL HTRequest_flush (HTRequest * me);
222: </PRE>
223: <H2>
2.47 frystyk 224: Binding to a User Profile
2.30 frystyk 225: </H2>
226: <P>
2.47 frystyk 227: Each request is associated with a <A HREF="HTUser.html">User profile</A>
228: which contains information about the local host name, email address of the
229: user, news server etc. A request object is created with a default "generic
230: user" but can be assigned a specific user at any time.
2.1 frystyk 231: <PRE>
2.47 frystyk 232: extern BOOL HTRequest_setUserProfile (HTRequest * request, HTUserProfile * up);
233: extern HTUserProfile * HTRequest_userProfile (HTRequest * request);
2.45 frystyk 234: </PRE>
2.30 frystyk 235: <H2>
2.64 frystyk 236: <A NAME="HTNet">Binding to a Net Object</A>
2.30 frystyk 237: </H2>
238: <P>
2.47 frystyk 239: If a request is actually going on the net then the <A HREF="HTNet.html">Net
240: Manager</A> is contacted to handle the request. The Net manager creates a
241: HTNEt object and links it to the Request object. You can get to the HTNet
242: object using the following functions.
2.19 frystyk 243: <PRE>
2.47 frystyk 244: extern HTNet * HTRequest_net (HTRequest * request);
245: extern BOOL HTRequest_setNet (HTRequest * request, HTNet * net);
2.19 frystyk 246: </PRE>
2.61 frystyk 247: <P>
248: Note that you can go from the HTNet object to the
249: <A HREF="HTHost.html">HTHost</A> object by calling <TT>HTNet_host(...)</TT>.
2.30 frystyk 250: <H2>
2.47 frystyk 251: Binding to a Response Object
2.30 frystyk 252: </H2>
253: <P>
2.47 frystyk 254: If a request is actually going on the net and we are getting a response back
255: then we also create a HTResponse object and bind it to the request object.
256: Once we know what to do with the response, we may transfer the information
257: to the anchor object.
2.38 frystyk 258: <PRE>
2.47 frystyk 259: extern HTResponse * HTRequest_response (HTRequest * request);
260: extern BOOL HTRequest_setResponse (HTRequest * request, HTResponse * response);
2.38 frystyk 261: </PRE>
2.30 frystyk 262: <H2>
2.47 frystyk 263: <A NAME="Error">Error Object</A>
2.44 frystyk 264: </H2>
265: <P>
2.47 frystyk 266: Errors are like almost anything kept in lists and a error list can be associated
267: with a request using the following functions. In order to make life easier,
268: there are also some easy mapping functions to the
269: <A HREF="HTError.html">HTError object</A>, so that you can add an error directly
270: to a request object.
2.44 frystyk 271: <PRE>
2.47 frystyk 272: extern HTList * HTRequest_error (HTRequest * request);
273: extern void HTRequest_setError (HTRequest * request, HTList * list);
2.55 frystyk 274: extern void HTRequest_deleteAllErrors (HTRequest * request);
2.45 frystyk 275: </PRE>
276: <P>
2.47 frystyk 277: These are the cover functions that go directly to the
278: <A HREF="HTError.html">Error Object</A>
2.46 frystyk 279: <PRE>
2.47 frystyk 280: extern BOOL HTRequest_addError (HTRequest * request,
281: HTSeverity severity,
282: BOOL ignore,
283: int element,
284: void * par,
285: unsigned int length,
286: char * where);
287:
288: extern BOOL HTRequest_addSystemError (HTRequest * request,
289: HTSeverity severity,
290: int errornumber,
291: BOOL ignore,
292: char * syscall);
2.46 frystyk 293: </PRE>
294: <H2>
295: Max number of Retrys for a Down Load
296: </H2>
2.30 frystyk 297: <P>
2.1 frystyk 298: Automatic reload can happen in two situations:
299: <UL>
2.30 frystyk 300: <LI>
301: The server sends a redirection response
302: <LI>
303: The document has expired
2.1 frystyk 304: </UL>
2.30 frystyk 305: <P>
306: In order to avoid the Library going into an infinite loop, it is necessary
307: to keep track of the number of automatic reloads. Loops can occur if the
308: server has a reload to the same document or if the server sends back a Expires
309: header which has already expired. The default maximum number of automatic
310: reloads is 6.
2.1 frystyk 311: <PRE>
312: extern BOOL HTRequest_setMaxRetry (int newmax);
313: extern int HTRequest_maxRetry (void);
2.41 frystyk 314:
315: extern int HTRequest_retrys (HTRequest * request);
316: extern BOOL HTRequest_doRetry (HTRequest *request);
2.44 frystyk 317: extern BOOL HTRequest_addRetry (HTRequest * request);
2.62 kahan 318:
319: extern int HTRequest_AAretrys (HTRequest * request);
320: extern BOOL HTRequest_addAARetry (HTRequest * request);
2.1 frystyk 321: </PRE>
2.30 frystyk 322: <H2>
2.43 frystyk 323: Set Max Forwards for TRACE methods
324: </H2>
325: <P>
326: The <CODE>TRACE</CODE> method is used to invoke a remote, application-layer
327: loop-back of the request message. The final recipient of the request SHOULD
328: reflect the message received back to the client as the entity-body of a 200
329: (OK) response. The final recipient is either the origin server or the first
330: proxy or gateway to receive a Max-Forwards value of zero (0) in the request.
331: A <CODE>TRACE</CODE> request <I>MUST NOT</I> include an entity.
332: <PRE>extern BOOL HTRequest_setMaxForwards (HTRequest * request, int maxforwards);
333: extern int HTRequest_maxForwards (HTRequest * request);
334: </PRE>
335: <H2>
2.60 frystyk 336: <A NAME="preemptive">Preemptive or Non-preemptive Access</A>
2.46 frystyk 337: </H2>
338: <P>
2.47 frystyk 339: A access scheme is defined with a default for using either preemptive (blocking
340: I/O) or non-premitve (non-blocking I/O). This is basically a result of the
341: implementation of the protocol module itself. However, if non-blocking I/O
342: is the default then some times it is nice to be able to set the mode to blocking
343: instead. For example when loading the first document (the home page) then
344: blocking can be used instead of non-blocking.
2.46 frystyk 345: <PRE>
2.47 frystyk 346: extern void HTRequest_setPreemptive (HTRequest *request, BOOL mode);
347: extern BOOL HTRequest_preemptive (HTRequest *request);
2.46 frystyk 348: </PRE>
349: <H2>
2.47 frystyk 350: Content Negotiation
2.30 frystyk 351: </H2>
352: <P>
2.47 frystyk 353: When accessing the local file system, the Library is capable of performing
354: content negotioation as described by the HTTP protocol. This is mainly for
355: server applications, but some client applications might also want to use
356: content negotiation when accessing the local file system. This method enables
357: or disables content negotiation - the default value is <EM>ON</EM>.
2.1 frystyk 358: <PRE>
2.47 frystyk 359: extern void HTRequest_setNegotiation (HTRequest *request, BOOL mode);
360: extern BOOL HTRequest_negotiation (HTRequest *request);
2.1 frystyk 361: </PRE>
2.30 frystyk 362: <H2>
2.57 frystyk 363: Request Preconditions
364: </H2>
2.64 frystyk 365: <P>
366: Should this request use preconditions when doing a <TT>PUT</TT> or a
367: <TT>POST</TT>? These are the "<TT>if-*</TT>" header fields that can be used
368: to avoid version conflicts etc. The default is not to use any preconsitions
369: (<TT>HT_NO_MATCH</TT>). The <TT>_THIS</TT> versions use etags and/or time
370: stamps and the <TT>_ANY</TT> versions use the "<TT>*</TT>" header field value
371: of the <TT>if-match</TT> and <TT>if-non-match</TT> header fields.
372: <PRE>typedef enum _HTPreconditions {
373: HT_NO_MATCH = 0,
374: HT_MATCH_THIS,
375: HT_MATCH_ANY,
376: HT_DONT_MATCH_THIS,
377: HT_DONT_MATCH_ANY
378: } HTPreconditions;
379:
380: extern void HTRequest_setPreconditions (HTRequest * me, HTPreconditions mode);
381: extern HTPreconditions HTRequest_preconditions (HTRequest * me);
2.57 frystyk 382: </PRE>
383: <H2>
2.30 frystyk 384: Handling Metainformation (RFC822 Headers)
385: </H2>
386: <P>
387: The Library supports a large set of headers that can be sent along with a
388: request (or a response for that matter). All headers can be either disabled
389: or enabled using bit flags that are defined in the following.
390: <H3>
391: <A NAME="gnhd">General HTTP Header Mask</A>
392: </H3>
393: <P>
394: There are a few header fields which have general applicability for both request
395: and response mesages, but which do not apply to the communication parties
396: or theentity being transferred. This mask enables and disables these headers.
2.54 frystyk 397: If the bit is not turned on they are not sent.
2.1 frystyk 398: <PRE>
399: typedef enum _HTGnHd {
2.45 frystyk 400: HT_G_CC = 0x1,
401: HT_G_CONNECTION = 0x2,
402: HT_G_DATE = 0x4,
403: HT_G_PRAGMA_NO_CACHE= 0x8,
404: HT_G_FORWARDED = 0x10,
405: HT_G_MESSAGE_ID = 0x20,
2.53 frystyk 406: HT_G_MIME = 0x40,
2.54 frystyk 407: HT_G_TRAILER = 0x80,
408: HT_G_TRANSFER = 0x100
2.1 frystyk 409: } HTGnHd;
410:
2.54 frystyk 411: #define DEFAULT_GENERAL_HEADERS \
412: HT_G_CONNECTION + HT_G_CC + HT_G_TRANSFER + HT_G_TRAILER
2.1 frystyk 413:
414: extern void HTRequest_setGnHd (HTRequest *request, HTGnHd gnhd);
415: extern void HTRequest_addGnHd (HTRequest *request, HTGnHd gnhd);
416: extern HTGnHd HTRequest_gnHd (HTRequest *request);
417: </PRE>
2.30 frystyk 418: <H3>
419: <A NAME="rqhd">Request Headers</A>
420: </H3>
421: <P>
422: The request header fields allow the client to pass additional information
423: about the request (and about the client itself) to the server. All headers
424: are optional but the default value is all request headers if present
425: <EM>except</EM> <CODE>From</CODE> and <CODE>Pragma</CODE>.
2.1 frystyk 426: <PRE>
427: typedef enum _HTRqHd {
2.16 frystyk 428: HT_C_ACCEPT_TYPE = 0x1,
429: HT_C_ACCEPT_CHAR = 0x2,
430: HT_C_ACCEPT_ENC = 0x4,
2.53 frystyk 431: HT_C_ACCEPT_TE = 0x8,
432: HT_C_ACCEPT_LAN = 0x10,
433: HT_C_AUTH = 0x20, /* Includes proxy authentication */
434: HT_C_EXPECT = 0x40,
435: HT_C_FROM = 0x80,
436: HT_C_HOST = 0x100,
437: HT_C_IMS = 0x200,
438: HT_C_IF_MATCH = 0x400,
2.64 frystyk 439: HT_C_IF_MATCH_ANY = 0x800,
2.63 frystyk 440: HT_C_IF_NONE_MATCH = 0x1000,
2.64 frystyk 441: HT_C_IF_NONE_MATCH_ANY=0x2000,
2.63 frystyk 442: HT_C_IF_RANGE = 0x4000,
443: HT_C_IF_UNMOD_SINCE = 0x8000,
444: HT_C_MAX_FORWARDS = 0x10000,
445: HT_C_RANGE = 0x20000,
446: HT_C_REFERER = 0x40000,
447: HT_C_USER_AGENT = 0x80000
2.1 frystyk 448: } HTRqHd;
449:
2.16 frystyk 450: #define DEFAULT_REQUEST_HEADERS \
2.37 frystyk 451: HT_C_ACCEPT_TYPE + HT_C_ACCEPT_CHAR + \
2.53 frystyk 452: HT_C_ACCEPT_ENC + HT_C_ACCEPT_TE + HT_C_ACCEPT_LAN + HT_C_AUTH + \
453: HT_C_EXPECT + HT_C_HOST + HT_C_REFERER + HT_C_USER_AGENT
2.1 frystyk 454:
455: extern void HTRequest_setRqHd (HTRequest *request, HTRqHd rqhd);
456: extern void HTRequest_addRqHd (HTRequest *request, HTRqHd rqhd);
457: extern HTRqHd HTRequest_rqHd (HTRequest *request);
458: </PRE>
2.30 frystyk 459: <H3>
460: <A NAME="rshd">Response Headers</A>
461: </H3>
462: <P>
463: The response header fields allow the server to pass additional information
464: about the response (and about the server itself) to the client. All headers
465: are optional.
2.16 frystyk 466: <PRE>
467: typedef enum _HTRsHd {
2.37 frystyk 468: HT_S_AGE = 0x1,
469: HT_S_LOCATION = 0x2,
470: HT_S_PROXY_AUTH = 0x4,
471: HT_S_PUBLIC = 0x8,
472: HT_S_RETRY_AFTER = 0x10,
473: HT_S_SERVER = 0x20,
474: HT_S_VARY = 0x40,
475: HT_S_WARNING = 0x80,
2.53 frystyk 476: HT_S_WWW_AUTH = 0x100,
477: HT_S_TRAILER = 0x200
2.16 frystyk 478: } HTRsHd;
479:
480: #define DEFAULT_RESPONSE_HEADERS HT_S_SERVER
481:
482: extern void HTRequest_setRsHd (HTRequest * request, HTRsHd rshd);
483: extern void HTRequest_addRsHd (HTRequest * request, HTRsHd rshd);
2.17 frystyk 484: extern HTRsHd HTRequest_rsHd (HTRequest * request);
2.16 frystyk 485: </PRE>
2.30 frystyk 486: <H3>
487: <A NAME="enhd">Entity Header Mask</A>
488: </H3>
489: <P>
490: The entity headers contain information about the object sent in the HTTP
491: transaction. See the <A HREF="HTAnchor.html">Anchor module</A>, for the storage
492: of entity headers. This flag defines which headers are to be sent in a request
493: together with an entity body. All headers are optional but the default value
494: is <EM>ALL ENTITY HEADERS IF PRESENT</EM>
2.1 frystyk 495: <PRE>
496: typedef enum _HTEnHd {
2.37 frystyk 497: HT_E_ALLOW = 0x1,
498: HT_E_CONTENT_BASE = 0x2,
499: HT_E_CONTENT_ENCODING = 0x4,
500: HT_E_CONTENT_LANGUAGE = 0x8,
501: HT_E_CONTENT_LENGTH = 0x10,
502: HT_E_CONTENT_LOCATION = 0x20,
503: HT_E_CONTENT_MD5 = 0x40,
504: HT_E_CONTENT_RANGE = 0x80,
505: HT_E_CTE = 0x100, /* Content-Transfer-Encoding */
506: HT_E_CONTENT_TYPE = 0x200,
507: HT_E_DERIVED_FROM = 0x400,
508: HT_E_ETAG = 0x800,
509: HT_E_EXPIRES = 0x1000,
510: HT_E_LAST_MODIFIED = 0x2000,
511: HT_E_LINK = 0x4000,
512: HT_E_TITLE = 0x8000,
513: HT_E_URI = 0x10000,
514: HT_E_VERSION = 0x20000
2.1 frystyk 515: } HTEnHd;
516:
517: #define DEFAULT_ENTITY_HEADERS 0xFFFF /* all */
518:
519: extern void HTRequest_setEnHd (HTRequest *request, HTEnHd enhd);
520: extern void HTRequest_addEnHd (HTRequest *request, HTEnHd enhd);
521: extern HTEnHd HTRequest_enHd (HTRequest *request);
522: </PRE>
2.47 frystyk 523: <H2>
524: Local MIME header Parsers
525: </H2>
2.37 frystyk 526: <P>
527: MIMEParsers get their own type which is optimized for static and regex parser
528: strings.
2.34 eric 529: <PRE>
530: typedef struct _HTMIMEParseSet HTMIMEParseSet;
531: extern void HTRequest_setMIMEParseSet (HTRequest *request,
532: HTMIMEParseSet * parseSet, BOOL local);
533: extern HTMIMEParseSet * HTRequest_MIMEParseSet (HTRequest *request,
534: BOOL * pLocal);
535: </PRE>
2.30 frystyk 536: <H2>
2.48 frystyk 537: <A NAME="Accept">Accept Headers</A>
2.47 frystyk 538: </H2>
539: <P>
540: The Accept family of headers is an important part of HTTP handling the format
541: negotiation. The Library supports both a global set of accept headers that
542: are used in <EM>all</EM> HTTP requests and a local set of accept headers
543: that are used in specific requests only. The global ones are defined in the
544: <A HREF="HTFormat.html">Format Manager</A>.
545: <P>
546: Each request can have its local set of accept headers that either are added
547: to the global set or replaces the global set of accept headers. Non of the
548: headers <EM>have</EM> to be set. If the global set is sufficient for all
549: requests then this us perfectly fine. If the parameter "override" is set
550: then only local accept headers are used, else <EM>both</EM> local and global
551: headers are used.
552: <H3>
553: Content Types
554: </H3>
555: <P>
556: The <EM>local</EM> list of specific conversions which the format manager
557: can do in order to fulfill the request. It typically points to a list set
558: up on initialisation time for example by <A HREF="HTInit.html">HTInit()</A>.
559: There is also a <A HREF="HTFormat.html#z17"><EM>global</EM></A> list of
560: conversions which contains a generic set of possible conversions.
561: <PRE>
562: extern void HTRequest_setConversion (HTRequest *request, HTList *type, BOOL override);
563: extern HTList * HTRequest_conversion (HTRequest *request);
564: </PRE>
565: <H3>
566: Content Encodings
567: </H3>
568: <P>
569: The list of encodings acceptable in the output stream.
570: <PRE>
571: extern void HTRequest_setEncoding (HTRequest *request, HTList *enc, BOOL override);
572: extern HTList * HTRequest_encoding (HTRequest *request);
573: </PRE>
574: <H3>
2.53 frystyk 575: Transfer Encodings
2.47 frystyk 576: </H3>
577: <P>
578: The list of transfer encodings acceptable in the output stream.
579: <PRE>
2.53 frystyk 580: extern void HTRequest_setTransfer (HTRequest *request, HTList *te, BOOL override);
2.47 frystyk 581: extern HTList * HTRequest_transfer (HTRequest *request);
582: </PRE>
583: <H3>
584: Content Languages
585: </H3>
586: <P>
587: The list of (human) language values acceptable in the response. The default
588: is all languages.
589: <PRE>
590: extern void HTRequest_setLanguage (HTRequest *request, HTList *lang, BOOL override);
591: extern HTList * HTRequest_language (HTRequest *request);
592: </PRE>
593: <H3>
594: Content Charsets
595: </H3>
596: <P>
597: The list of charsets accepted by the application
598: <PRE>
599: extern void HTRequest_setCharset (HTRequest *request, HTList *charset, BOOL override);
600: extern HTList * HTRequest_charset (HTRequest *request);
601: </PRE>
602: <H2>
603: HTTP Cache Validation and Cache Control
604: </H2>
605: <P>
606: The Library has two concepts of caching: in memory and on file. When loading
607: a document, this flag can be set in order to define who can give a response
608: to the request. The mempory buffer is considered to be equivalent to a history
609: buffer. That is, it doesn't not follow the same expiration mechanism that
610: is characteristic for a persistent file cache.
611: <P>
612: You can also set the cache to run in disconnected mode - see the
613: <A HREF="HTCache.html">Cache manager</A> for more details on how to do this.
614: <PRE>
615: typedef enum _HTReload {
616: HT_CACHE_OK = 0x0, /* Use any version available */
617: HT_CACHE_FLUSH_MEM = 0x1, /* Reload from file cache or network */
618: HT_CACHE_VALIDATE = 0x2, /* Validate cache entry */
619: HT_CACHE_END_VALIDATE = 0x4, /* End to end validation */
620: HT_CACHE_RANGE_VALIDATE = 0x8,
2.52 frystyk 621: HT_CACHE_FLUSH = 0x10, /* Force full reload */
622: HT_CACHE_ERROR = 0x20 /* An error occurred in the cache */
2.47 frystyk 623: } HTReload;
624:
625: extern void HTRequest_setReloadMode (HTRequest *request, HTReload mode);
626: extern HTReload HTRequest_reloadMode (HTRequest *request);
627: </PRE>
628: <H3>
629: HTTP Cache Control Directives
630: </H3>
631: <P>
632: The cache control directives are all part of the cache control header and
633: control the behavior of any intermediate cache between the user agent and
634: the origin server. This association list is a list of the connection control
635: directives that are to be sent as part of the <CODE>Cache-Control</CODE>
636: header.
637: <PRE>
638: extern BOOL HTRequest_addCacheControl (HTRequest * request,
639: char * token, char *value);
640: extern BOOL HTRequest_deleteCacheControlAll (HTRequest * request);
641: extern HTAssocList * HTRequest_cacheControl (HTRequest * request);
642: </PRE>
2.53 frystyk 643: <H3>
644: HTTP Expect Directives
645: </H3>
2.64 frystyk 646: <P>
647: The Expect request-header field is used to indicate that particular server
648: behaviors are required by the client. A server that does not understand or
649: is unable to comply with any of the expectation values in the Expect field
650: of a request MUST respond with appropriate error status.
2.53 frystyk 651: <PRE>
652: extern BOOL HTRequest_addExpect (HTRequest * me,
653: char * token, char * value);
654: extern BOOL HTRequest_deleteExpect (HTRequest * me);
655: extern HTAssocList * HTRequest_expect (HTRequest * me);
656: </PRE>
2.47 frystyk 657: <H3>
658: Partial Requests and Range Retrievals
659: </H3>
660: <P>
661: Libwww can issue range requests in case we have already obtained a part of
662: the entity body. Since all HTTP entities are represented in HTTP messages
663: as sequences of bytes, the concept of a byte range is meaningful for any
664: HTTP entity. (However, not all clients and servers need to support byte-range
665: operations.) Byte range specifications in HTTP apply to the sequence of bytes
666: in the entity-body (not necessarily the same as the message-body). A byte
667: range operation may specify a single range of bytes, or a set of ranges within
668: a single entity.
669: <PRE>
670: extern BOOL HTRequest_addRange (HTRequest * request,
671: char * unit, char * range);
672: extern BOOL HTRequest_deleteRangeAll (HTRequest * request);
673: extern HTAssocList * HTRequest_range (HTRequest * request);
674: </PRE>
675: <H2>
676: HTTP Connection Control Request Directives
677: </H2>
678: <P>
679: The connection control directives are all part of the connection header and
680: control the behavior of this connection. This association list is a list
681: of the connection control directives that are to be sent as part of the
682: <CODE>Connection</CODE> header.
683: <PRE>
684: extern BOOL HTRequest_addConnection (HTRequest * request,
685: char * token, char * value);
686: extern BOOL HTRequest_deleteConnection (HTRequest * request);
687: extern HTAssocList * HTRequest_connection (HTRequest * request);
688: </PRE>
689: <H2>
690: <A NAME="Access">HTTP Access Authentication Credentials</A>
691: </H2>
692: <P>
693: When a access denied response is returned to the Library, for example from
694: a remote HTTP server, this code is passed back to the application. The
695: application can then decide whether a new request should be established or
696: not. These two methods return the authentication information required to
697: issue a new request, that is the new anchor and any list of keywords associated
698: with this anchor.
699: <PRE>
700: extern BOOL HTRequest_addCredentials (HTRequest * request,
701: char * token, char * value);
702: extern BOOL HTRequest_deleteCredentialsAll (HTRequest * request);
703: extern HTAssocList * HTRequest_credentials (HTRequest * request);
704: </PRE>
705: <H3>
706: Realms
707: </H3>
2.64 frystyk 708: <P>
2.59 frystyk 709: The realm is normally set and used by the authentication filters.
2.47 frystyk 710: <PRE>
711: extern BOOL HTRequest_setRealm (HTRequest * request, char * realm);
712: extern const char * HTRequest_realm (HTRequest * request);
2.59 frystyk 713: extern BOOL HTRequest_deleteRealm (HTRequest * me);
2.47 frystyk 714: </PRE>
715: <H2>
716: HTTP Extensions (PEP)
717: </H2>
718: <P>
719: HTTP can be extended in several ways but traditionally it has been by using
720: new headers. Here we present a new idea which provides a framework for describing
721: extensions and their scope. This is only an idea an may be modified later!
722: The implementation of the extensions can be found in the
723: <A HREF="HTPEP.html">PEP module</A>
724: <H3>
725: Protocol
726: </H3>
727: <P>
728: This association list is a list of the extension directives that are to be
729: sent as part of the request.
730: <PRE>
731: extern BOOL HTRequest_addProtocol (HTRequest * request,
732: char * token, char * value);
733: extern BOOL HTRequest_deleteProtocolAll (HTRequest * request);
734: extern HTAssocList * HTRequest_Protocol (HTRequest * request);
735: </PRE>
736: <H3>
737: Protocol Info
738: </H3>
739: <P>
740: This association list is a list of the extension directives that are to be
741: sent as part of the request.
742: <PRE>
743: extern BOOL HTRequest_addProtocolInfo (HTRequest * request,
744: char * token, char * value);
745: extern BOOL HTRequest_deleteProtocolInfoAll (HTRequest * request);
746: extern HTAssocList * HTRequest_ProtocolInfo (HTRequest * request);
747: </PRE>
748: <H3>
749: Protocol Request
750: </H3>
751: <P>
752: This association list is a list of the extension directives that are to be
753: sent as part of the request.
754: <PRE>
755: extern BOOL HTRequest_addProtocolRequest (HTRequest * request,
756: char * token, char * value);
757: extern BOOL HTRequest_deleteProtocolRequestAll (HTRequest * request);
758: extern HTAssocList * HTRequest_ProtocolRequest (HTRequest * request);
759: </PRE>
760: <H2>
761: HTTP Referer Field
762: </H2>
763: <P>
764: If this parameter is set then a `Referer: <parent address> can be generated
765: in the request to the server, see
2.64 frystyk 766: <A HREF="http://www.w3.org/Protocols/">Referer field in a HTTP Request</A>
2.47 frystyk 767: <PRE>
768: extern void HTRequest_setParent (HTRequest *request, HTParentAnchor *parent);
769: extern HTParentAnchor * HTRequest_parent (HTRequest *request);
770: </PRE>
771: <H2>
772: Extra Headers
773: </H2>
774: <P>
775: Extra header information can be send along with a request using this variable.
776: The text is sent as is so it must be preformatted with
777: <CODE><CRLF></CODE> line terminators. This will get changed at some
778: point so that you can register a header together with a handler in the MIME
779: parser.
780: <PRE>
781: extern void HTRequest_setGenerator (HTRequest *request, HTList *gens,
782: BOOL override);
783: extern HTList * HTRequest_generator (HTRequest *request, BOOL *override);
784: </PRE>
785: <H2>
786: <A NAME="before">BEFORE and AFTER Filters</A>
787: </H2>
788: <P>
789: The request object may have it's own before and after
790: <A HREF="HTFilter.html">filters</A>. These may override or suplement the
791: global set in <A HREF="HTNet.html">HTNet</A>. The request object itself handles
792: the list element, that is this should not be freed bu the caller.
793: <H3>
794: BEFORE Filters
795: </H3>
796: <P>
797: The BEFORE <A HREF="HTFilter.html">filters</A> are called just after the
798: request has been passed to the Library but before any request is issued over
799: the network. A BEFORE can infact stop a request completely from being processed.
800: <H4>
801: Add a local BEFORE Filter
802: </H4>
803: <P>
804: You can add a local <I>BEFORE</I> filter for a single request so that the
805: both the local and global <I>BEFORE</I> filters are called or you can replace
806: the global filters with a local set. Note that the local set can be NULL.
807: This can be used to effectively disable all <I>BEFORE</I> filters without
808: unregistering the global ones.
809: <PRE>
810: extern BOOL HTRequest_addBefore (HTRequest * request, HTNetBefore * filter,
811: const char * tmplate, void * param,
2.48 frystyk 812: HTFilterOrder order, BOOL override);
2.47 frystyk 813: extern HTList * HTRequest_before (HTRequest * request, BOOL * override);
814: </PRE>
815: <H4>
816: Delete a Local BEFORE Filter
817: </H4>
818: <P>
819: You can delete a local BEFORE filter explicitly by passing the filter itself
820: or you can delete all filters which are registered for a certain status code.
821: <PRE>extern BOOL HTRequest_deleteBefore (HTRequest * request, HTNetBefore * filter);
822: extern BOOL HTRequest_deleteBeforeAll (HTRequest * request);
823: </PRE>
824: <H3>
825: AFTER Filters
826: </H3>
827: <P>
828: You can add a local AFTER filter for a single request so that the both the
829: local and global AFTER filters are called or you can replace the global filters
830: with a local set. Note that the local set can be NULL. This can be used to
831: effectively disable all AFTER filters without unregistering the global ones.
832: <P>
833: AFTER filters can be registered to handle a certain set of return values
834: from the protocol modules, for example explicitly to handle redirection,
835: authentication, etc. You can find all the available codes in the HTNet object
836: description.
837: <H4>
838: Add a local AFTER Filter
839: </H4>
840: <PRE>
841: extern BOOL HTRequest_addAfter (HTRequest * request, HTNetAfter * filter,
842: const char * tmplate, void * param,
2.48 frystyk 843: int status, HTFilterOrder order,
844: BOOL override);
2.47 frystyk 845: extern HTList * HTRequest_after (HTRequest * request, BOOL * override);
846: </PRE>
847: <H4>
848: Delete an AFTER Filter
849: </H4>
850: <P>
851: You can delete a local AFTER filter explicitly by passing the filter itself
852: or you can delete all filters which are registered for a certain status code.
853: <PRE>
854: extern BOOL HTRequest_deleteAfter (HTRequest * request, HTNetAfter * filter);
855: extern BOOL HTRequest_deleteAfterStatus (HTRequest * request, int status);
856: extern BOOL HTRequest_deleteAfterAll (HTRequest * request);
857: </PRE>
858: <H2>
859: Sending data to the Network
2.30 frystyk 860: </H2>
861: <P>
2.33 frystyk 862: Multiple Request objects can be connected in order to create a
863: <A HREF="../User/Architecture/PostWeb.html">PostWeb</A> for sending data
864: from one location (source) to another (destination). Request objects are
865: bound together by connecting the output stream of the source with the input
866: stream of the destination requst. The connection can be done directly so
867: that the output from the source is exactly what is sent to the destination
868: or there can be a conversion between the two streams so that we can do
869: conversions on the fly while copying data. This is in fact the way we use
870: for building a proxy server.
871: <P>
2.30 frystyk 872: The Library supports two ways of posting a data object to a remote destination:
873: Input comes from a socket descriptor or from memory. In the case where you
874: want to <EM>copy</EM> a URL, for example from local file system <EM>or</EM>
875: from a remote HTTP server then you must use the
2.33 frystyk 876: <A HREF="../User/Architecture/PostWeb.html">PostWeb design</A>. This model
2.30 frystyk 877: operates by using at least two request objects which gets linked to eachother
2.33 frystyk 878: as part of the PostWeb model. However, if you are posting from memory, we
2.30 frystyk 879: only use <EM>one</EM> request object to perform the operation. In order to
880: do this, the application must register a callback function that can be called
881: when the <A HREF="HTTP.c">HTTP client module</A> is ready for accepting data.
882: be included as part of the body and/or as extra metainformation. In the latter
883: case you need to register a callback function of the following type using
884: the methods provided in the next section.
2.9 frystyk 885: <PRE>
2.21 frystyk 886: typedef int HTPostCallback (HTRequest * request, HTStream * target);
2.33 frystyk 887:
888: extern void HTRequest_setPostCallback (HTRequest * request, HTPostCallback * cbf);
889: extern HTPostCallback * HTRequest_postCallback (HTRequest * request);
2.9 frystyk 890: </PRE>
2.40 frystyk 891: <P>
892: The Entity Anchor is either the anchor directly associated with the Request
893: object or the post anchor associated with the object. The purpose of the
894: entity anchor is if we are to send data to a remote server then we get the
895: metainformation using the entity anchor.
2.39 frystyk 896: <PRE>
897: extern BOOL HTRequest_setEntityAnchor (HTRequest * request, HTParentAnchor * anchor);
898: extern HTParentAnchor * HTRequest_entityAnchor (HTRequest * request);
899: </PRE>
2.30 frystyk 900: <H3>
901: Input Stream
902: </H3>
903: <P>
904: The input stream is to be used to put data <EM>to</EM> the network. Normally
905: each protocol sets the input stream in order to generate the protocol headers
906: while making a request.
2.27 frystyk 907: <PRE>
908: extern void HTRequest_setInputStream (HTRequest * request, HTStream * input);
909: extern HTStream *HTRequest_inputStream (HTRequest * request);
910: </PRE>
2.33 frystyk 911: <H3>
912: Is This Request part of a Post Web?
913: </H3>
914: <P>
915: Check to see if this request object is part of a Post Web.
916: <PRE>
917: extern BOOL HTRequest_isPostWeb (HTRequest * request);
918: </PRE>
919: <H3>
920: Source of a Request
921: </H3>
922: <P>
923: A request may have a source in which is another request object that as output
924: stream has the input stream of this request object.
925: <PRE>
926: extern BOOL HTRequest_setSource (HTRequest * request, HTRequest * source);
927: extern HTRequest * HTRequest_source (HTRequest * request);
928: </PRE>
2.30 frystyk 929: <H2>
930: Streams From Network to Application
931: </H2>
932: <H3>
933: Default Output Stream
934: </H3>
935: <P>
2.1 frystyk 936: The output stream is to be used to put data down to as they come in
2.30 frystyk 937: <B>from</B> the network and back to the application. The default value is
938: <CODE>NULL</CODE> which means that the stream goes to the user (display).
2.1 frystyk 939: <PRE>
940: extern void HTRequest_setOutputStream (HTRequest *request, HTStream *output);
2.6 frystyk 941: extern HTStream *HTRequest_outputStream (HTRequest *request);
2.1 frystyk 942: </PRE>
2.37 frystyk 943: <H3>
944: Has Output Stream been Connected to Channel?
945: </H3>
946: <P>
947: Has output stream been connected to the channel? If not then we must free
948: it explicitly when deleting the request object
949: <PRE>extern void HTRequest_setOutputConnected (HTRequest * request, BOOL mode);
950: extern BOOL HTRequest_outputConnected (HTRequest * request);
951: </PRE>
2.30 frystyk 952: <P>
953: The desired format of the output stream. This can be used to get unconverted
954: data etc. from the library. If <CODE>NULL</CODE>, then
955: <A HREF="HTFormat.html#FormatTypes">WWW_PRESENT</A> is default value.
2.1 frystyk 956: <PRE>
957: extern void HTRequest_setOutputFormat (HTRequest *request, HTFormat format);
2.6 frystyk 958: extern HTFormat HTRequest_outputFormat (HTRequest *request);
2.1 frystyk 959: </PRE>
2.30 frystyk 960: <H3>
961: Debug Stream
962: </H3>
963: <P>
964: All object bodies sent from the server with status codes different from
965: <CODE>200 OK</CODE> will be put down this stream. This can be used for
966: redirecting body information in status codes different from "200 OK" to for
967: example a debug window. If the value is NULL (default) then the stream is
968: not set up.
2.1 frystyk 969: <PRE>
970: extern void HTRequest_setDebugStream (HTRequest *request, HTStream *debug);
2.6 frystyk 971: extern HTStream *HTRequest_debugStream (HTRequest *request);
2.1 frystyk 972: </PRE>
2.30 frystyk 973: <P>
974: The desired format of the error stream. This can be used to get unconverted
975: data etc. from the library. The default value if <CODE>WWW_HTML</CODE> as
976: a character based only has one WWW_PRESENT.
2.1 frystyk 977: <PRE>
978: extern void HTRequest_setDebugFormat (HTRequest *request, HTFormat format);
2.6 frystyk 979: extern HTFormat HTRequest_debugFormat (HTRequest *request);
2.1 frystyk 980: </PRE>
2.33 frystyk 981: <H2>
2.30 frystyk 982: <A NAME="context">Context Swapping</A>
983: </H2>
984: <P>
985: In multi threaded applications it is often required to keep track of the
986: context of a request so that when the Library returns a result of a request,
987: it can be put into the context it was in before the request was first passed
988: to the Library. This call back function allows the application to do this.
2.1 frystyk 989: <PRE>
990: typedef int HTRequestCallback (HTRequest * request, void *param);
991:
992: extern void HTRequest_setCallback (HTRequest *request, HTRequestCallback *cb);
993: extern HTRequestCallback *HTRequest_callback (HTRequest *request);
994: </PRE>
2.30 frystyk 995: <P>
996: The callback function can be passed an arbitrary pointer (the void part)
997: which can describe the context of the current request structure. If such
998: context information is required then it can be set using the following methods:
2.1 frystyk 999: <PRE>
1000: extern void HTRequest_setContext (HTRequest *request, void *context);
1001: extern void *HTRequest_context (HTRequest *request);
2.20 frystyk 1002: </PRE>
2.30 frystyk 1003: <H2>
1004: Binding to an Anchor Object
1005: </H2>
1006: <P>
2.33 frystyk 1007: Every request object has an <A HREF="HTAnchor.html">anchor</A> associated
1008: with it. The anchor normally lives until the application terminates but a
2.47 frystyk 1009: request object only lives as long as the request is being serviced. If the
1010: anchor that we have requested is infact a child anchor then we always load
1011: the parent anchor and then after the load jump to the location. A child anchor
1012: is a an anchor which points to a subpart of the document (has a "#" in the
1013: URL).
2.45 frystyk 1014: <PRE>extern void HTRequest_setAnchor (HTRequest *request, HTAnchor *anchor);
2.30 frystyk 1015: extern HTParentAnchor * HTRequest_anchor (HTRequest *request);
2.45 frystyk 1016:
1017: extern HTChildAnchor * HTRequest_childAnchor (HTRequest * request);
2.30 frystyk 1018: </PRE>
1019: <H2>
2.33 frystyk 1020: Should we Issue a full HTTP Request-URI?
2.31 frystyk 1021: </H2>
1022: <P>
1023: In early versions of HTTP, the request sent to the remote server varies whether
1024: we use a proxy or go directly to the origin server. The default value is
2.42 frystyk 1025: <EM>OFF</EM> but we use a full request if we are talking to a proxy server.
2.31 frystyk 1026: <PRE>
2.32 frystyk 1027: extern void HTRequest_setFullURI (HTRequest *request, BOOL mode);
1028: extern BOOL HTRequest_fullURI (HTRequest *request);
2.31 frystyk 1029: </PRE>
1030: <H2>
2.42 frystyk 1031: Proxy URL
1032: </H2>
1033: <P>
1034: In case we are using a proxy for this requst then we can register it together
1035: with the request object. That way we can find the proxy and look for
1036: authentication information, for example in the
2.43 frystyk 1037: <A HREF="HTAAUtil.html">Authentication filter</A>. The string is freed by
1038: the Request object on deletion.
2.42 frystyk 1039: <PRE>
2.43 frystyk 1040: extern BOOL HTRequest_setProxy (HTRequest * request, const char * proxy);
1041: extern char * HTRequest_proxy (HTRequest * request);
1042: extern BOOL HTRequest_deleteProxy (HTRequest * request);
2.42 frystyk 1043: </PRE>
1044: <H2>
2.58 frystyk 1045: Enity Bytes Read or Written in a Request
2.30 frystyk 1046: </H2>
1047: <P>
1048: This function returns the bytes read in the current request. For a deeper
1049: description of what the current request is, please read the user's guide.
1050: This function can be used in for example the <A HREF="HTAlert.html">HTAlert
1051: module</A> to give the number of bytes read or written in a progress message.
2.1 frystyk 1052: <PRE>
2.49 frystyk 1053: extern long HTRequest_bodyRead (HTRequest * request);
2.58 frystyk 1054: extern long HTRequest_bodyWritten (HTRequest * request);
1055: </PRE>
2.64 frystyk 1056: <P>
1057: You can also get the total number of bytes read or written including the
1058: headers
2.58 frystyk 1059: <PRE>
1060: extern long HTRequest_bytesRead (HTRequest * request);
2.19 frystyk 1061: extern long HTRequest_bytesWritten (HTRequest * request);
2.1 frystyk 1062: </PRE>
2.30 frystyk 1063: <H2>
2.33 frystyk 1064: Internal Request Objects
2.30 frystyk 1065: </H2>
1066: <P>
2.33 frystyk 1067: The library may under certain circumstances create its own Request objects.
1068: These are all handled internal and does not show up on the application side
1069: at all.
2.1 frystyk 1070: <PRE>
2.33 frystyk 1071: extern BOOL HTRequest_setInternal (HTRequest * request, BOOL mode);
1072: extern BOOL HTRequest_internal (HTRequest * request);
2.49 frystyk 1073: extern int HTRequest_forceFlush (HTRequest * request);
2.1 frystyk 1074: </PRE>
1075: <PRE>
1076: #endif /* HTREQ_H */
1077: </PRE>
2.30 frystyk 1078: <P>
1079: <HR>
2.27 frystyk 1080: <ADDRESS>
2.65 ! frystyk 1081: @(#) $Id: HTReq.html,v 2.64 1998/11/19 17:14:39 frystyk Exp $
2.27 frystyk 1082: </ADDRESS>
2.30 frystyk 1083: </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