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