Annotation of libwww/Library/src/HTAccess.html, revision 2.32
2.9 timbl 1: <HTML>
2: <HEAD>
2.6 timbl 3: <TITLE>HTAccess: Access manager for libwww</TITLE>
2.19 timbl 4: <NEXTID N="z11">
2.9 timbl 5: </HEAD>
2.5 timbl 6: <BODY>
7: <H1>Access Manager</H1>This module keeps a list of valid
8: protocol (naming scheme) specifiers
9: with associated access code. It
10: allows documents to be loaded given
11: various combinations of parameters.
12: New access protocols may be registered
13: at any time.<P>
2.9 timbl 14: Note: HTRequest defined and request
15: parametsr added to almost all calls
16: 18 Nov 1993.<P>
2.5 timbl 17: Part of the <A
2.19 timbl 18: NAME="z0" HREF="Overview.html">libwww library</A> . Implemented
19: by <A
20: NAME="z8" HREF="HTAccess.c">HTAcces.c</A>
2.5 timbl 21: <PRE>#ifndef HTACCESS_H
1.1 timbl 22: #define HTACCESS_H
23:
24: /* Definition uses:
25: */
26: #include "HTUtils.h"
2.16 luotonen 27: #include "HTList.h"
1.1 timbl 28: #include "tcp.h"
2.14 luotonen 29:
1.1 timbl 30:
31: #ifdef SHORT_NAMES
2.8 timbl 32: #define HTClientHost HTClHost
33: #define HTSearchAbsolute HTSeAbso
34: #define HTOutputStream HTOuStre
35: #define HTOutputFormat HTOuForm
1.1 timbl 36: #endif
37:
2.16 luotonen 38: typedef enum {
39: METHOD_INVALID = 0,
40: METHOD_GET = 1,
41: METHOD_HEAD,
42: METHOD_POST,
43: METHOD_PUT,
44: METHOD_DELETE,
45: METHOD_CHECKOUT,
46: METHOD_CHECKIN,
47: METHOD_SHOWMETHOD,
48: METHOD_LINK,
49: METHOD_UNLINK,
50: MAX_METHODS
51: } HTMethod;
52:
53:
54: </PRE>
55: <H2>Methods</H2>
56: <PRE>
57:
58: /* Get method enum value
59: ** ---------------------
60: */
61: PUBLIC HTMethod HTMethod_enum PARAMS((char * name));
62:
63:
64: /* Get method name
65: ** ---------------
66: */
67: PUBLIC char * HTMethod_name PARAMS((HTMethod method));
68:
69:
70: /* PUBLIC HTMethod_inList()
71: ** IS A METHOD IN A LIST OF METHOD NAMES
72: ** ON ENTRY:
73: ** method is the method to look for.
74: ** list is a list of method names.
75: **
76: ** ON EXIT:
77: ** returns YES, if method was found.
78: ** NO, if not found.
79: */
80: PUBLIC BOOL HTMethod_inList PARAMS((HTMethod method,
81: HTList * list));
82: </PRE>
83: <H2>Match Template Against Filename</H2>
84: <PRE>
85: /* PUBLIC HTAA_templateMatch()
86: ** STRING COMPARISON FUNCTION FOR FILE NAMES
87: ** WITH ONE WILDCARD * IN THE TEMPLATE
88: ** NOTE:
89: ** This is essentially the same code as in HTRules.c, but it
90: ** cannot be used because it is embedded in between other code.
91: ** (In fact, HTRules.c should use this routine, but then this
92: ** routine would have to be more sophisticated... why is life
93: ** sometimes so hard...)
94: **
95: ** ON ENTRY:
96: ** template is a template string to match the file name
97: ** agaist, may contain a single wildcard
98: ** character * which matches zero or more
99: ** arbitrary characters.
100: ** filename is the filename (or pathname) to be matched
101: ** agaist the template.
102: **
103: ** ON EXIT:
104: ** returns YES, if filename matches the template.
105: ** NO, otherwise.
106: */
107: PUBLIC BOOL HTAA_templateMatch PARAMS((CONST char * template,
108: CONST char * filename));
109:
110:
2.19 timbl 111: </PRE>The following have to be defined
2.10 timbl 112: in advance of the other include files
113: because of circular references.
114: <PRE>typedef struct _HTRequest HTRequest;
115:
2.14 luotonen 116: /*
117: ** Callback to call when username and password
118: ** have been prompted.
119: */
120: typedef int (*HTRetryCallbackType) PARAMS((HTRequest * req));
121:
122:
2.10 timbl 123: #include "HTAnchor.h"
124: #include <A
125: NAME="z3" HREF="HTFormat.html">"HTFormat.h"</A>
2.15 luotonen 126: #include "HTAAUtil.h" /* HTAAScheme, HTAAFailReason */
2.14 luotonen 127: #include "HTAABrow.h" /* HTAASetup */
2.10 timbl 128:
129:
1.1 timbl 130: /* Return codes from load routines:
131: **
132: ** These codes may be returned by the protocol modules,
133: ** and by the HTLoad routines.
134: ** In general, positive codes are OK and negative ones are bad.
135: */
136:
137: #define HT_NO_DATA -9999 /* return code: OK but no data was loaded */
138: /* Typically, other app started or forked */
139:
2.5 timbl 140: </PRE>
2.6 timbl 141: <H2>Default Addresses</H2>These control the home page selection.
2.8 timbl 142: To mess with these for normal browses
2.6 timbl 143: is asking for user confusion.
144: <PRE>#define LOGICAL_DEFAULT "WWW_HOME" /* Defined to be the home page */
1.1 timbl 145:
2.6 timbl 146: #ifndef PERSONAL_DEFAULT
147: #define PERSONAL_DEFAULT "WWW/default.html" /* in home directory */
148: #endif
149: #ifndef LOCAL_DEFAULT_FILE
1.1 timbl 150: #define LOCAL_DEFAULT_FILE "/usr/local/lib/WWW/default.html"
2.6 timbl 151: #endif
2.7 timbl 152: /* If one telnets to a www access point,
153: it will look in this file for home page */
154: #ifndef REMOTE_POINTER
155: #define REMOTE_POINTER "/etc/www-remote.url" /* can't be file */
156: #endif
157: /* and if that fails it will use this. */
2.6 timbl 158: #ifndef REMOTE_ADDRESS
1.1 timbl 159: #define REMOTE_ADDRESS "http://info.cern.ch/remote.html" /* can't be file */
160: #endif
161:
162: /* If run from telnet daemon and no -l specified, use this file:
163: */
164: #ifndef DEFAULT_LOGFILE
165: #define DEFAULT_LOGFILE "/usr/adm/www-log/www-log"
166: #endif
167:
168: /* If the home page isn't found, use this file:
169: */
170: #ifndef LAST_RESORT
2.6 timbl 171: #define LAST_RESORT "http://info.cern.ch/default.html"
1.1 timbl 172: #endif
173:
2.23 frystyk 174: /* This is the default cache directory:
175: */
176: #ifndef CACHE_HOME_DIR
177: #define CACHE_HOME_DIR "/tmp/"
178: #endif
179:
180: /* The default directory for "save locally" and "save and execute" files:
181: */
182: #ifndef SAVE_LOCALLY_HOME_DIR
183: #define SAVE_LOCALLY_HOME_DIR "/tmp/"
184: #endif
2.10 timbl 185:
2.9 timbl 186: </PRE>
187: <H2><A
188: NAME="z1">The Request structure</A></H2>When a request is handled, all kinds
189: of things about it need to be passed
190: along. These are all put into a
2.31 frystyk 191: HTRequest structure. <P>
192:
193: <NOTE>Note 1:</NOTE> There is also a <A NAME="z4" HREF="HTFormat.html#z17">global list of converters</A> <P>
194: <NOTE>Note 2:</NOTE> It is <B>NOT</B> safe to reuse a request structure for more than one request. It should be freed and reallocated or cleared, see <A HREF="#z100">functions to manipulate HTRequest Structure</A>
195:
2.10 timbl 196: <PRE>struct _HTRequest {
2.19 timbl 197:
198: </PRE>The elements of the request structure
199: are as follows.
200: <H3>Set by the caller of HTaccess:</H3>
201: <H4>Conditions of the request itself:</H4>
202: <PRE> HTMethod method;
203:
204: </PRE>An atom for the name of the operation
205: using HTTP <A
206: NAME="z7" HREF="../../Protocols/HTTP/Methods.html">method names</A> .
207: <PRE> HTList * conversions ;
2.20 frystyk 208: </PRE>NULL, or a list of conversions which
2.19 timbl 209: the format manager can do in order
210: to fulfill the request. This is
211: set by the caller of HTAccess. Typically
212: points to a list set up an initialisation
213: time for example by HTInit.
214: <PRE> HTList * encodings; /* allowed content-encodings */
215:
216: </PRE>The list of encodings acceptablein
217: the output stream.
218: <PRE> HTList * languages; /* accepted content-languages */
219:
220: </PRE>The list of (human) language values
221: acceptable in the response
222: <PRE> BOOL (*<A
2.20 frystyk 223: NAME="z9"> callback</A> ) PARAMS((
2.9 timbl 224: struct _HTRequest* request,
225: void *param));
2.19 timbl 226:
227: </PRE>A function to be called back in the
228: event that a file has been saved
229: to disk by HTSaveAndCallBack for
230: example.
231: <PRE> void * context; /* caller data -- HTAccess unaware */
232:
233: </PRE>An arbitrary pointer passed to HTAccess
234: and passed back as a parameter to
235: the <A
2.20 frystyk 236: NAME="z10" HREF="#z9">callback</A> .
2.19 timbl 237: <PRE> HTStream* output_stream;
238:
239: </PRE>NULL in the case of display to the
240: user, or if a specific output stream
241: is required, the stream.
242: <PRE> HTAtom * output_format;
243:
244: </PRE>The output format required, or a
245: generic format such as www/present
246: (present to user).
247: <H4>Information about the requester</H4>
248: <PRE> char * from;
249:
250: </PRE>Email format address of person responible
251: for request
252: <H3>Set by HTAccess</H3>None of the bits below may be looked
253: at by a client application except
254: in the callback routine, when the
255: anchor may be picked out.
256: <PRE> HTParentAnchor* anchor;
257:
258: </PRE>The anchor for the object in question.
2.20 frystyk 259: Set immediately by HTAcesss. Used
2.19 timbl 260: by the protocol and parsing modules.
261: Valid thoughout the access.
262: <PRE> HTChildAnchor * childAnchor; /* For element within the object */
263:
2.31 frystyk 264: </PRE>The anchor for the sub object if
2.19 timbl 265: any. The object builder should ensure
266: that htis is selected, highlighted,
267: etc when the object is loaded. NOTE:
268: Set by HTAccess.
269: <PRE> void * using_cache;
270:
271: </PRE>pointer to cache element if cache
272: hit
2.25 luotonen 273: <H3>Error Diagnostics</H3>
274: <PRE>
2.30 frystyk 275: BOOL error_block; /* YES if stream has been used */
2.29 luotonen 276: HTList * error_stack; /* List of errors */
2.25 luotonen 277:
278: </PRE>
2.21 luotonen 279: <H3>Server Side</H3>
280: <PRE>
281: HTAtom * content_type; /* Content-Type: */
2.18 luotonen 282: HTAtom * content_language;/* Language */
283: HTAtom * content_encoding;/* Encoding */
2.16 luotonen 284: int content_length; /* Content-Length: */
2.21 luotonen 285: HTInputSocket * isoc; /* InputSocket object for reading */
2.14 luotonen 286: char * authorization; /* Authorization: field */
287: HTAAScheme scheme; /* Authentication scheme used */
2.19 timbl 288: </PRE>
2.21 luotonen 289: <H3>Client Side</H3>
2.19 timbl 290: <PRE>
2.14 luotonen 291: HTList * valid_schemes; /* Valid auth.schemes */
292: HTAssocList ** scheme_specifics;/* Scheme-specific parameters */
293: char * prot_template; /* WWW-Protection-Template: field */
294: HTAASetup * setup; /* Doc protection info */
295: HTAARealm * realm; /* Password realm */
296: char * dialog_msg; /* Authentication prompt (client) */
297: HTRetryCallbackType
298: retry_callback; /* Called when password entered */
2.10 timbl 299: };
2.9 timbl 300:
2.31 frystyk 301: </PRE>
302:
303: <H2><A NAME="z100">Functions to Manipulate a HTRequest Structure</A></H2>
304:
305: Just to make things easier especially for clients, here are some functions to
306: manipulate the request structure:
307:
308: <H3>Create blank request</H3>This request has defaults in -- in
2.9 timbl 309: most cases it will need some information
310: added before being passed to HTAccess,
311: but it will work as is for a simple
312: request.
2.14 luotonen 313: <PRE>
314: PUBLIC HTRequest * HTRequest_new NOPARAMS;
2.31 frystyk 315: </PRE>
2.14 luotonen 316:
2.31 frystyk 317: <H3>Delete request structure</H3>Frees also conversion list hanging
2.19 timbl 318: from req->conversions.
2.14 luotonen 319: <PRE>
320: PUBLIC void HTRequest_delete PARAMS((HTRequest * req));
2.31 frystyk 321: </PRE>
1.1 timbl 322:
2.31 frystyk 323: <H3>Clear a request structure</H3>
324: Clears a request structure so that it can be reused. The only thing that differs from using free/new is that the list of conversions is kept.
325: <PRE>
326: extern void HTRequest_clear PARAMS((HTRequest * req));
327: </PRE>
2.9 timbl 328:
2.5 timbl 329: <H2>Flags which may be set to control
330: this module</H2>
2.22 frystyk 331: <PRE>
2.23 frystyk 332: extern char * HTSaveLocallyDir; /* Dir home for "save locally" files */
333: extern char * HTCacheDir; /* Cache dir, default NULL: no cache */
1.1 timbl 334: extern char * HTClientHost; /* Name or number of telnetting host */
2.27 frystyk 335: extern FILE * HTlogfile; /* File to output one-liners to */
2.7 timbl 336: extern BOOL HTSecure; /* Disable security holes? */
2.28 luotonen 337: extern char * HTImServer; /* If I'm cern_httpd */
2.21 luotonen 338: extern BOOL HTImProxy; /* If I'm cern_httpd as a proxy */
2.23 frystyk 339: extern BOOL HTForceReload; /* Force reload from cache or net */
1.1 timbl 340:
2.5 timbl 341: </PRE>
342: <H2>Load a document from relative name</H2>
343: <H3>On Entry,</H3>
344: <DL>
345: <DT>relative_name
2.6 timbl 346: <DD> The relative address
2.5 timbl 347: of the file to be accessed.
348: <DT>here
2.6 timbl 349: <DD> The anchor of the object being
2.5 timbl 350: searched
2.9 timbl 351: <DT>request->anchor
352: <DD> not filled in yet
2.5 timbl 353: </DL>
354:
355: <H3>On Exit,</H3>
356: <DL>
357: <DT>returns YES
2.6 timbl 358: <DD> Success in opening
2.5 timbl 359: file
360: <DT>NO
2.6 timbl 361: <DD> Failure
2.5 timbl 362: </DL>
1.1 timbl 363:
2.5 timbl 364: <PRE>extern BOOL HTLoadRelative PARAMS((
1.1 timbl 365: CONST char * relative_name,
2.9 timbl 366: HTParentAnchor * here,
367: HTRequest * request));
1.1 timbl 368:
369:
2.5 timbl 370: </PRE>
371: <H2>Load a document from absolute name</H2>
372: <H3>On Entry,</H3>
373: <DL>
374: <DT>addr
2.6 timbl 375: <DD> The absolute address of the
376: document to be accessed.
2.5 timbl 377: <DT>filter
2.6 timbl 378: <DD> if YES, treat document as
379: HTML
2.9 timbl 380: <DT>request->anchor
381: <DD> not filled in yet
2.5 timbl 382: </DL>
1.1 timbl 383:
2.5 timbl 384: <PRE>
385: </PRE>
386: <H3>On Exit,</H3>
387: <PRE>
388: </PRE>
389: <DL>
390: <DT>returns YES
2.6 timbl 391: <DD> Success in opening document
2.5 timbl 392: <DT>NO
2.6 timbl 393: <DD> Failure
2.5 timbl 394: </DL>
1.1 timbl 395:
2.9 timbl 396: <PRE>extern BOOL HTLoadAbsolute PARAMS((CONST char * addr,
397: HTRequest * request));
1.1 timbl 398:
399:
2.5 timbl 400: </PRE>
401: <H2>Load a document from absolute name
402: to a stream</H2>
403: <H3>On Entry,</H3>
404: <DL>
405: <DT>addr
2.6 timbl 406: <DD> The absolute address of the
407: document to be accessed.
2.5 timbl 408: <DT>filter
2.6 timbl 409: <DD> if YES, treat document as
410: HTML
2.9 timbl 411: <DT>request->anchor
412: <DD> not filled in yet
2.5 timbl 413: </DL>
414:
415: <H3>On Exit,</H3>
416: <DL>
417: <DT>returns YES
2.6 timbl 418: <DD> Success in opening document
2.5 timbl 419: <DT>NO
2.6 timbl 420: <DD> Failure
2.5 timbl 421: </DL>
422: Note: This is equivalent to HTLoadDocument
2.9 timbl 423: <PRE>extern BOOL HTLoadToStream PARAMS((
424: CONST char * addr,
425: BOOL filter,
426: HTRequest * request));
1.1 timbl 427:
428:
2.5 timbl 429: </PRE>
430: <H2>Load if necessary, and select an
2.9 timbl 431: anchor</H2>The anchor parameter may be a child
432: anchor. The anchor in the request
433: is set to the parent anchor.
2.5 timbl 434: <H3>On Entry,</H3>
435: <DL>
2.9 timbl 436: <DT>anchor
437: <DD> may be a child or parenet
438: anchor or 0 in which case there is
439: no effect.
440: <DT>request->anchor
441: <DD> Not set
442: yet.
2.5 timbl 443: </DL>
444:
445: <H3>On Exit,</H3>
446: <PRE>
447: </PRE>
448: <DL>
449: <DT>returns YES
2.6 timbl 450: <DD> Success
2.5 timbl 451: <DT>returns NO
2.6 timbl 452: <DD> Failure
2.9 timbl 453: <DT>request->anchor
454: <DD> The parenet anchor.
2.5 timbl 455: </DL>
456:
2.9 timbl 457: <PRE>extern BOOL HTLoadAnchor PARAMS((HTAnchor * a,
458: HTRequest * request));
1.1 timbl 459:
460:
2.5 timbl 461: </PRE>
2.24 luotonen 462:
463: <H2>Load a Document</H2>
464: This is an internal routine, which has an address AND a matching
465: anchor. (The public routines are called with one OR the other.)
466: This is, however, recursively called from file load module to
467: try ftp.
468:
469: <H3>On entry,</H3>
470: request->
471: <DL>
472: <DT> anchor <DD> a parent anchor with fully qualified
473: hypertext reference as its address set
474: <DT> output_format <DD> valid
475: <DT> output_stream <DD> valid on NULL
476: </DL>
477:
478: <H3>On exit,</H3>
479: returns
480: <DL>
481: <DT> <0 <DD> Error has occured.
482: <DT> HT_LOADED <DD> Success
483: <DT> HT_NO_DATA <DD> Success, but no document loaded.
484: (telnet sesssion started etc)
485: </DL>
486:
487: <PRE>
488: PUBLIC int HTLoad PARAMS((HTRequest * request));
489: </PRE>
490:
491:
2.20 frystyk 492: <H2>Bind an anchor to a request structure
493: without loading</H2>The anchor parameter may be a child
494: anchor. The anchor in the request
495: is set to the parent anchor. This
496: is useful in non-interactive mode
497: if no home-anchor is known. Actually
498: the same as HTLoadAnchor(), but without
499: loading
500: <H3>On Entry,</H3>
501: <DL>
502: <DT>anchor
503: <DD> may be a child or parenet
504: anchor or 0 in which case there is
505: no effect.
506: <DT>request->anchor
507: <DD> Not set yet.
508: </DL>
509:
510: <H3>On Exit,</H3>
511: <PRE>
512: </PRE>returns YES Success<P>
513: returns NO Failure <P>
514: request->anchor The parenet anchor.
515: <PRE>
516: extern BOOL HTBindAnchor PARAMS((HTAnchor *anchor, HTRequest *request));
517:
518:
519: </PRE>
2.5 timbl 520: <H2>Make a stream for Saving object back</H2>
521: <H3>On Entry,</H3>
522: <DL>
2.9 timbl 523: <DT>request->anchor
524: <DD> is valid anchor which
525: has previously beeing loaded
2.5 timbl 526: </DL>
527:
528: <H3>On exit,</H3>
529: <DL>
530: <DT>returns
2.6 timbl 531: <DD> 0 if error else a stream
532: to save the object to.
2.5 timbl 533: </DL>
534:
535: <PRE>
536:
2.13 timbl 537: extern HTStream * HTSaveStream PARAMS((HTRequest * request));
1.1 timbl 538:
539:
2.5 timbl 540: </PRE>
541: <H2>Search</H2>Performs a search on word given by
542: the user. Adds the search words to
543: the end of the current address and
544: attempts to open the new address.
545: <H3>On Entry,</H3>
546: <DL>
547: <DT>*keywords
2.6 timbl 548: <DD> space-separated keyword
2.5 timbl 549: list or similar search list
550: <DT>here
2.6 timbl 551: <DD> The anchor of the object being
2.5 timbl 552: searched
553: </DL>
1.1 timbl 554:
2.9 timbl 555: <PRE>extern BOOL HTSearch PARAMS((
556: CONST char * keywords,
557: HTParentAnchor* here,
558: HTRequest * request));
1.1 timbl 559:
560:
2.5 timbl 561: </PRE>
562: <H2>Search Given Indexname</H2>Performs a keyword search on word
563: given by the user. Adds the keyword
564: to the end of the current address
565: and attempts to open the new address.
566: <H3>On Entry,</H3>
567: <DL>
568: <DT>*keywords
2.6 timbl 569: <DD> space-separated keyword
2.5 timbl 570: list or similar search list
571: <DT>*indexname
2.6 timbl 572: <DD> is name of object search
2.5 timbl 573: is to be done on.
574: </DL>
1.1 timbl 575:
2.5 timbl 576: <PRE>extern BOOL HTSearchAbsolute PARAMS((
2.9 timbl 577: CONST char * keywords,
578: CONST char * indexname,
579: HTRequest * request));
1.1 timbl 580:
581:
2.5 timbl 582: </PRE>
2.9 timbl 583: <H2>Register an access method</H2>An access method is defined by an
584: HTProtocol structure which point
585: to the routines for performing the
586: various logical operations on an
587: object: in HTTP terms, GET, PUT,
588: and POST.<P>
589: Each of these routine takes as a
590: parameter a <A
591: NAME="z2" HREF="#z1">request structure</A> containing
592: details ofthe request. When the
593: protocol class routine is called,
594: the anchor elemnt in the request
595: is already valid (made valid by HTAccess).
596: <PRE>typedef struct _HTProtocol {
1.1 timbl 597: char * name;
598:
2.11 timbl 599: int (*load)PARAMS((HTRequest * request));
1.1 timbl 600:
2.11 timbl 601: HTStream* (*saveStream)PARAMS((HTRequest * request));
602:
2.9 timbl 603: HTStream* (*postStream)PARAMS((
604: HTRequest * request,
605: HTParentAnchor* postTo));
1.1 timbl 606:
607: } HTProtocol;
608:
609: extern BOOL HTRegisterProtocol PARAMS((HTProtocol * protocol));
610:
611:
2.5 timbl 612: </PRE>
613: <H2>Generate the anchor for the home
614: page</H2>
615: <PRE>
616: </PRE>As it involves file access, this
617: should only be done once when the
618: program first runs. This is a default
619: algorithm -- browser don't HAVE to
620: use this.
621: <PRE>extern HTParentAnchor * HTHomeAnchor NOPARAMS;
1.1 timbl 622:
2.25 luotonen 623: </PRE>
624:
625: <H2>Error Diagnostics</H2>
626: <PRE>
627:
628: PUBLIC void HTAddError PARAMS((HTRequest * req,
2.26 luotonen 629: CONST char * msg));
2.25 luotonen 630:
631: PUBLIC void HTAddError2 PARAMS((HTRequest * req,
2.26 luotonen 632: CONST char * msg,
633: CONST char * param));
2.25 luotonen 634:
635: PUBLIC void HTAddErrorN PARAMS((HTRequest * req,
2.26 luotonen 636: CONST char * msg,
2.25 luotonen 637: int param));
638:
639: PUBLIC void HTClearErrors PARAMS((HTRequest * req));
640:
641: </PRE>
642:
643: <PRE>
644:
1.1 timbl 645: #endif /* HTACCESS_H */
2.11 timbl 646:
2.25 luotonen 647: </PRE>
648: end of HTAccess
649: </BODY>
2.9 timbl 650: </HTML>
Webmaster