Annotation of libwww/Library/src/HTAccess.html, revision 2.14
2.9 timbl 1: <HTML>
2: <HEAD>
2.6 timbl 3: <TITLE>HTAccess: Access manager for libwww</TITLE>
2.13 timbl 4: <NEXTID N="z8">
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.9 timbl 18: NAME="z0" HREF="Overview.html">libwww library</A> .
2.5 timbl 19: <PRE>#ifndef HTACCESS_H
1.1 timbl 20: #define HTACCESS_H
21:
22: /* Definition uses:
23: */
24: #include "HTUtils.h"
25: #include "tcp.h"
2.14 ! luotonen 26: #include "HTGroup.h" /* HTAAFailReason */
! 27:
1.1 timbl 28:
29: #ifdef SHORT_NAMES
2.8 timbl 30: #define HTClientHost HTClHost
31: #define HTSearchAbsolute HTSeAbso
32: #define HTOutputStream HTOuStre
33: #define HTOutputFormat HTOuForm
1.1 timbl 34: #endif
35:
2.10 timbl 36: </PRE>The following have to be defined
37: in advance of the other include files
38: because of circular references.
39: <PRE>typedef struct _HTRequest HTRequest;
40:
2.14 ! luotonen 41: /*
! 42: ** Callback to call when username and password
! 43: ** have been prompted.
! 44: */
! 45: typedef int (*HTRetryCallbackType) PARAMS((HTRequest * req));
! 46:
! 47:
2.10 timbl 48: #include "HTAnchor.h"
49: #include <A
50: NAME="z3" HREF="HTFormat.html">"HTFormat.h"</A>
2.14 ! luotonen 51: #include "HTAAUtil.h" /* HTAAScheme */
! 52: #include "HTAuth.h" /* HTAAUser */
! 53: #include "HTAABrow.h" /* HTAASetup */
2.10 timbl 54:
55:
1.1 timbl 56: /* Return codes from load routines:
57: **
58: ** These codes may be returned by the protocol modules,
59: ** and by the HTLoad routines.
60: ** In general, positive codes are OK and negative ones are bad.
61: */
62:
63: #define HT_NO_DATA -9999 /* return code: OK but no data was loaded */
64: /* Typically, other app started or forked */
65:
2.5 timbl 66: </PRE>
2.6 timbl 67: <H2>Default Addresses</H2>These control the home page selection.
2.8 timbl 68: To mess with these for normal browses
2.6 timbl 69: is asking for user confusion.
70: <PRE>#define LOGICAL_DEFAULT "WWW_HOME" /* Defined to be the home page */
1.1 timbl 71:
2.6 timbl 72: #ifndef PERSONAL_DEFAULT
73: #define PERSONAL_DEFAULT "WWW/default.html" /* in home directory */
74: #endif
75: #ifndef LOCAL_DEFAULT_FILE
1.1 timbl 76: #define LOCAL_DEFAULT_FILE "/usr/local/lib/WWW/default.html"
2.6 timbl 77: #endif
2.7 timbl 78: /* If one telnets to a www access point,
79: it will look in this file for home page */
80: #ifndef REMOTE_POINTER
81: #define REMOTE_POINTER "/etc/www-remote.url" /* can't be file */
82: #endif
83: /* and if that fails it will use this. */
2.6 timbl 84: #ifndef REMOTE_ADDRESS
1.1 timbl 85: #define REMOTE_ADDRESS "http://info.cern.ch/remote.html" /* can't be file */
86: #endif
87:
88: /* If run from telnet daemon and no -l specified, use this file:
89: */
90: #ifndef DEFAULT_LOGFILE
91: #define DEFAULT_LOGFILE "/usr/adm/www-log/www-log"
92: #endif
93:
94: /* If the home page isn't found, use this file:
95: */
96: #ifndef LAST_RESORT
2.6 timbl 97: #define LAST_RESORT "http://info.cern.ch/default.html"
1.1 timbl 98: #endif
99:
2.10 timbl 100:
2.9 timbl 101: </PRE>
102: <H2><A
103: NAME="z1">The Request structure</A></H2>When a request is handled, all kinds
104: of things about it need to be passed
105: along. These are all put into a
2.11 timbl 106: HTRequest structure. Note there
107: is also a <A
2.12 timbl 108: NAME="z4" HREF="HTFormat.html#z17">global list of converters</A>
109: .
2.10 timbl 110: <PRE>struct _HTRequest {
2.11 timbl 111: HTList * <A
2.12 timbl 112: NAME="z5">conversions</A> ; /* conversions allowed in this case */
2.9 timbl 113: char * from; /* On behalf of whom? */
114: HTStream* output_stream; /* For non-interactive, set this */
2.10 timbl 115: HTAtom * output_format; /* To convert on load, set this */
2.9 timbl 116: BOOL (*callback) PARAMS((
117: struct _HTRequest* request,
118: void *param));
119: void * context; /* caller data -- HTAccess unaware */
120: HTParentAnchor* anchor; /* Set by HTAccess */
2.12 timbl 121: void * using_cache; /* pointer to cache element if cache hit */
2.14 ! luotonen 122: HTAtom * method; /* HTTP method */
2.13 timbl 123: HTChildAnchor * childAnchor; /* For element within the object */
2.14 ! luotonen 124: int content_length; /* MIME message Content-Length */
! 125: int status_code; /* HTTP status code */
! 126: char * reason_line; /* Reason for failing */
! 127: /*
! 128: ** Server side info about request
! 129: */
! 130: char * request; /* First request line as received */
! 131: char * argument; /* Arg to HTTP method as given */
! 132: char * arg_path; /* Pathinfo part of argument */
! 133: char * arg_keywords; /* ?keywords part of argument */
! 134: char * simplified; /* Simplified filename */
! 135: char * translated; /* Translated filename */
! 136: char * script; /* Executable server script name */
! 137: char * script_pathinfo;/* Path info after script name */
! 138: BOOL cgi_script; /* If a CGI/1.0 script */
! 139: char * location; /* Location for redirection */
! 140: char * redir_on_fly; /* Non-full URL location on local */
! 141: /*
! 142: ** Access Authorization
! 143: */
! 144: char * authorization; /* Authorization: field */
! 145: HTAAScheme scheme; /* Authentication scheme used */
! 146: char * auth_string; /* Authentication string */
! 147: /*
! 148: ** Server side AA
! 149: */
! 150: HTAAProt * prot; /* Protection (Protect rule) */
! 151: HTAAProt * def_prot; /* Default prot (DefProt rule) */
! 152: HTAAUser * user; /* Authenticated user */
! 153: HTAAFailReason reason; /* Reason for failing */
! 154: /*
! 155: ** Client side AA
! 156: */
! 157: HTList * valid_schemes; /* Valid auth.schemes */
! 158: HTAssocList ** scheme_specifics;/* Scheme-specific parameters */
! 159: char * prot_template; /* WWW-Protection-Template: field */
! 160: HTAASetup * setup; /* Doc protection info */
! 161: HTAARealm * realm; /* Password realm */
! 162: char * dialog_msg; /* Authentication prompt (client) */
! 163: HTRetryCallbackType
! 164: retry_callback; /* Called when password entered */
! 165: #ifdef OLD_CODE
! 166: void (*retry_callback) PARAMS((
! 167: struct _HTRequest * request
! 168: )); /* Call this when password entered*/
! 169: #endif
2.10 timbl 170: };
2.9 timbl 171:
172: </PRE>The elements of the request structure
173: are as follows.
174: <DL>
2.14 ! luotonen 175: <DT><CODE>method</CODE>
2.13 timbl 176: <DD>An atom for the name of the
177: operation using HTTP <A
178: NAME="z7" HREF="../../Protocols/HTTP/Methods.html">method names</A>.
2.14 ! luotonen 179: <DT><CODE>conversions</CODE>
2.10 timbl 180: <DD> NULL, or a list of conversions
2.9 timbl 181: which the format manager can do in
182: order to fulfill the request. This
183: is set by the caller of HTAccess.
2.10 timbl 184: Typically points to a list set up
2.9 timbl 185: an initialisation time for example
186: by HTInit.
2.14 ! luotonen 187: <DT><CODE>from</CODE>
! 188: <DD>Email format adderss of person
2.9 timbl 189: responible for request
2.14 ! luotonen 190: <DT><CODE>output_stream</CODE>
! 191: <DD>NULL or if a specific
2.9 timbl 192: output stream is required, te stream.
2.14 ! luotonen 193: <DT><CODE>output_format</CODE>
! 194: <DD>The output format required,
2.9 timbl 195: or a generic format such as www/present
196: (present to user).
2.14 ! luotonen 197: <DT><CODE>anchor</CODE>
! 198: <DD>The anchor for teh object in
! 199: question. NOTE: Set by HTAcesss.
2.13 timbl 200: <DT><A
201: NAME="z6">childAnchor</A>
202: <DD>the anchor for the subobject
203: if any. The object builder should
204: ensure that htis is selected, highlighted,
205: etc when the object is loaded. NOTE:
206: Set by HTAccess.
2.14 ! luotonen 207: <DT><CODE>simplified</CODE>
! 208: <DD>Simplified filename (after removing <CODE>..</CODE> etc).
! 209: <DT><CODE>translated</CODE>
! 210: <DD>Translated filename (set by function <CODE>HTTranslateReq().</CODE>
! 211: <CODE>NULL,</CODE> if this is a script execution request.
! 212: <DT><CODE>script</CODE>
! 213: <DD>Executable script name (set by <CODE>HTTranslateReq().</CODE>
! 214: <CODE>NULL</CODE> if not a script request.
! 215: <DT><CODE>authorization</CODE>
! 216: <DD><CODE>Authorization:</CODE> field contents.
! 217: <DT><CODE>scheme</CODE>
! 218: <DD>Authentication scheme used.
! 219: <DT><CODE>scheme_specifics</CODE>
! 220: <DD>Authentication scheme specific information.
! 221: <DT><CODE>user</CODE>
! 222: <DD>Authenticated user.
2.9 timbl 223: </DL>
224: Just to make things easier especially
225: for clients, here is a function to
226: return a new blank request:
227: <H2>Create blank request</H2>This request has defaults in -- in
228: most cases it will need some information
229: added before being passed to HTAccess,
230: but it will work as is for a simple
231: request.
2.14 ! luotonen 232: <PRE>
! 233: PUBLIC HTRequest * HTRequest_new NOPARAMS;
! 234:
! 235:
! 236: </PRE>
! 237: <H2>Delete request structure</H2>
! 238: Frees also conversion list hanging from <CODE>req->conversions.</CODE>
! 239: <PRE>
! 240: PUBLIC void HTRequest_delete PARAMS((HTRequest * req));
1.1 timbl 241:
2.9 timbl 242:
2.5 timbl 243: </PRE>
244: <H2>Flags which may be set to control
245: this module</H2>
246: <PRE>extern int HTDiag; /* Flag: load source as plain text */
1.1 timbl 247: extern char * HTClientHost; /* Name or number of telnetting host */
248: extern FILE * logfile; /* File to output one-liners to */
2.7 timbl 249: extern BOOL HTSecure; /* Disable security holes? */
1.1 timbl 250:
251:
252:
2.5 timbl 253: </PRE>
254: <H2>Load a document from relative name</H2>
255: <H3>On Entry,</H3>
256: <DL>
257: <DT>relative_name
2.6 timbl 258: <DD> The relative address
2.5 timbl 259: of the file to be accessed.
260: <DT>here
2.6 timbl 261: <DD> The anchor of the object being
2.5 timbl 262: searched
2.9 timbl 263: <DT>request->anchor
264: <DD> not filled in yet
2.5 timbl 265: </DL>
266:
267: <H3>On Exit,</H3>
268: <DL>
269: <DT>returns YES
2.6 timbl 270: <DD> Success in opening
2.5 timbl 271: file
272: <DT>NO
2.6 timbl 273: <DD> Failure
2.5 timbl 274: </DL>
1.1 timbl 275:
2.5 timbl 276: <PRE>extern BOOL HTLoadRelative PARAMS((
1.1 timbl 277: CONST char * relative_name,
2.9 timbl 278: HTParentAnchor * here,
279: HTRequest * request));
1.1 timbl 280:
281:
2.5 timbl 282: </PRE>
283: <H2>Load a document from absolute name</H2>
284: <H3>On Entry,</H3>
285: <DL>
286: <DT>addr
2.6 timbl 287: <DD> The absolute address of the
288: document to be accessed.
2.5 timbl 289: <DT>filter
2.6 timbl 290: <DD> if YES, treat document as
291: HTML
2.9 timbl 292: <DT>request->anchor
293: <DD> not filled in yet
2.5 timbl 294: </DL>
1.1 timbl 295:
2.5 timbl 296: <PRE>
297: </PRE>
298: <H3>On Exit,</H3>
299: <PRE>
300: </PRE>
301: <DL>
302: <DT>returns YES
2.6 timbl 303: <DD> Success in opening document
2.5 timbl 304: <DT>NO
2.6 timbl 305: <DD> Failure
2.5 timbl 306: </DL>
1.1 timbl 307:
2.9 timbl 308: <PRE>extern BOOL HTLoadAbsolute PARAMS((CONST char * addr,
309: HTRequest * request));
1.1 timbl 310:
311:
2.5 timbl 312: </PRE>
313: <H2>Load a document from absolute name
314: to a stream</H2>
315: <H3>On Entry,</H3>
316: <DL>
317: <DT>addr
2.6 timbl 318: <DD> The absolute address of the
319: document to be accessed.
2.5 timbl 320: <DT>filter
2.6 timbl 321: <DD> if YES, treat document as
322: HTML
2.9 timbl 323: <DT>request->anchor
324: <DD> not filled in yet
2.5 timbl 325: </DL>
326:
327: <H3>On Exit,</H3>
328: <DL>
329: <DT>returns YES
2.6 timbl 330: <DD> Success in opening document
2.5 timbl 331: <DT>NO
2.6 timbl 332: <DD> Failure
2.5 timbl 333: </DL>
334: Note: This is equivalent to HTLoadDocument
2.9 timbl 335: <PRE>extern BOOL HTLoadToStream PARAMS((
336: CONST char * addr,
337: BOOL filter,
338: HTRequest * request));
1.1 timbl 339:
340:
2.5 timbl 341: </PRE>
342: <H2>Load if necessary, and select an
2.9 timbl 343: anchor</H2>The anchor parameter may be a child
344: anchor. The anchor in the request
345: is set to the parent anchor.
2.5 timbl 346: <H3>On Entry,</H3>
347: <DL>
2.9 timbl 348: <DT>anchor
349: <DD> may be a child or parenet
350: anchor or 0 in which case there is
351: no effect.
352: <DT>request->anchor
353: <DD> Not set
354: yet.
2.5 timbl 355: </DL>
356:
357: <H3>On Exit,</H3>
358: <PRE>
359: </PRE>
360: <DL>
361: <DT>returns YES
2.6 timbl 362: <DD> Success
2.5 timbl 363: <DT>returns NO
2.6 timbl 364: <DD> Failure
2.9 timbl 365: <DT>request->anchor
366: <DD> The parenet anchor.
2.5 timbl 367: </DL>
368:
2.9 timbl 369: <PRE>extern BOOL HTLoadAnchor PARAMS((HTAnchor * a,
370: HTRequest * request));
1.1 timbl 371:
372:
2.5 timbl 373: </PRE>
374: <H2>Make a stream for Saving object back</H2>
375: <H3>On Entry,</H3>
376: <DL>
2.9 timbl 377: <DT>request->anchor
378: <DD> is valid anchor which
379: has previously beeing loaded
2.5 timbl 380: </DL>
381:
382: <H3>On exit,</H3>
383: <DL>
384: <DT>returns
2.6 timbl 385: <DD> 0 if error else a stream
386: to save the object to.
2.5 timbl 387: </DL>
388:
389: <PRE>
390:
2.13 timbl 391: extern HTStream * HTSaveStream PARAMS((HTRequest * request));
1.1 timbl 392:
393:
2.5 timbl 394: </PRE>
395: <H2>Search</H2>Performs a search on word given by
396: the user. Adds the search words to
397: the end of the current address and
398: attempts to open the new address.
399: <H3>On Entry,</H3>
400: <DL>
401: <DT>*keywords
2.6 timbl 402: <DD> space-separated keyword
2.5 timbl 403: list or similar search list
404: <DT>here
2.6 timbl 405: <DD> The anchor of the object being
2.5 timbl 406: searched
407: </DL>
1.1 timbl 408:
2.9 timbl 409: <PRE>extern BOOL HTSearch PARAMS((
410: CONST char * keywords,
411: HTParentAnchor* here,
412: HTRequest * request));
1.1 timbl 413:
414:
2.5 timbl 415: </PRE>
416: <H2>Search Given Indexname</H2>Performs a keyword search on word
417: given by the user. Adds the keyword
418: to the end of the current address
419: and attempts to open the new address.
420: <H3>On Entry,</H3>
421: <DL>
422: <DT>*keywords
2.6 timbl 423: <DD> space-separated keyword
2.5 timbl 424: list or similar search list
425: <DT>*indexname
2.6 timbl 426: <DD> is name of object search
2.5 timbl 427: is to be done on.
428: </DL>
1.1 timbl 429:
2.5 timbl 430: <PRE>extern BOOL HTSearchAbsolute PARAMS((
2.9 timbl 431: CONST char * keywords,
432: CONST char * indexname,
433: HTRequest * request));
1.1 timbl 434:
435:
2.5 timbl 436: </PRE>
2.9 timbl 437: <H2>Register an access method</H2>An access method is defined by an
438: HTProtocol structure which point
439: to the routines for performing the
440: various logical operations on an
441: object: in HTTP terms, GET, PUT,
442: and POST.<P>
443: Each of these routine takes as a
444: parameter a <A
445: NAME="z2" HREF="#z1">request structure</A> containing
446: details ofthe request. When the
447: protocol class routine is called,
448: the anchor elemnt in the request
449: is already valid (made valid by HTAccess).
450: <PRE>typedef struct _HTProtocol {
1.1 timbl 451: char * name;
452:
2.11 timbl 453: int (*load)PARAMS((HTRequest * request));
1.1 timbl 454:
2.11 timbl 455: HTStream* (*saveStream)PARAMS((HTRequest * request));
456:
2.9 timbl 457: HTStream* (*postStream)PARAMS((
458: HTRequest * request,
459: HTParentAnchor* postTo));
1.1 timbl 460:
461: } HTProtocol;
462:
463: extern BOOL HTRegisterProtocol PARAMS((HTProtocol * protocol));
464:
465:
2.5 timbl 466: </PRE>
467: <H2>Generate the anchor for the home
468: page</H2>
469: <PRE>
470: </PRE>As it involves file access, this
471: should only be done once when the
472: program first runs. This is a default
473: algorithm -- browser don't HAVE to
474: use this.
475: <PRE>extern HTParentAnchor * HTHomeAnchor NOPARAMS;
1.1 timbl 476:
477: #endif /* HTACCESS_H */
2.11 timbl 478:
2.12 timbl 479: </PRE>end of HTAccess</BODY>
2.9 timbl 480: </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