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