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