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