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