Annotation of libwww/Library/src/HTAccess.html, revision 2.13
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"
26:
27: #ifdef SHORT_NAMES
2.8 timbl 28: #define HTClientHost HTClHost
29: #define HTSearchAbsolute HTSeAbso
30: #define HTOutputStream HTOuStre
31: #define HTOutputFormat HTOuForm
1.1 timbl 32: #endif
33:
2.10 timbl 34: </PRE>The following have to be defined
35: in advance of the other include files
36: because of circular references.
37: <PRE>typedef struct _HTRequest HTRequest;
38:
39: #include "HTAnchor.h"
40: #include <A
41: NAME="z3" HREF="HTFormat.html">"HTFormat.h"</A>
42:
43:
1.1 timbl 44: /* Return codes from load routines:
45: **
46: ** These codes may be returned by the protocol modules,
47: ** and by the HTLoad routines.
48: ** In general, positive codes are OK and negative ones are bad.
49: */
50:
51: #define HT_NO_DATA -9999 /* return code: OK but no data was loaded */
52: /* Typically, other app started or forked */
53:
2.5 timbl 54: </PRE>
2.6 timbl 55: <H2>Default Addresses</H2>These control the home page selection.
2.8 timbl 56: To mess with these for normal browses
2.6 timbl 57: is asking for user confusion.
58: <PRE>#define LOGICAL_DEFAULT "WWW_HOME" /* Defined to be the home page */
1.1 timbl 59:
2.6 timbl 60: #ifndef PERSONAL_DEFAULT
61: #define PERSONAL_DEFAULT "WWW/default.html" /* in home directory */
62: #endif
63: #ifndef LOCAL_DEFAULT_FILE
1.1 timbl 64: #define LOCAL_DEFAULT_FILE "/usr/local/lib/WWW/default.html"
2.6 timbl 65: #endif
2.7 timbl 66: /* If one telnets to a www access point,
67: it will look in this file for home page */
68: #ifndef REMOTE_POINTER
69: #define REMOTE_POINTER "/etc/www-remote.url" /* can't be file */
70: #endif
71: /* and if that fails it will use this. */
2.6 timbl 72: #ifndef REMOTE_ADDRESS
1.1 timbl 73: #define REMOTE_ADDRESS "http://info.cern.ch/remote.html" /* can't be file */
74: #endif
75:
76: /* If run from telnet daemon and no -l specified, use this file:
77: */
78: #ifndef DEFAULT_LOGFILE
79: #define DEFAULT_LOGFILE "/usr/adm/www-log/www-log"
80: #endif
81:
82: /* If the home page isn't found, use this file:
83: */
84: #ifndef LAST_RESORT
2.6 timbl 85: #define LAST_RESORT "http://info.cern.ch/default.html"
1.1 timbl 86: #endif
87:
2.10 timbl 88:
2.9 timbl 89: </PRE>
90: <H2><A
91: NAME="z1">The Request structure</A></H2>When a request is handled, all kinds
92: of things about it need to be passed
93: along. These are all put into a
2.11 timbl 94: HTRequest structure. Note there
95: is also a <A
2.12 timbl 96: NAME="z4" HREF="HTFormat.html#z17">global list of converters</A>
97: .
2.10 timbl 98: <PRE>struct _HTRequest {
2.11 timbl 99: HTList * <A
2.12 timbl 100: NAME="z5">conversions</A> ; /* conversions allowed in this case */
2.9 timbl 101: char * from; /* On behalf of whom? */
102: HTStream* output_stream; /* For non-interactive, set this */
2.10 timbl 103: HTAtom * output_format; /* To convert on load, set this */
2.9 timbl 104: BOOL (*callback) PARAMS((
105: struct _HTRequest* request,
106: void *param));
107: void * context; /* caller data -- HTAccess unaware */
108:
109: HTParentAnchor* anchor; /* Set by HTAccess */
2.12 timbl 110:
111: void * using_cache; /* pointer to cache element if cache hit */
2.13 ! timbl 112: HTAtom * method; /* Operation code */
! 113: HTChildAnchor * childAnchor; /* For element within the object */
2.12 timbl 114:
2.9 timbl 115: /* To be added: authentication, etc */
2.10 timbl 116: };
2.9 timbl 117:
118: </PRE>The elements of the request structure
119: are as follows.
120: <DL>
2.13 ! timbl 121: <DT>method
! 122: <DD>An atom for the name of the
! 123: operation using HTTP <A
! 124: NAME="z7" HREF="../../Protocols/HTTP/Methods.html">method names</A>.
2.9 timbl 125: <DT>conversions
2.10 timbl 126: <DD> NULL, or a list of conversions
2.9 timbl 127: which the format manager can do in
128: order to fulfill the request. This
129: is set by the caller of HTAccess.
2.10 timbl 130: Typically points to a list set up
2.9 timbl 131: an initialisation time for example
132: by HTInit.
133: <DT>from
2.10 timbl 134: <DD> Email format adderss of person
2.9 timbl 135: responible for request
136: <DT>output_stream
2.10 timbl 137: <DD> NULL or if a specific
2.9 timbl 138: output stream is required, te stream.
139: <DT>output_format
2.10 timbl 140: <DD> The output format required,
2.9 timbl 141: or a generic format such as www/present
142: (present to user).
143: <DT>anchor
2.13 ! timbl 144: <DD> The anchor for the object
2.10 timbl 145: in question. NOTE: Set by HTAcesss.
2.13 ! timbl 146: <DT><A
! 147: NAME="z6">childAnchor</A>
! 148: <DD>the anchor for the subobject
! 149: if any. The object builder should
! 150: ensure that htis is selected, highlighted,
! 151: etc when the object is loaded. NOTE:
! 152: Set by HTAccess.
2.9 timbl 153: </DL>
154: Just to make things easier especially
155: for clients, here is a function to
156: return a new blank request:
157: <H2>Create blank request</H2>This request has defaults in -- in
158: most cases it will need some information
159: added before being passed to HTAccess,
160: but it will work as is for a simple
161: request.
162: <PRE>extern HTRequest * HTRequest_new NOPARAMS;
1.1 timbl 163:
2.9 timbl 164:
2.5 timbl 165: </PRE>
166: <H2>Flags which may be set to control
167: this module</H2>
168: <PRE>extern int HTDiag; /* Flag: load source as plain text */
1.1 timbl 169: extern char * HTClientHost; /* Name or number of telnetting host */
170: extern FILE * logfile; /* File to output one-liners to */
2.7 timbl 171: extern BOOL HTSecure; /* Disable security holes? */
1.1 timbl 172:
173:
174:
2.5 timbl 175: </PRE>
176: <H2>Load a document from relative name</H2>
177: <H3>On Entry,</H3>
178: <DL>
179: <DT>relative_name
2.6 timbl 180: <DD> The relative address
2.5 timbl 181: of the file to be accessed.
182: <DT>here
2.6 timbl 183: <DD> The anchor of the object being
2.5 timbl 184: searched
2.9 timbl 185: <DT>request->anchor
186: <DD> not filled in yet
2.5 timbl 187: </DL>
188:
189: <H3>On Exit,</H3>
190: <DL>
191: <DT>returns YES
2.6 timbl 192: <DD> Success in opening
2.5 timbl 193: file
194: <DT>NO
2.6 timbl 195: <DD> Failure
2.5 timbl 196: </DL>
1.1 timbl 197:
2.5 timbl 198: <PRE>extern BOOL HTLoadRelative PARAMS((
1.1 timbl 199: CONST char * relative_name,
2.9 timbl 200: HTParentAnchor * here,
201: HTRequest * request));
1.1 timbl 202:
203:
2.5 timbl 204: </PRE>
205: <H2>Load a document from absolute name</H2>
206: <H3>On Entry,</H3>
207: <DL>
208: <DT>addr
2.6 timbl 209: <DD> The absolute address of the
210: document to be accessed.
2.5 timbl 211: <DT>filter
2.6 timbl 212: <DD> if YES, treat document as
213: HTML
2.9 timbl 214: <DT>request->anchor
215: <DD> not filled in yet
2.5 timbl 216: </DL>
1.1 timbl 217:
2.5 timbl 218: <PRE>
219: </PRE>
220: <H3>On Exit,</H3>
221: <PRE>
222: </PRE>
223: <DL>
224: <DT>returns YES
2.6 timbl 225: <DD> Success in opening document
2.5 timbl 226: <DT>NO
2.6 timbl 227: <DD> Failure
2.5 timbl 228: </DL>
1.1 timbl 229:
2.9 timbl 230: <PRE>extern BOOL HTLoadAbsolute PARAMS((CONST char * addr,
231: HTRequest * request));
1.1 timbl 232:
233:
2.5 timbl 234: </PRE>
235: <H2>Load a document from absolute name
236: to a stream</H2>
237: <H3>On Entry,</H3>
238: <DL>
239: <DT>addr
2.6 timbl 240: <DD> The absolute address of the
241: document to be accessed.
2.5 timbl 242: <DT>filter
2.6 timbl 243: <DD> if YES, treat document as
244: HTML
2.9 timbl 245: <DT>request->anchor
246: <DD> not filled in yet
2.5 timbl 247: </DL>
248:
249: <H3>On Exit,</H3>
250: <DL>
251: <DT>returns YES
2.6 timbl 252: <DD> Success in opening document
2.5 timbl 253: <DT>NO
2.6 timbl 254: <DD> Failure
2.5 timbl 255: </DL>
256: Note: This is equivalent to HTLoadDocument
2.9 timbl 257: <PRE>extern BOOL HTLoadToStream PARAMS((
258: CONST char * addr,
259: BOOL filter,
260: HTRequest * request));
1.1 timbl 261:
262:
2.5 timbl 263: </PRE>
264: <H2>Load if necessary, and select an
2.9 timbl 265: anchor</H2>The anchor parameter may be a child
266: anchor. The anchor in the request
267: is set to the parent anchor.
2.5 timbl 268: <H3>On Entry,</H3>
269: <DL>
2.9 timbl 270: <DT>anchor
271: <DD> may be a child or parenet
272: anchor or 0 in which case there is
273: no effect.
274: <DT>request->anchor
275: <DD> Not set
276: yet.
2.5 timbl 277: </DL>
278:
279: <H3>On Exit,</H3>
280: <PRE>
281: </PRE>
282: <DL>
283: <DT>returns YES
2.6 timbl 284: <DD> Success
2.5 timbl 285: <DT>returns NO
2.6 timbl 286: <DD> Failure
2.9 timbl 287: <DT>request->anchor
288: <DD> The parenet anchor.
2.5 timbl 289: </DL>
290:
2.9 timbl 291: <PRE>extern BOOL HTLoadAnchor PARAMS((HTAnchor * a,
292: HTRequest * request));
1.1 timbl 293:
294:
2.5 timbl 295: </PRE>
296: <H2>Make a stream for Saving object back</H2>
297: <H3>On Entry,</H3>
298: <DL>
2.9 timbl 299: <DT>request->anchor
300: <DD> is valid anchor which
301: has previously beeing loaded
2.5 timbl 302: </DL>
303:
304: <H3>On exit,</H3>
305: <DL>
306: <DT>returns
2.6 timbl 307: <DD> 0 if error else a stream
308: to save the object to.
2.5 timbl 309: </DL>
310:
311: <PRE>
312:
2.13 ! timbl 313: extern HTStream * HTSaveStream PARAMS((HTRequest * request));
1.1 timbl 314:
315:
2.5 timbl 316: </PRE>
317: <H2>Search</H2>Performs a search on word given by
318: the user. Adds the search words to
319: the end of the current address and
320: attempts to open the new address.
321: <H3>On Entry,</H3>
322: <DL>
323: <DT>*keywords
2.6 timbl 324: <DD> space-separated keyword
2.5 timbl 325: list or similar search list
326: <DT>here
2.6 timbl 327: <DD> The anchor of the object being
2.5 timbl 328: searched
329: </DL>
1.1 timbl 330:
2.9 timbl 331: <PRE>extern BOOL HTSearch PARAMS((
332: CONST char * keywords,
333: HTParentAnchor* here,
334: HTRequest * request));
1.1 timbl 335:
336:
2.5 timbl 337: </PRE>
338: <H2>Search Given Indexname</H2>Performs a keyword search on word
339: given by the user. Adds the keyword
340: to the end of the current address
341: and attempts to open the new address.
342: <H3>On Entry,</H3>
343: <DL>
344: <DT>*keywords
2.6 timbl 345: <DD> space-separated keyword
2.5 timbl 346: list or similar search list
347: <DT>*indexname
2.6 timbl 348: <DD> is name of object search
2.5 timbl 349: is to be done on.
350: </DL>
1.1 timbl 351:
2.5 timbl 352: <PRE>extern BOOL HTSearchAbsolute PARAMS((
2.9 timbl 353: CONST char * keywords,
354: CONST char * indexname,
355: HTRequest * request));
1.1 timbl 356:
357:
2.5 timbl 358: </PRE>
2.9 timbl 359: <H2>Register an access method</H2>An access method is defined by an
360: HTProtocol structure which point
361: to the routines for performing the
362: various logical operations on an
363: object: in HTTP terms, GET, PUT,
364: and POST.<P>
365: Each of these routine takes as a
366: parameter a <A
367: NAME="z2" HREF="#z1">request structure</A> containing
368: details ofthe request. When the
369: protocol class routine is called,
370: the anchor elemnt in the request
371: is already valid (made valid by HTAccess).
372: <PRE>typedef struct _HTProtocol {
1.1 timbl 373: char * name;
374:
2.11 timbl 375: int (*load)PARAMS((HTRequest * request));
1.1 timbl 376:
2.11 timbl 377: HTStream* (*saveStream)PARAMS((HTRequest * request));
378:
2.9 timbl 379: HTStream* (*postStream)PARAMS((
380: HTRequest * request,
381: HTParentAnchor* postTo));
1.1 timbl 382:
383: } HTProtocol;
384:
385: extern BOOL HTRegisterProtocol PARAMS((HTProtocol * protocol));
386:
387:
2.5 timbl 388: </PRE>
389: <H2>Generate the anchor for the home
390: page</H2>
391: <PRE>
392: </PRE>As it involves file access, this
393: should only be done once when the
394: program first runs. This is a default
395: algorithm -- browser don't HAVE to
396: use this.
397: <PRE>extern HTParentAnchor * HTHomeAnchor NOPARAMS;
1.1 timbl 398:
399: #endif /* HTACCESS_H */
2.11 timbl 400:
2.12 timbl 401: </PRE>end of HTAccess</BODY>
2.9 timbl 402: </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