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