Annotation of libwww/Library/src/HTAccess.html, revision 2.57
2.9 timbl 1: <HTML>
2: <HEAD>
2.45 frystyk 3: <TITLE>Access manager for libwww</TITLE>
2.57 ! frystyk 4: <!-- Changed by: Henrik Frystyk Nielsen, 13-Aug-1995 -->
2.19 timbl 5: <NEXTID N="z11">
2.9 timbl 6: </HEAD>
2.5 timbl 7: <BODY>
2.39 frystyk 8:
2.33 frystyk 9: <H1>Access Manager</H1>
2.39 frystyk 10:
2.41 frystyk 11: <PRE>
12: /*
2.50 frystyk 13: ** (c) COPYRIGHT MIT 1995.
2.41 frystyk 14: ** Please first read the full copyright statement in the file COPYRIGH.
15: */
16: </PRE>
17:
2.39 frystyk 18: This module keeps a list of valid protocol (naming scheme) specifiers
19: with associated access code. It allows documents to be loaded given
20: various combinations of parameters. New access protocols may be
21: registered at any time.<P>
22:
23: This module is implemented by <A HREF="HTAccess.c">HTAccess.c</A>, and
24: it is a part of the <A NAME="z10"
2.56 frystyk 25: HREF="http://www.w3.org/hypertext/WWW/Library/">
26: W3C Reference Library</A>. <P>
2.39 frystyk 27:
28: The module contains a lot of stuff but the main topics are:
29:
30: <UL>
2.41 frystyk 31: <LI><A HREF="#Library">Initializing and Terminating the Library</A>
2.52 frystyk 32: <LI><A HREF="#Addresses">Default Directories and URLs</A>
33: <LI><A HREF="#flags">Global Flags</A><P>
34:
35: <LI><A HREF="#z100">Management of the HTRequest Object</A>
2.55 frystyk 36: <LI><A HREF="#headers">Handling HTTP headers</A><P>
2.52 frystyk 37:
2.39 frystyk 38: <LI><A HREF="#LoadDoc">Functions for loading a document</A>
39: <LI><A HREF="#ClientHelp">Help functions for clients to get started</A>
2.52 frystyk 40: <LI><A HREF="#PostDoc">Functions for posting a document</A> <P>
41:
42: <LI><A HREF="#Int">Internal Data Structures</A>
2.39 frystyk 43: </UL>
44:
2.33 frystyk 45:
46: <PRE>
47: #ifndef HTACCESS_H
1.1 timbl 48: #define HTACCESS_H
2.44 roeber 49:
2.52 frystyk 50: #include "<A HREF="HTList.html">HTList.h</A>"
51: #include "<A HREF="HTChunk.html">HTChunk.h</A>"
52: #include "<A HREF="HTAnchor.html">HTAnchor.h</A>"
53: #include "<A HREF="HTStream.html">HTStream.h</A>"
54: #include "<A HREF="HTAssoc.html">HTAssoc.h</A>"
2.54 frystyk 55: #include "<A HREF="HTMethod.html">HTMethod.h</A>"
2.52 frystyk 56: </PRE>
57:
58: <A NAME="Library"><H2>Initializing and Terminating the Library</H2></A>
59:
60: <IMG SRC="http://www.w3.org/hypertext/WWW/Icons/32x32/warning.gif">
61: These two functions initiates memory and settings for the Library and
62: cleans up memory kept by the Library when about to exit the
63: application. It is highly recommended that they are used!
64:
65: <PRE>
66: extern BOOL HTLibInit NOPARAMS;
67: extern BOOL HTLibTerminate NOPARAMS;
68: </PRE>
69:
70: <A NAME="Addresses"><H2>Default WWW Addresses</H2></A>
71:
72: These control the home page selection. To mess with these for normal browses
73: is asking for user confusion.
74: <PRE>
75: #define LOGICAL_DEFAULT "WWW_HOME" /* Defined to be the home page */
76:
77: #ifndef PERSONAL_DEFAULT
78: #define PERSONAL_DEFAULT "WWW/default.html" /* in home directory */
79: #endif
80:
81: /* If the home page isn't found, use this file: */
82: #ifndef LAST_RESORT
83: #define LAST_RESORT "http://www.w3.org/"
84: #endif
85:
86: /* If one telnets to an access point it will look in this file for home page */
87: #ifndef REMOTE_POINTER
88: #define REMOTE_POINTER "/etc/www-remote.url" /* can't be file */
89: #endif
90:
91: /* and if that fails it will use this. */
92: #ifndef REMOTE_ADDRESS
93: #define REMOTE_ADDRESS "http://www.w3.org/" /* can't be file */
94: #endif
95:
96: /* Default log file name */
97: #ifndef DEFAULT_LOGFILE
98: #define DEFAULT_LOGFILE "www-log"
99: #endif
100:
101: #ifndef LOCAL_DEFAULT_FILE
102: #define LOCAL_DEFAULT_FILE "/usr/local/lib/WWW/default.html"
103: #endif
104:
105: /* This is the default cache directory: */
106: #ifndef HT_CACHE_ROOT
107: #define HT_CACHE_ROOT "/tmp"
108: #endif
109:
110: /* The default directory for "save locally" and "save and execute" files: */
111: #ifndef HT_TMP_ROOT
112: #define HT_TMP_ROOT "/tmp"
113: #endif
2.35 frystyk 114: </PRE>
1.1 timbl 115:
2.52 frystyk 116: <A NAME="flags"><H2>Global Flags</H2></A>
2.46 frystyk 117:
118: Flags and variables which may be set to control the Library
119:
2.52 frystyk 120: <H3>Maximum Number of Redirections</H3>
2.46 frystyk 121:
122: The maximum number of redirections is pr. default 10. This prevents
123: the library from going into an infinite loop which is kind of nice :-)
2.52 frystyk 124: It is normally not necessary to change the default value.
2.46 frystyk 125:
2.35 frystyk 126: <PRE>
2.46 frystyk 127: extern int HTMaxRedirections;
2.33 frystyk 128: </PRE>
1.1 timbl 129:
2.52 frystyk 130: <H3>Allow Accss to Local File System</H3>
131:
132: This flag can be used to deny an application to get access to the
133: local file system (through cache, file URLs etc.)
134:
135: <PRE>
136: extern BOOL HTSecure; /* Disable security holes? */
137: </PRE>
138:
139: <H3>Name of Remote login Host</H3>
140:
141: If an application is used for remote access (allowing telnet access,
142: like for example the Line Mode Browser), then set this variable to the
143: name of the remote host.
2.36 frystyk 144:
145: <PRE>
146: extern char * HTClientHost; /* Name or number of telnetting host */
2.52 frystyk 147: </PRE>
148:
149: <H3>Server Specific Flags</H3>
150:
151: These two flags are set by a proxy and a server application
152: respectfully. They tell the Library to skip some of the client
153: application specific things.
2.46 frystyk 154:
2.52 frystyk 155: <PRE>
2.36 frystyk 156: extern char * HTImServer; /* If I'm cern_httpd */
157: extern BOOL HTImProxy; /* If I'm cern_httpd as a proxy */
158: </PRE>
159:
2.52 frystyk 160: <H2><A NAME="z100">Functions to Manipulate a HTRequest Structure</A></H2>
161:
162: Just to make things easier especially for clients, here are some functions to
163: manipulate the request structure:
164:
165: <PRE>
166: typedef struct _HTRequest HTRequest;
167: </PRE>
168:
169: <H3>Create blank request</H3>
170:
171: This request has defaults in -- in most cases it will need some
172: information added before being passed to HTAccess, but it will work as
173: is for a simple request.
174:
175: <PRE>
176: extern HTRequest * HTRequest_new NOPARAMS;
177: </PRE>
178:
179: <H3>Delete request structure</H3>
180:
181: Frees also conversion list hanging from req->conversions.
182:
183: <PRE>
184: extern void HTRequest_delete PARAMS((HTRequest * req));
185: </PRE>
186:
2.54 frystyk 187: <H3>Post Web Management</H3>
2.16 luotonen 188:
2.57 ! frystyk 189: These functions are mainly used internally in the Library but there is
! 190: no reason for them not to be public.
! 191:
2.33 frystyk 192: <PRE>
2.54 frystyk 193: extern BOOL HTRequest_addDestination PARAMS((HTRequest * src,
194: HTRequest * dest));
195: extern BOOL HTRequest_removeDestination PARAMS((HTRequest * dest));
196:
197: extern BOOL HTRequest_linkDestination PARAMS((HTRequest * dest));
198: extern BOOL HTRequest_unlinkDestination PARAMS((HTRequest * dest));
199:
200: extern BOOL HTRequest_removePostWeb PARAMS((HTRequest * me));
201: extern BOOL HTRequest_killPostWeb PARAMS((HTRequest * me));
202:
203: #define HTRequest_mainDestination(me) \
204: ((me) && (me)->source ? (me)->source->mainDestination : NULL)
205: #define HTRequest_isDestination(me) \
206: ((me) && (me)->source && (me) != (me)->source)
207: #define HTRequest_isMainDestination(me) \
208: ((me) && (me)->source && \
209: (me) == (me)->source->mainDestination)
210: #define HTRequest_isSource(me) \
211: ((me) && (me)->source && (me) == (me)->source)
212: #define HTRequest_isPostWeb(me) \
213: ((me) && (me)->source)
2.16 luotonen 214: </PRE>
2.33 frystyk 215:
2.55 frystyk 216: <A NAME="headers"><H2>HTTP/MIME Header Methods</H2></A>
2.10 timbl 217:
2.52 frystyk 218: These enumerations set up the headers that are used in a HTTP request
219: <EM>OR</EM> a HTTP response.
2.10 timbl 220:
2.52 frystyk 221: <A NAME="HeaderMask"><H3>General HTTP Header Mask</H3></A>
2.46 frystyk 222:
2.51 frystyk 223: There are a few header fields which have general applicability for
224: both request and response mesages, but which do not apply to the
225: communication parties or theentity being transferred. This mask
226: enables and disables these headers. If the bit is not turned on they
2.52 frystyk 227: are not sent. All headers are optional and the default value is <EM>NO
228: GENERAL HEADERS</EM>
2.46 frystyk 229:
230: <PRE>
2.51 frystyk 231: typedef enum _GenHeaderEnum {
2.46 frystyk 232: HT_DATE = 0x1,
2.51 frystyk 233: HT_FORWARDED = 0x2,
234: HT_MESSAGE_ID = 0x4,
235: HT_MIME = 0x8
236: } GenHeaderEnum;
237:
238: #define <A NAME="DEF_HEAD">DEFAULT_GENERAL_HEADERS</A> 0
239: </PRE>
240:
2.52 frystyk 241: <H3>Request Headers</H3>
2.46 frystyk 242:
2.51 frystyk 243: The request header fields allow the client to pass additional
244: information about the request (and about the client itself) to the
245: server. All headers are optional but the default value is all request
246: headers if present <EM>except</EM> <CODE>From</CODE> and
247: <CODE>Pragma</CODE>.
248:
249: <PRE>
250: typedef enum _ReqHeaderEnum {
251: HT_ACCEPT_TYPE = 0x1,
252: HT_ACCEPT_CHAR = 0x2,
253: HT_ACCEPT_ENC = 0x4,
254: HT_ACCEPT_LAN = 0x8,
2.46 frystyk 255: HT_FROM = 0x10,
256: HT_PRAGMA = 0x20,
257: HT_REFERER = 0x40,
258: HT_USER_AGENT = 0x80
2.51 frystyk 259: } ReqHeaderEnum;
2.46 frystyk 260:
2.51 frystyk 261: #define <A NAME="DEF_REQ">DEFAULT_REQUEST_HEADERS</A> \
262: HT_ACCEPT_TYPE+HT_ACCEPT_CHAR+HT_ACCEPT_ENC+HT_ACCEPT_LAN+HT_REFERER+HT_USER_AGENT
2.46 frystyk 263: </PRE>
264:
2.52 frystyk 265: <H3>Entity Header Mask</H3>
2.46 frystyk 266:
267: The entity headers contain information about the object sent in the
268: HTTP transaction. See the <A HREF="HTAnchor.html">Anchor module</A>,
269: for the storage of entity headers. This flag defines which headers are
270: to be sent in a request together with an entity body (the <B>O</B>
2.51 frystyk 271: stands for <EM>object</EM>). All headers are optional but the default
272: value is <EM>ALL ENTITY HEADERS IF PRESENT</EM>
2.46 frystyk 273:
274: <PRE>
275: typedef enum _EntityHeaderEnum {
276: HT_ALLOW = 0x1,
277: HT_CONTENT_ENCODING = 0x2,
278: HT_CONTENT_LANGUAGE = 0x4,
279: HT_CONTENT_LENGTH = 0x8,
280: HT_CTE = 0x10, /* Content-Transfer-Encoding */
281: HT_CONTENT_TYPE = 0x20,
282: HT_DERIVED_FROM = 0x40,
283: HT_EXPIRES = 0x80,
284: HT_LAST_MODIFIED = 0x200,
285: HT_LINK = 0x400,
286: HT_TITLE = 0x800,
287: HT_URI = 0x1000,
288: HT_VERSION = 0x2000
289: } EntityHeaderEnum;
290:
2.51 frystyk 291: #define <A NAME="DEF_ENTITY">DEFAULT_ENTITY_HEADERS</A> 0xFFFF
2.46 frystyk 292: </PRE>
293:
2.52 frystyk 294: <H3>User Defined Headers</H3>
2.10 timbl 295:
2.52 frystyk 296: Extra header can be generated when initializing the <A
297: HREF="#ExtraHeaders">ExtraHeaders field</A>.
1.1 timbl 298:
2.57 ! frystyk 299:
! 300: <H3>Force Reload of a Document</H3>
! 301:
! 302: The <A HREF="#FR">ForceReload</A> flag can either force reload of
! 303: object in memory or in a disk cache. That is, if only memory version
! 304: is to reloaded - the new version can come from the local disk
! 305: cache. The default value is <CODE>HT_NO_UPDATE</CODE>.
! 306:
! 307: <PRE>
! 308: typedef enum _HTForceReload {
! 309: HT_NO_UPDATE = 0x0,
! 310: HT_UPDATE_MEM = 0x1,
! 311: HT_UPDATE_DISK = 0x2
! 312: } HTForceReload;
! 313: </PRE>
! 314:
2.52 frystyk 315: <A NAME="LoadDoc"><H2>Functions for Loading a Document</H2></A>
2.33 frystyk 316:
2.52 frystyk 317: There are several different ways of loading a document. However, the
318: major difference between them is whether the document is referenced by
2.33 frystyk 319:
2.52 frystyk 320: <UL>
321: <LI><A HREF="#Relative">Relative URI</A>
322: <LI><A HREF="#Absolute">Absolute URI</A>
323: <LI><A HREF="#Anchor">Anchor element</A> or
324: <LI>Contains keywords for <A HREF="#RelSearch">searching an relative URI</A>
325: <LI>Contains keywords for <A HREF="#AbsSearch">searching an absolute URI</A>
326: </UL>
2.33 frystyk 327:
2.52 frystyk 328: <B>NOTE:</B> From release 3.0 of the Library, the return codes from
329: the loading functions are no mode <CODE>BOOL</CODE>, that is
330: <CODE>YES</CODE> or <CODE>NO</CODE>. Insted they have been replaced
331: with the following set of return codes defined in the <A
332: HREF="HTUtils.html#ReturnCodes">Utility module</A>:
1.1 timbl 333:
2.52 frystyk 334: <DL>
335: <DT>HT_WOULD_BLOCK
336: <DD>An I/O operation would block
1.1 timbl 337:
2.52 frystyk 338: <DT>HT_ERROR
339: <DD>Error has occured
1.1 timbl 340:
2.52 frystyk 341: <DT>HT_LOADED
342: <DD>Success
2.23 frystyk 343:
2.52 frystyk 344: <DT>HT_NO_DATA
345: <DD>Success, but no document loaded. This might be the situation when a
346: telnet sesssion is started etc.
2.10 timbl 347:
2.52 frystyk 348: <DT>HT_RETRY
349: <DD>The remote server is down but will serve documents from the
350: calendar time indicated in HTRequest->retry_after.
2.51 frystyk 351:
2.52 frystyk 352: </DL>
2.51 frystyk 353:
2.52 frystyk 354: However, a general rule about the return codes is that <B>ERRORS</B>
355: have a <EM>negative</EM> value whereas <B>SUCCESS</B> has a
356: <EM>positive</EM> value. <P>
2.51 frystyk 357:
2.52 frystyk 358: There are also some functions to help the client getting started with
359: <A HREF="#ClientHelp">the first URI</A>.
2.51 frystyk 360:
2.52 frystyk 361: <A NAME="Relative"><H3>Load a document from relative URL</H3></A>
2.34 frystyk 362:
363: <PRE>
2.52 frystyk 364: extern int HTLoadRelative PARAMS((CONST char * relative_name,
365: HTParentAnchor* here,
366: HTRequest * request));
2.34 frystyk 367: </PRE>
368:
2.52 frystyk 369: <A NAME="Absolute"></A><H3>Load a document from absolute URL</H3>
2.39 frystyk 370:
371: <PRE>
2.52 frystyk 372: extern int HTLoadAbsolute PARAMS((CONST char * addr,
373: HTRequest * request));
2.39 frystyk 374: </PRE>
2.19 timbl 375:
2.52 frystyk 376: <H3>Load a document from absolute name to a stream</H3>
2.19 timbl 377:
2.39 frystyk 378: <PRE>
2.52 frystyk 379: extern int HTLoadToStream PARAMS((CONST char * addr,
380: BOOL filter,
381: HTRequest * request));
2.39 frystyk 382: </PRE>
383:
2.52 frystyk 384: <A NAME="Anchor"><H3>Load a document from anchor</H3></A>
2.46 frystyk 385:
2.52 frystyk 386: The anchor parameter may be a child anchor. The anchor in the request
387: is set to the parent anchor. The recursive function keeps the error
388: stack in the request structure so that no information is lost having
389: more than one call. See also <A HREF="#BindAnchor">HTBindAnchor()</A>.
2.39 frystyk 390:
391: <PRE>
2.52 frystyk 392: extern int HTLoadAnchor PARAMS((HTAnchor * a,
393: HTRequest * request));
394: extern int HTLoadAnchorRecursive PARAMS((HTAnchor * a,
395: HTRequest * request));
2.39 frystyk 396: </PRE>
397:
2.52 frystyk 398: <H3>Load a Document</H3>
2.39 frystyk 399:
2.52 frystyk 400: These are two internal routines for loading a document which has an
401: address AND a matching anchor. (The public routines are called with
402: one OR the other.) This is recursively called from file load module
403: to try ftp (though this will be obsolete in the next major
404: release).<P>
2.39 frystyk 405:
2.52 frystyk 406: If <CODE>keep_error_stack</CODE> is YES then the error (or info) stack
407: is not cleared from the previous call.
2.39 frystyk 408:
409: <PRE>
2.52 frystyk 410: extern int HTLoad PARAMS((HTRequest * request,
411: BOOL keep_error_stack));
2.39 frystyk 412: </PRE>
413:
414: <PRE>
2.52 frystyk 415: extern BOOL HTLoadTerminate PARAMS((HTRequest * request, int status));
2.51 frystyk 416: </PRE>
417:
2.52 frystyk 418: <A NAME="RelSearch"><H3>Search Using Relative URL</H3></A>
419:
420: Performs a search on word given by the user. Adds the search words to
421: the end of the current address and attempts to open the new address.
2.51 frystyk 422:
423: <PRE>
2.52 frystyk 424: extern int HTSearch PARAMS((CONST char * keywords,
425: HTParentAnchor* here,
426: HTRequest * request));
2.46 frystyk 427: </PRE>
428:
2.52 frystyk 429: <A NAME="AbsSearch"><H3>Search using Absolute URL</H3></A>
430:
431: Performs a keyword search on word given by the user. Adds the keyword
432: to the end of the current address and attempts to open the new
433: address.
2.46 frystyk 434:
435: <PRE>
2.52 frystyk 436: extern int HTSearchAbsolute PARAMS((CONST char * keywords,
437: CONST char * indexname,
438: HTRequest * request));
2.46 frystyk 439: </PRE>
440:
441:
2.52 frystyk 442: <A NAME="ClientHelp"><H2>Help Function for Clients to get started</H2></A>
2.39 frystyk 443:
2.52 frystyk 444: These function helps the client to load the first document. They are
445: not mandatory to use - but they make life easier!
2.46 frystyk 446:
2.52 frystyk 447: <A NAME="BindAnchor"><H3>Bind an anchor to a request structure without
448: loading</H3></A>
2.39 frystyk 449:
450: <PRE>
2.52 frystyk 451: extern BOOL HTBindAnchor PARAMS((HTAnchor *anchor, HTRequest *request));
2.39 frystyk 452: </PRE>
453:
2.52 frystyk 454: <A NAME="HomePage"><H3>Generate the Anchor for the Home Page</H3></A>
455:
456: As it involves file access, this should only be done once when the
457: program first runs. This is a default algorithm using the
458: <CODE>WWW_HOME</CODE> environment variable.
2.39 frystyk 459:
460: <PRE>
2.52 frystyk 461: extern HTParentAnchor * HTHomeAnchor NOPARAMS;
2.39 frystyk 462: </PRE>
463:
2.52 frystyk 464: <H3>Find Related Name</H3>
2.45 frystyk 465:
2.52 frystyk 466: Creates a local file URI that can be used as a relative name when
467: calling HTParse() to expand a relative file name to an absolute
468: one. <P>
2.45 frystyk 469:
2.52 frystyk 470: The code for this routine originates from the Line Mode Browser and
2.53 frystyk 471: was moved here by <EM>howcome@w3.org</EM> in order for all
2.52 frystyk 472: clients to take advantage.<P>
2.39 frystyk 473:
2.47 frystyk 474: <PRE>
2.52 frystyk 475: extern char * HTFindRelatedName NOPARAMS;
2.47 frystyk 476: </PRE>
477:
2.52 frystyk 478: <A NAME="PostDoc"><H2>Functions for Posting a Document</H2></A>
479:
480: <B>NOTE:</B> The Posting functions are used to send a data object
481: along with the request. The functions have the same set of return
482: codes as for the <A HREF="#LoadDoc">Load Functions</A>.
2.47 frystyk 483:
2.52 frystyk 484: <H3>Get a Save Stream</H3>
2.46 frystyk 485:
2.52 frystyk 486: <H4>On Entry,</H4>
487: <DL>
488: <DT>request->anchor
489: <DD> is valid anchor which
490: has previously beeing loaded
491: </DL>
2.46 frystyk 492:
2.52 frystyk 493: <H4>On exit,</H4>
494: <DL>
495: <DT>returns
496: <DD> 0 if error else a stream
497: to save the object to.
498: </DL>
2.46 frystyk 499:
500: <PRE>
2.52 frystyk 501: extern HTStream * HTSaveStream PARAMS((HTRequest * request));
2.46 frystyk 502: </PRE>
503:
2.52 frystyk 504: <H3>Copy an Anchor</H3>
505:
506: Fetch the URL (possibly local file URL) and send it using either
507: <B>PUT</B> or <B>POST</B> directly to the remote destination using
508: HTTP, that is remote copy of object <EM>O</EM> from <EM>A</EM> to
509: <EM>B</EM> where <EM>A</EM> might be the host of the application. The
510: caller can decide the exact method used and which HTTP header fields
511: to transmit by setting the user fields in the destination request
512: structure.
2.46 frystyk 513:
514: <PRE>
2.52 frystyk 515: extern int HTCopyAnchor PARAMS((HTAnchor * src_anchor,
516: HTRequest * dest_req));
2.39 frystyk 517: </PRE>
518:
2.46 frystyk 519:
2.52 frystyk 520: <H3>Upload an Anchor</H3>
2.39 frystyk 521:
2.52 frystyk 522: Send the contents (in hyperdoc) of the source anchor using either
523: <B>PUT</B> or <B>POST</B> to the remote destination using HTTP. The
524: caller can decide the exact method used and which HTTP header fields
525: to transmit by setting the user fields in the request structure.
526: <EM>Format conversion</EM> can be made on the fly by setting the <A
527: HREF="#input_format">input_format field</A> in the destination request
528: structure. If the content-length is unknown (-1) then a <A
529: HREF="HTConLen.html">content-length counter</A> is automaticly put
530: into the stream pipe.
2.43 frystyk 531:
532:
533: <PRE>
2.52 frystyk 534: extern int HTUploadAnchor PARAMS((HTAnchor * src_anchor,
535: HTParentAnchor *dest_anchor,
536: HTRequest * dest_req));
2.46 frystyk 537: </PRE>
538:
2.52 frystyk 539: <A NAME="Int"><H2>Internal Data Structures</H2></A>
540:
541: These are internal to the Library and should not normally be accessed
542: directly.
2.46 frystyk 543:
2.52 frystyk 544: <H3>Access Authentication</H3>
2.39 frystyk 545:
2.52 frystyk 546: We need to define the following structures as they are used in the
547: HTRequest structure. The AA module is declared in <A
548: HREF="HTAAUtil.html">HTAAUtil</A> and <A HREF="HTAABrow.html">
549: HTAABrow</A>. The enumeration <CODE>HTAAScheme </CODE>represents the
550: possible authentication schemes used by the WWW Access Authorization.
2.19 timbl 551:
2.25 luotonen 552: <PRE>
2.52 frystyk 553: typedef enum {
554: HTAA_UNKNOWN,
555: HTAA_NONE,
556: HTAA_BASIC,
557: HTAA_PUBKEY,
558: HTAA_KERBEROS_V4,
559: HTAA_KERBEROS_V5,
560: HTAA_MAX_SCHEMES /* THIS MUST ALWAYS BE LAST! */
561: } HTAAScheme;
562:
563: typedef struct _HTAARealm HTAARealm;
564: typedef struct _HTAASetup HTAASetup;
2.46 frystyk 565: </PRE>
2.25 luotonen 566:
2.52 frystyk 567: <A NAME="socket"><H3>Buffering for the network</H3></A>
568:
569: This structure provides buffering for READ (and future WRITE) to the
570: network. It is used by all the protocol modules. The size of the
571: buffer, <CODE>INPUT_BUFFER_SIZE</CODE>, is a compromis between speed
572: and memory.
2.46 frystyk 573:
574: <PRE>
2.52 frystyk 575: #define INPUT_BUFFER_SIZE 8192
576:
577: typedef struct _HTInputSocket HTInputSocket;
2.34 frystyk 578: </PRE>
2.46 frystyk 579:
2.52 frystyk 580: <H3><A NAME="HTNetInfo">Protocol Specific Information</A></H3>
581:
582: This structure contains information about socket number, input buffer
583: for reading from the network etc. The structure is used through out
584: the protocol modules and is the reference point for introducing multi
585: threaded execution into the library, see specifications on <A
2.54 frystyk 586: HREF="http://www.w3.org/hypertext/WWW/Library/User/Architecture/Threads.html">Multiple
2.52 frystyk 587: Threads</A>.
2.46 frystyk 588:
2.34 frystyk 589: <PRE>
2.52 frystyk 590: typedef enum _SocAction {
591: SOC_INVALID = -1,
592: SOC_WRITE = 0, /* By default ready to write */
593: SOC_READ,
594: SOC_INTERRUPT
595: } SocAction;
596:
597: typedef struct _HTNetInfo {
598: SOCKFD sockfd; /* Socket descripter */
599: SockA sock_addr; /* SockA is defined in tcp.h */
600: HTInputSocket * isoc; /* Input buffer */
601: SocAction action; /* Result of the select call */
602: HTStream * target; /* Target stream */
603: int addressCount; /* Attempts if multi-homed host */
604: time_t connecttime; /* Used on multihomed hosts */
605: struct _HTRequest * request; /* Link back to request structure */
606: } HTNetInfo;
2.25 luotonen 607: </PRE>
2.39 frystyk 608:
2.52 frystyk 609: <EM><B>Note:</B> The AddressCount varaible is used to count the number
610: of attempt to connect to a multi-homed host so we know when to stop
611: trying new IP-addresses.</EM>
612:
613: <H3><A NAME="z1">The Request structure</A></H3>
2.46 frystyk 614:
2.52 frystyk 615: When a request is handled, all kinds of things about it need to be
616: passed along. These are all put into a HTRequest structure. This is
617: the most essential structure in the library. It contains two main
618: categories of information regarding a request:
2.39 frystyk 619:
2.52 frystyk 620: <UL>
621: <LI>Application dependent information
622: <LI>Library dependent information
623: </UL>
2.46 frystyk 624:
2.52 frystyk 625: Applications using the Library should <EM>never</EM> use the internal
626: library dependent information. It's only because we dont have real
627: classes that we can't hide it. <P>
2.46 frystyk 628:
2.52 frystyk 629: <B>Note:</B> If you reuse the request structure for more than one
630: request then make sure that the request is re-initialized, so that no
631: `old' data is reused, see <A HREF="#z100">functions to manipulate
632: HTRequest Structure</A>. The library handles its own internal
633: information from request to request but the information set by the
634: caller is untouched. <P>
2.46 frystyk 635:
2.52 frystyk 636: The elements of the request structure are as follows:
2.49 frystyk 637:
638: <PRE>
2.52 frystyk 639: struct _HTRequest {
2.49 frystyk 640: </PRE>
641:
2.52 frystyk 642: <H4>Application Dependent - Set by the caller of HTAccess</H4>
643:
2.19 timbl 644: <PRE>
2.52 frystyk 645: <A HREF="#Methods">HTMethod</A> method;
2.31 frystyk 646: </PRE>
647:
2.52 frystyk 648: An enum used to specify the HTTP <A NAME="z7"
649: HREF="../../Protocols/HTTP/Methods.html">method</A> used for the
650: actual request. The default value is <A
651: HREF="#Methods"><CODE>GET</CODE></A>.
2.31 frystyk 652:
2.52 frystyk 653: <H5>HTTP Header Information</H5>
2.31 frystyk 654:
2.14 luotonen 655: <PRE>
2.52 frystyk 656: HTList * conversions;
2.31 frystyk 657: </PRE>
2.14 luotonen 658:
2.52 frystyk 659: NULL, or a <EM>local</EM> list of specific conversions which the
660: format manager can do in order to fulfill the request. It typically
661: points to a list set up on initialisation time for example by <A
662: HREF="HTInit.html">HTInit()</A>. There is also a <A
663: HREF="HTFormat.html#z17"><EM>global</EM></A> list of conversions which
664: contains a generic set of possible conversions.
665:
2.14 luotonen 666: <PRE>
2.52 frystyk 667: HTList * encodings;
2.31 frystyk 668: </PRE>
1.1 timbl 669:
2.52 frystyk 670: The list of encodings acceptable in the output stream.
2.46 frystyk 671:
2.52 frystyk 672: <PRE>
673: HTList * languages;
674: </PRE>
2.46 frystyk 675:
2.52 frystyk 676: The list of (human) language values acceptable in the response. The default
677: is all languages.
2.46 frystyk 678:
2.31 frystyk 679: <PRE>
2.52 frystyk 680: HTList * charsets;
2.31 frystyk 681: </PRE>
2.9 timbl 682:
2.52 frystyk 683: The list of charsets accepted by the application
2.39 frystyk 684:
2.52 frystyk 685: <PRE>
686: GenHeaderEnum GenMask;
687: ReqHeaderEnum RequestMask;
688: EntityHeaderEnum EntityMask;
689: </PRE>
2.39 frystyk 690:
2.52 frystyk 691: These bitmask variables defines which headers to include in a HTTP
692: request (or any other MIME-like protocol). See <A
693: HREF="#HeaderMask">header masks</A> for more information on default
694: values.
2.39 frystyk 695:
2.52 frystyk 696: <PRE>
697: HTParentAnchor *parentAnchor;
698: </PRE>
2.39 frystyk 699:
2.52 frystyk 700: If this parameter is set then a `Referer: <parent address> can
701: be generated in the request to the server, see <A
702: HREF="http://www.w3.org/hypertext/WWW/Protocols/HTTP/HTRQ_Headers.html#z14">
703: Referer field in a HTTP Request</A>
2.39 frystyk 704:
2.52 frystyk 705: <PRE>
706: <A NAME="ExtraHeaders">char * ExtraHeaders;</A>
707: </PRE>
2.39 frystyk 708:
2.52 frystyk 709: Extra header information can be send along with a request using this
710: variable. The text is sent as is so it must be preformatted with
711: <CRLF> line terminators.
2.47 frystyk 712:
2.52 frystyk 713: <H5>Streams From Network to Application</H5>
1.1 timbl 714:
2.39 frystyk 715: <PRE>
2.52 frystyk 716: HTStream * output_stream;
2.5 timbl 717: </PRE>
2.39 frystyk 718:
2.52 frystyk 719: The output stream is to be used to put data down to as they come in
720: <B>from</B> the network and back to the application. The default value
721: is <CODE>NULL</CODE> which means that the stream goes to the user
722: (display).
1.1 timbl 723:
2.5 timbl 724: <PRE>
2.52 frystyk 725: HTAtom * output_format;
2.5 timbl 726: </PRE>
2.39 frystyk 727:
2.52 frystyk 728: The desired format of the output stream. This can be used to get
729: unconverted data etc. from the library. If <CODE>NULL</CODE>, then <A
730: HREF="HTFormat.html#FormatTypes">WWW_PRESENT</A> is default value.
2.39 frystyk 731:
2.5 timbl 732: <PRE>
2.52 frystyk 733: HTStream* error_stream;
2.5 timbl 734: </PRE>
1.1 timbl 735:
2.52 frystyk 736: All object bodies sent from the server with status codes different
737: from <CODE>200 OK</CODE> will be put down this stream. This can be
738: used as a debug window etc. If the value is NULL (default) then the
739: stream used is <A HREF="HTFormat.html#BlackHole">HTBlackHole</A>.
1.1 timbl 740:
2.39 frystyk 741: <PRE>
2.52 frystyk 742: HTAtom * error_format;
2.5 timbl 743: </PRE>
744:
2.52 frystyk 745: The desired format of the error stream. This can be used to get
746: unconverted data etc. from the library. The default value if
747: <CODE>WWW_HTML</CODE> as a character based only has one WWW_PRESENT.
1.1 timbl 748:
2.52 frystyk 749: <H5>Streams From Application to Network</H5>
1.1 timbl 750:
2.39 frystyk 751: <PRE>
2.52 frystyk 752: HTStream * input_stream;
2.41 frystyk 753: </PRE>
754:
2.52 frystyk 755: The input stream is to be used by the <CODE>PostCallBack</CODE>
756: function to put data out on the network. The user should not
757: initialize this field.
758:
2.41 frystyk 759: <PRE>
2.52 frystyk 760: HTAtom * input_format;
2.5 timbl 761: </PRE>
762:
2.52 frystyk 763: The desired format of the output stream. This can be used to upload
764: converted data to a remote server. If <CODE>NULL</CODE>, then <A
765: HREF="HTFormat.html#FormatTypes">WWW_SOURCE</A> is default value.
2.39 frystyk 766:
2.5 timbl 767: <PRE>
2.52 frystyk 768: int (*PostCallBack) PARAMS((struct _HTRequest * request,
769: HTStream * target));
2.5 timbl 770: </PRE>
2.39 frystyk 771:
2.52 frystyk 772: The call back function which is called when the current request is
773: ready for sending (posting) the data object. The request is the
774: current request so that the application knows which post we are
775: handling. The function must have the same return values as the other
776: <A HREF="#LoadDoc">Load functions</A>.
2.39 frystyk 777:
2.57 ! frystyk 778: <A NAME="FR"><H5>Force reload</H5></A>
! 779:
! 780: This flag can either force reload of object in memory or in a disk
! 781: cache. That is, if only memory version is to reloaded - the new
! 782: version can come from the local disk cache.
! 783:
! 784: <PRE>
! 785: HTForceReload ForceReload;
! 786: </PRE>
! 787:
2.52 frystyk 788: <H5>Other Flags</H5>
2.5 timbl 789:
2.33 frystyk 790: <PRE>
2.52 frystyk 791: BOOL BlockingIO;
792: BOOL ContentNegotiation;
2.5 timbl 793: </PRE>
2.24 luotonen 794:
2.52 frystyk 795: <CODE>BlockingIO</CODE> can be set to override if a protocol module is
796: registered as using non-blocking IO, <CODE>ForceReload</CODE> will
797: cancel any cached element, and <CODE>ContentNegotioation</CODE> will
798: force content negotiation when looking for a local file. This is the
799: default!
2.24 luotonen 800:
801: <PRE>
2.52 frystyk 802: BOOL (*<A NAME="z9"> callback</A> ) PARAMS((struct _HTRequest* request,
803: void *param));
2.24 luotonen 804: </PRE>
805:
2.52 frystyk 806: A function to be called back in the event that a file has been saved
807: to disk by HTSaveAndCallBack for example.
2.20 frystyk 808:
809: <PRE>
2.52 frystyk 810: void * context;
2.39 frystyk 811: </PRE>
812:
2.52 frystyk 813: An arbitrary pointer passed to HTAccess and passed back as a parameter
814: to the <A NAME="z10" HREF="#z9">callback</A>.
2.39 frystyk 815:
2.52 frystyk 816: <H4>Library Dependent - Set by Library</H4>
2.39 frystyk 817:
2.52 frystyk 818: None of the bits below may be looked at by a WWW application. The
819: Library handles the cleanup by itself.
2.39 frystyk 820:
2.20 frystyk 821: <PRE>
2.52 frystyk 822: HTParentAnchor* anchor;
2.39 frystyk 823: </PRE>
824:
2.52 frystyk 825: The anchor for the object in question. Set immediately by HTAcesss.
826: Used by the protocol and parsing modules. Valid thoughout the access.
2.39 frystyk 827:
2.52 frystyk 828: <PRE>
829: HTChildAnchor * childAnchor; /* For element within the object */
830: </PRE>
2.20 frystyk 831:
2.52 frystyk 832: The anchor for the sub object if any. The object builder should
833: ensure that is is selected, highlighted, etc when the object is
834: loaded.
2.20 frystyk 835:
2.52 frystyk 836: <PRE>
837: BOOL using_proxy;
838: </PRE>
2.5 timbl 839:
2.57 ! frystyk 840: If we are using a proxy this affects the HTTP request
2.5 timbl 841:
842: <PRE>
2.52 frystyk 843: BOOL error_block; /* YES if stream has been used */
844: HTList * error_stack; /* List of errors */
2.46 frystyk 845: </PRE>
846:
2.52 frystyk 847: These two fields are used by the error reporting system to keep a
848: stack of messages.
2.46 frystyk 849:
850: <PRE>
2.54 frystyk 851: char * redirect; /* Location or URI */
2.52 frystyk 852: int redirections; /* Number of redirections */
853: time_t retry_after; /* Absolut time for a retry */
2.46 frystyk 854: </PRE>
855:
2.54 frystyk 856: We keep track of the number of redirections and also register if we
857: have to repeat a request (if we received "5xx Retry After")
858:
859: <PRE>
860: HTNetInfo * net_info; /* Information about socket etc. */
861: </PRE>
862:
863: This structure contains protocol specific information, socket number etc.
864:
865: <PRE>
866: HTRequest * source; /* Source for request or itself */
867: HTRequest * mainDestination; /* For the typical case */
868: HTList * destinations; /* List of related requests */
869: int destRequests; /* Number of destination requests */
870: int destStreams; /* Number of destination streams */
871: </PRE>
872:
873: A simple model to bind related request structures together, for
874: example the source and destination request in a PUT.
2.46 frystyk 875:
2.52 frystyk 876: <PRE>
877: char * WWWAAScheme; /* WWW-Authenticate scheme */
878: char * WWWAARealm; /* WWW-Authenticate realm */
879: char * WWWprotection; /* WWW-Protection-Template */
2.54 frystyk 880: char * authorization; /* Authorization: field */
881: HTAAScheme scheme; /* Authentication scheme used */
2.52 frystyk 882: </PRE>
2.46 frystyk 883:
2.54 frystyk 884: Access Authentication specific information.
2.46 frystyk 885:
886: <PRE>
2.52 frystyk 887: HTInputSocket * isoc; /* InputSocket object for reading */
2.39 frystyk 888: </PRE>
2.5 timbl 889:
2.54 frystyk 890: This header is only used by the server and will be removed at some point.
1.1 timbl 891:
2.52 frystyk 892: <PRE>
893: HTList * valid_schemes; /* Valid auth.schemes */
894: HTAssocList ** scheme_specifics;/* Scheme-specific parameters */
895: char * authenticate; /* WWW-authenticate: field */
896: char * prot_template; /* WWW-Protection-Template: field */
897: HTAASetup * setup; /* Doc protection info */
898: HTAARealm * realm; /* Password realm */
899: char * dialog_msg; /* Authentication prompt (client) */
900: </PRE>
1.1 timbl 901:
2.52 frystyk 902: These fields are used by the HTTP access authentication used by a
903: client application.
2.39 frystyk 904:
2.52 frystyk 905: <H4>Windows Specific Information</H4>
2.39 frystyk 906:
907: <PRE>
2.52 frystyk 908: #ifdef _WINDOWS
909: HWND hwnd; /* Windows handle for MSWindows */
910: unsigned long winMsg; /* msg number of Windows eloop */
911: #endif /* _WINDOWS */
2.5 timbl 912: </PRE>
1.1 timbl 913:
2.38 howcome 914: <PRE>
2.52 frystyk 915: };
2.38 howcome 916: </PRE>
917:
2.52 frystyk 918: End of Declaration
2.25 luotonen 919:
920: <PRE>
1.1 timbl 921: #endif /* HTACCESS_H */
2.25 luotonen 922: </PRE>
923: end of HTAccess
924: </BODY>
2.9 timbl 925: </HTML>
Webmaster
![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to HTAccess.html CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [Public] / libwww / Library / src