Annotation of libwww/Library/src/HTAccess.html, revision 2.44
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>
2.39 frystyk 7:
2.33 frystyk 8: <H1>Access Manager</H1>
2.39 frystyk 9:
2.41 frystyk 10: <PRE>
11: /*
12: ** (c) COPYRIGHT CERN 1994.
13: ** Please first read the full copyright statement in the file COPYRIGH.
14: */
15: </PRE>
16:
2.39 frystyk 17: This module keeps a list of valid protocol (naming scheme) specifiers
18: with associated access code. It allows documents to be loaded given
19: various combinations of parameters. New access protocols may be
20: registered at any time.<P>
21:
22: <B>Note:</B> HTRequest defined and request parameter added to almost
23: all calls 18 Nov 1993.<P>
24:
25: This module is implemented by <A HREF="HTAccess.c">HTAccess.c</A>, and
26: it is a part of the <A NAME="z10"
27: HREF="http://info.cern.ch/hypertext/WWW/Library/User/Guide/Guide.html">Library
28: of Common Code</A>. <P>
29:
30: The module contains a lot of stuff but the main topics are:
31:
32: <UL>
2.41 frystyk 33: <LI><A HREF="#Library">Initializing and Terminating the Library</A>
2.39 frystyk 34: <LI><A HREF="#Methods">Management of access methods</A>
35: <LI><A HREF="#Addresses">A lot of hard coded addresses</A>
36: <LI><A HREF="#z1">The HTRequest structure</A>
37: <LI><A HREF="#z100">Management of the HTRequest structure</A>
38: <LI><A HREF="#LoadDoc">Functions for loading a document</A>
39: <LI><A HREF="#ClientHelp">Help functions for clients to get started</A>
40: <LI><A HREF="#PostDoc">Functions for posting a document</A>
41: <LI><A HREF="#ProtReg">Access Method Registration</H2></A>
42: </UL>
43:
2.33 frystyk 44:
45: <PRE>
46: #ifndef HTACCESS_H
1.1 timbl 47: #define HTACCESS_H
2.44 ! roeber 48:
! 49: #include "sysdep.h"
2.16 luotonen 50: #include "HTList.h"
2.39 frystyk 51: #include "HTChunk.h"
2.35 frystyk 52: </PRE>
1.1 timbl 53:
2.35 frystyk 54: <B>Short Names</B>
55: <PRE>
1.1 timbl 56: #ifdef SHORT_NAMES
2.8 timbl 57: #define HTClientHost HTClHost
58: #define HTSearchAbsolute HTSeAbso
59: #define HTOutputStream HTOuStre
60: #define HTOutputFormat HTOuForm
1.1 timbl 61: #endif
2.33 frystyk 62: </PRE>
1.1 timbl 63:
2.36 frystyk 64: <H2>Flags which may be set to control this module</H2>
65:
66: <PRE>
67: extern char * HTSaveLocallyDir; /* Dir home for "save locally" files */
68: extern char * HTCacheDir; /* Cache dir, default NULL: no cache */
69: extern char * HTClientHost; /* Name or number of telnetting host */
70: extern FILE * HTlogfile; /* File to output one-liners to */
71: extern BOOL HTSecure; /* Disable security holes? */
72: extern char * HTImServer; /* If I'm cern_httpd */
73: extern BOOL HTImProxy; /* If I'm cern_httpd as a proxy */
74: extern BOOL HTForceReload; /* Force reload from cache or net */
75: </PRE>
76:
2.41 frystyk 77: <A NAME="Library"><H2>Initializing and Terminating the Library</H2></A>
78:
79: <IMG SRC="http://info.cern.ch/hypertext/WWW/Icons/32x32/warning.gif">
80: These two functions initiates memory and settings for the Library and
81: cleans up memory kept by the Library when about to exit the
82: application. It is highly recommended that they are used!
83:
84: <PRE>
85: extern BOOL HTLibInit NOPARAMS;
86: extern BOOL HTLibTerminate NOPARAMS;
87: </PRE>
88:
2.39 frystyk 89: <A NAME="Methods"><H2>Method Management</H2></A>
2.33 frystyk 90:
2.41 frystyk 91: These are the valid methods, see <A
2.39 frystyk 92: HREF="http://info.cern.ch/hypertext/WWW/Protocols/HTTP/Methods.html">HTTP
93: Methods</A>
2.33 frystyk 94:
95: <PRE>
2.16 luotonen 96: typedef enum {
97: METHOD_INVALID = 0,
98: METHOD_GET = 1,
99: METHOD_HEAD,
100: METHOD_POST,
101: METHOD_PUT,
102: METHOD_DELETE,
103: METHOD_CHECKOUT,
104: METHOD_CHECKIN,
105: METHOD_SHOWMETHOD,
106: METHOD_LINK,
107: METHOD_UNLINK,
108: MAX_METHODS
109: } HTMethod;
2.33 frystyk 110: </PRE>
111:
112: <H3>Get Method Enumeration</H3>
2.16 luotonen 113:
2.33 frystyk 114: Gives the enumeration value of the method as a function of the (char *) name.
2.16 luotonen 115:
2.33 frystyk 116: <PRE>
2.40 frystyk 117: extern HTMethod HTMethod_enum PARAMS((char * name));
2.16 luotonen 118: </PRE>
119:
2.33 frystyk 120: <H3>Get Method String</H3>
2.16 luotonen 121:
2.33 frystyk 122: The reverse of <I>HTMethod_enum()</I>
2.16 luotonen 123:
2.33 frystyk 124: <PRE>
2.40 frystyk 125: extern char * HTMethod_name PARAMS((HTMethod method));
2.33 frystyk 126: </PRE>
127:
128: <H3>Valid Methods</H3>
2.16 luotonen 129:
2.33 frystyk 130: This functions searches the list of valid methods for a given anchor, see
131: <A HREF="HTAnchor.html">HTAnchor module</A> If the method is found it returns
132: YES else NO.
2.16 luotonen 133:
2.33 frystyk 134: <PRE>
2.40 frystyk 135: extern BOOL HTMethod_inList PARAMS((HTMethod method,
2.16 luotonen 136: HTList * list));
137: </PRE>
2.33 frystyk 138:
2.35 frystyk 139: <HR>
140: <EM>This section might be move to the Access Authentication Module</EM>
141:
2.36 frystyk 142: <H4>Match Template Against Filename</H4>
2.16 luotonen 143: <PRE>
2.40 frystyk 144: /* extern HTAA_templateMatch()
2.16 luotonen 145: ** STRING COMPARISON FUNCTION FOR FILE NAMES
146: ** WITH ONE WILDCARD * IN THE TEMPLATE
147: ** NOTE:
148: ** This is essentially the same code as in HTRules.c, but it
149: ** cannot be used because it is embedded in between other code.
150: ** (In fact, HTRules.c should use this routine, but then this
151: ** routine would have to be more sophisticated... why is life
152: ** sometimes so hard...)
153: **
154: ** ON ENTRY:
2.37 frystyk 155: ** tmplate is a template string to match the file name
2.16 luotonen 156: ** agaist, may contain a single wildcard
157: ** character * which matches zero or more
158: ** arbitrary characters.
159: ** filename is the filename (or pathname) to be matched
160: ** agaist the template.
161: **
162: ** ON EXIT:
163: ** returns YES, if filename matches the template.
164: ** NO, otherwise.
165: */
2.40 frystyk 166: extern BOOL HTAA_templateMatch PARAMS((CONST char * tmplate,
2.16 luotonen 167: CONST char * filename));
2.35 frystyk 168: </PRE>
2.16 luotonen 169:
2.35 frystyk 170: <HR>
2.16 luotonen 171:
2.35 frystyk 172: The following have to be defined
2.10 timbl 173: in advance of the other include files
174: because of circular references.
2.33 frystyk 175: <PRE>
176: typedef struct _HTRequest HTRequest;
2.39 frystyk 177: typedef struct _HTNetInfo HTNetInfo;
2.10 timbl 178:
2.14 luotonen 179: /*
2.39 frystyk 180: ** Callback to a protocol module
2.14 luotonen 181: */
2.39 frystyk 182: typedef int (*HTLoadCallBack) PARAMS((HTRequest * req));
2.14 luotonen 183:
2.10 timbl 184: #include "HTAnchor.h"
185: #include <A
186: NAME="z3" HREF="HTFormat.html">"HTFormat.h"</A>
2.15 luotonen 187: #include "HTAAUtil.h" /* HTAAScheme, HTAAFailReason */
2.14 luotonen 188: #include "HTAABrow.h" /* HTAASetup */
2.33 frystyk 189: </PRE>
2.10 timbl 190:
2.39 frystyk 191: <A NAME="Addresses"><H2>Default WWW Addresses</H2></A>
2.10 timbl 192:
2.33 frystyk 193: These control the home page selection. To mess with these for normal browses
2.6 timbl 194: is asking for user confusion.
2.33 frystyk 195: <PRE>
196: #define LOGICAL_DEFAULT "WWW_HOME" /* Defined to be the home page */
1.1 timbl 197:
2.6 timbl 198: #ifndef PERSONAL_DEFAULT
2.33 frystyk 199: #define PERSONAL_DEFAULT "WWW/default.html" /* in home directory */
2.6 timbl 200: #endif
2.33 frystyk 201:
2.6 timbl 202: #ifndef LOCAL_DEFAULT_FILE
1.1 timbl 203: #define LOCAL_DEFAULT_FILE "/usr/local/lib/WWW/default.html"
2.6 timbl 204: #endif
2.33 frystyk 205:
206: /* If one telnets to an access point it will look in this file for home page */
2.7 timbl 207: #ifndef REMOTE_POINTER
2.33 frystyk 208: #define REMOTE_POINTER "/etc/www-remote.url" /* can't be file */
2.7 timbl 209: #endif
2.33 frystyk 210:
2.7 timbl 211: /* and if that fails it will use this. */
2.6 timbl 212: #ifndef REMOTE_ADDRESS
2.33 frystyk 213: #define REMOTE_ADDRESS "http://info.cern.ch/remote.html" /* can't be file */
1.1 timbl 214: #endif
215:
2.33 frystyk 216: /* If run from telnet daemon and no -l specified, use this file: */
1.1 timbl 217: #ifndef DEFAULT_LOGFILE
218: #define DEFAULT_LOGFILE "/usr/adm/www-log/www-log"
219: #endif
220:
2.33 frystyk 221: /* If the home page isn't found, use this file: */
1.1 timbl 222: #ifndef LAST_RESORT
2.6 timbl 223: #define LAST_RESORT "http://info.cern.ch/default.html"
1.1 timbl 224: #endif
225:
2.33 frystyk 226: /* This is the default cache directory: */
2.23 frystyk 227: #ifndef CACHE_HOME_DIR
228: #define CACHE_HOME_DIR "/tmp/"
229: #endif
230:
2.33 frystyk 231: /* The default directory for "save locally" and "save and execute" files: */
2.23 frystyk 232: #ifndef SAVE_LOCALLY_HOME_DIR
233: #define SAVE_LOCALLY_HOME_DIR "/tmp/"
234: #endif
2.33 frystyk 235: </PRE>
2.10 timbl 236:
2.34 frystyk 237: <H2><A NAME="HTNetInfo">Protocol Specific Information</A></H2>
238:
239: This structure contains information about socket number, input buffer for
240: reading from the network etc. The structure is used through out the protocol
241: modules and is the refenrence point for introducing multi threaded execution
2.35 frystyk 242: into the library, see specifications on <A HREF="http://info.cern.ch/hypertext/WWW/Library/User/Multithread/multithread.html">Multiple Threads</A>.
2.34 frystyk 243:
244: <PRE>
2.39 frystyk 245: struct _HTNetInfo {
246: int sockfd; /* Socket descripter */
247: SockA sock_addr; /* SockA is defined in tcp.h */
2.36 frystyk 248: HTInputSocket * isoc; /* Input buffer */
2.39 frystyk 249: HTStream * target; /* Output stream */
250: HTChunk * transmit; /* Line to be send */
2.36 frystyk 251: int addressCount; /* Attempts if multi-homed host */
2.39 frystyk 252: time_t connecttime; /* Used on multihomed hosts */
2.36 frystyk 253: struct _HTRequest * request; /* Link back to request structure */
2.39 frystyk 254: };
2.34 frystyk 255: </PRE>
256:
2.36 frystyk 257: <EM><B>Note:</B> The AddressCount varaible is used to count the number
258: of attempt to connect to a multi-homed host so we know when to stop
259: trying new IP-addresses.</EM>
260:
2.9 timbl 261: <H2><A
262: NAME="z1">The Request structure</A></H2>When a request is handled, all kinds
263: of things about it need to be passed
264: along. These are all put into a
2.31 frystyk 265: HTRequest structure. <P>
266:
2.35 frystyk 267: <B>Note 1:</B> There is also a <A NAME="z4" HREF="HTFormat.html#z17">global list of converters</A> <P>
268: <B>Note 2:</B> If you reuse the request structure for more than one
2.33 frystyk 269: request then make sure that the request is re-initialized, so that no `old'
270: data is reused, see <A HREF="#z100">functions to manipulate HTRequest
271: Structure</A>. The library handles its own internal information from request
2.39 frystyk 272: to request but the information set by the caller is untouched. <P>
2.31 frystyk 273:
2.39 frystyk 274: The elements of the request structure are as follows.
275:
276: <PRE>
277: struct _HTRequest {
278: </PRE>
2.19 timbl 279:
280: <H3>Set by the caller of HTaccess:</H3>
281:
2.39 frystyk 282: <PRE>
283: <A HREF="#Methods">HTMethod</A> method;
284: </PRE>
285:
286: An enum used to specify the HTTP <A NAME="z7"
287: HREF="../../Protocols/HTTP/Methods.html">method</A> used. The default
288: value is <CODE>GET</CODE>
289:
290: <PRE>
291: HTList * conversions;
292: </PRE>
293:
294: NULL, or a list of conversions which the format manager can do in
295: order to fulfill the request. It typically points to a list set up an
296: initialisation time for example by <A HREF="HTInit.html">HTInit().</A>
297:
298: <PRE>
299: HTList * encodings;
300: </PRE>
301:
302: The list of encodings acceptable in the output stream.
303:
304: <PRE>
305: HTList * languages;
306: </PRE>
307:
308: The list of (human) language values acceptable in the response. The default
309: is all languages.
310:
311: <PRE>
312: BOOL (*<A NAME="z9"> callback</A> ) PARAMS((struct _HTRequest* request,
313: void *param));
314: </PRE>
315:
316: A function to be called back in the event that a file has been saved
317: to disk by HTSaveAndCallBack for example.
318:
319: <PRE>
320: void * context;
321: </PRE>
322:
323: An arbitrary pointer passed to HTAccess and passed back as a parameter
324: to the <A NAME="z10" HREF="#z9">callback</A> .
325:
326: <PRE>
327: HTStream* output_stream;
328: </PRE>
329:
330: The output stream to be used to put data down to as they come in from the
331: network. The default value is <CODE>NULL</CODE> which means that the stream
332: goes to the user (display).
333:
334: <PRE>
335: HTAtom * output_format;
336: </PRE>
337:
338: The output format of the stream. This can be used to get unconverted
339: data etc. from the library. If <CODE>NULL</CODE>, then WWW_PRESENT is
340: default value.
341:
342: <PRE>
2.43 frystyk 343: BOOL BlockingIO;
344: </PRE>
345:
346: This flag can be set to override if a protocol module is registered as
347: using non-blocking IO.
348:
349: <PRE>
2.39 frystyk 350: HTParentAnchor *parentAnchor;
351: </PRE>
352:
353: If this parameter is set then a `Referer: <parent address> is
354: generated in the request to the server, see <A
355: HREF="http://info.cern.ch/hypertext/WWW/Protocols/HTTP/HTRQ_Headers.html#z14">
356: Referer field in a HTTP Request</A>
357:
358: <H3>Set by HTAccess</H3>
359:
360: None of the bits below may be looked at by a client application except
361: in the callback routine, when the anchor may be picked out.
362:
363: <PRE>
364: HTParentAnchor* anchor;
365: </PRE>
366:
367: The anchor for the object in question. Set immediately by HTAcesss.
368: Used by the protocol and parsing modules. Valid thoughout the access.
369:
370: <PRE>
371: HTChildAnchor * childAnchor; /* For element within the object */
372: </PRE>
373:
374: The anchor for the sub object if any. The object builder should
375: ensure that htis is selected, highlighted, etc when the object is
376: loaded.
377:
378: <PRE>
379: void * using_cache;
380: </PRE>
381:
382: Pointer to cache element if cache hit
2.19 timbl 383:
2.25 luotonen 384: <H3>Error Diagnostics</H3>
385: <PRE>
2.30 frystyk 386: BOOL error_block; /* YES if stream has been used */
2.29 luotonen 387: HTList * error_stack; /* List of errors */
2.25 luotonen 388:
2.34 frystyk 389: </PRE>
390: <H3>Library Side</H3>
391: <PRE>
392: HTNetInfo * net_info; /* Information about socket etc. */
2.36 frystyk 393: int redirections; /* Number of redirections */
2.25 luotonen 394: </PRE>
2.39 frystyk 395:
396: <H3>Temporary until we get a good MIME parser</H3>
397: <PRE>
398: char * redirect; /* Location or URI */
399: char * WWWAAScheme; /* WWW-Authenticate scheme */
400: char * WWWAARealm; /* WWW-Authenticate realm */
401: char * WWWprotection; /* WWW-Protection-Template */
402: </PRE>
403:
2.21 luotonen 404: <H3>Server Side</H3>
405: <PRE>
406: HTAtom * content_type; /* Content-Type: */
2.18 luotonen 407: HTAtom * content_language;/* Language */
408: HTAtom * content_encoding;/* Encoding */
2.16 luotonen 409: int content_length; /* Content-Length: */
2.21 luotonen 410: HTInputSocket * isoc; /* InputSocket object for reading */
2.14 luotonen 411: char * authorization; /* Authorization: field */
412: HTAAScheme scheme; /* Authentication scheme used */
2.19 timbl 413: </PRE>
2.21 luotonen 414: <H3>Client Side</H3>
2.19 timbl 415: <PRE>
2.14 luotonen 416: HTList * valid_schemes; /* Valid auth.schemes */
417: HTAssocList ** scheme_specifics;/* Scheme-specific parameters */
2.39 frystyk 418: char * authenticate; /* WWW-authenticate: field */
2.14 luotonen 419: char * prot_template; /* WWW-Protection-Template: field */
420: HTAASetup * setup; /* Doc protection info */
421: HTAARealm * realm; /* Password realm */
422: char * dialog_msg; /* Authentication prompt (client) */
2.10 timbl 423: };
2.9 timbl 424:
2.31 frystyk 425: </PRE>
426:
427: <H2><A NAME="z100">Functions to Manipulate a HTRequest Structure</A></H2>
428:
429: Just to make things easier especially for clients, here are some functions to
430: manipulate the request structure:
431:
432: <H3>Create blank request</H3>This request has defaults in -- in
2.9 timbl 433: most cases it will need some information
434: added before being passed to HTAccess,
435: but it will work as is for a simple
436: request.
2.14 luotonen 437: <PRE>
2.40 frystyk 438: extern HTRequest * HTRequest_new NOPARAMS;
2.31 frystyk 439: </PRE>
2.14 luotonen 440:
2.31 frystyk 441: <H3>Delete request structure</H3>Frees also conversion list hanging
2.19 timbl 442: from req->conversions.
2.14 luotonen 443: <PRE>
2.40 frystyk 444: extern void HTRequest_delete PARAMS((HTRequest * req));
2.31 frystyk 445: </PRE>
1.1 timbl 446:
2.31 frystyk 447: <H3>Clear a request structure</H3>
448: 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.
449: <PRE>
450: extern void HTRequest_clear PARAMS((HTRequest * req));
451: </PRE>
2.9 timbl 452:
2.39 frystyk 453: <A NAME="LoadDoc"><H2>Functions for Loading a Document</H2></A>
454:
455: There are several different ways of loading a document. However, the
456: major difference between them is whether the document is referenced by
457:
458: <UL>
459: <LI><A HREF="#Relative">Relative URI</A>
460: <LI><A HREF="#Absolute">Absolute URI</A>
461: <LI><A HREF="#Anchor">Anchor element</A> or
462: <LI>Contains keywords for <A HREF="#RelSearch">searching an relative URI</A>
463: <LI>Contains keywords for <A HREF="#AbsSearch">searching an absolute URI</A>
464: </UL>
465:
466: <B>NOTE:</B> From release 3.0 of the Library, the return codes from
467: the loading functions are no mode <CODE>BOOL</CODE>, that is
468: <CODE>YES</CODE> or <CODE>NO</CODE>. Insted they have been replaced
469: with the following set of return codes defined in the <A
470: HREF="HTUtils.html#ReturnCodes">Utility module</A>:
471:
2.5 timbl 472: <DL>
2.39 frystyk 473: <DT>HT_WOULD_BLOCK
474: <DD>An I/O operation would block
475:
476: <DT>HT_ERROR
477: <DD>Error has occured
478:
479: <DT>HT_LOADED
480: <DD>Success
481:
482: <DT>HT_NO_DATA
483: <DD>Success, but no document loaded. This might be the situation when a
484: telnet sesssion is started etc.
2.5 timbl 485: </DL>
486:
2.39 frystyk 487: However, a general rule about the return codes is that <B>ERRORS</B>
488: have a <EM>negative</EM> value whereas <B>SUCCESS</B> has a
489: <EM>positive</EM> value. <P>
1.1 timbl 490:
2.39 frystyk 491: There are also some functions to help the client getting started with
492: <A HREF="#ClientHelp">the first URI</A>.
1.1 timbl 493:
2.39 frystyk 494: <A NAME="Relative"><H3>Load a document from relative name</H3></A>
1.1 timbl 495:
2.39 frystyk 496: <PRE>
497: extern int HTLoadRelative PARAMS((CONST char * relative_name,
498: HTParentAnchor* here,
499: HTRequest * request));
2.5 timbl 500: </PRE>
2.39 frystyk 501:
502: <A NAME="Absolute"></A><H3>Load a document from absolute name</H3>
1.1 timbl 503:
2.5 timbl 504: <PRE>
2.39 frystyk 505: extern int HTLoadAbsolute PARAMS((CONST char * addr,
506: HTRequest * request));
2.5 timbl 507: </PRE>
2.39 frystyk 508:
509: <H3>Load a document from absolute name to a stream</H3>
510:
2.5 timbl 511: <PRE>
2.39 frystyk 512: extern int HTLoadToStream PARAMS((CONST char * addr,
513: BOOL filter,
514: HTRequest * request));
2.5 timbl 515: </PRE>
1.1 timbl 516:
2.39 frystyk 517: <A NAME="Anchor"><H3>Load if necessary, and select an anchor</H3></A>
1.1 timbl 518:
2.39 frystyk 519: The anchor parameter may be a child anchor. The anchor in the request
520: is set to the parent anchor. The recursive function keeps the error
521: stack in the request structure so that no information is lost having
522: more than one call. See also <A HREF="#BindAnchor">HTBindAnchor()</A>.
1.1 timbl 523:
2.39 frystyk 524: <PRE>
2.41 frystyk 525: extern int HTLoadAnchor PARAMS((HTAnchor * a,
526: HTRequest * request));
2.39 frystyk 527: extern int HTLoadAnchorRecursive PARAMS((HTAnchor * a,
528: HTRequest * request));
2.5 timbl 529: </PRE>
530:
2.39 frystyk 531: <H3>Load a Document</H3>
532:
2.41 frystyk 533: These are two internal routines fro loading a document which has an
534: address AND a matching anchor. (The public routines are called with
535: one OR the other.) This is recursively called from file load module
536: to try ftp (though this will be obsolete in the next major
537: release).<P>
1.1 timbl 538:
2.39 frystyk 539: If <CODE>keep_error_stack</CODE> is YES then the error (or info) stack
540: is not cleared from the previous call.
1.1 timbl 541:
2.39 frystyk 542: <PRE>
2.41 frystyk 543: extern int HTLoad PARAMS((HTRequest * request,
544: BOOL keep_error_stack));
545: </PRE>
546:
547: <PRE>
548: extern BOOL HTLoadTerminate PARAMS((HTRequest * request, int status));
2.5 timbl 549: </PRE>
550:
2.39 frystyk 551: <A NAME="RelSearch"><H3>Search Using Relative URI</H3></A>
552:
553: Performs a search on word given by the user. Adds the search words to
554: the end of the current address and attempts to open the new address.
555:
2.5 timbl 556: <PRE>
2.39 frystyk 557: extern int HTSearch PARAMS((CONST char * keywords,
558: HTParentAnchor* here,
559: HTRequest * request));
2.5 timbl 560: </PRE>
2.39 frystyk 561:
562: <A NAME="AbsSearch"><H3>Search using Absolute URI</H3></A>
563:
564: Performs a keyword search on word given by the user. Adds the keyword
565: to the end of the current address and attempts to open the new
566: address.
2.5 timbl 567:
2.33 frystyk 568: <PRE>
2.40 frystyk 569: extern int HTSearchAbsolute PARAMS((CONST char * keywords,
2.39 frystyk 570: CONST char * indexname,
571: HTRequest * request));
2.5 timbl 572: </PRE>
2.24 luotonen 573:
2.39 frystyk 574:
575: <A NAME="ClientHelp"><H2>Help Function for Clients to get started</H2></A>
576:
577: These function helps the client to load the first document. They are
578: not mandatory to use - but they make life easier!
579:
580: <A NAME="BindAnchor"><H3>Bind an anchor to a request structure without
581: loading</H3></A>
2.24 luotonen 582:
583: <PRE>
2.39 frystyk 584: extern BOOL HTBindAnchor PARAMS((HTAnchor *anchor, HTRequest *request));
2.24 luotonen 585: </PRE>
586:
2.39 frystyk 587: <A NAME="HomePage"><H3>Generate the Anchor for the Home Page</H3></A>
2.24 luotonen 588:
2.39 frystyk 589: As it involves file access, this should only be done once when the
590: program first runs. This is a default algorithm using the
591: <CODE>WWW_HOME</CODE> environment variable.
2.20 frystyk 592:
593: <PRE>
2.40 frystyk 594: extern HTParentAnchor * HTHomeAnchor NOPARAMS;
2.39 frystyk 595: </PRE>
596:
597: <H3>Find Related Name</H3>
598:
599: Creates a local file URI that can be used as a relative name when
600: calling HTParse() to expand a relative file name to an absolute
601: one. <P>
602:
603: The code for this routine originates from the Linemode browser and was
604: moved here by howcome@dxcern.cern.ch in order for all clients to take
605: advantage. <P>
606:
2.20 frystyk 607: <PRE>
2.39 frystyk 608: extern char * HTFindRelatedName NOPARAMS;
609: </PRE>
610:
611: <A NAME="PostDoc"><H2>Functions for Posting a Document</H2></A>
612:
613: This is not quite finished yet but more to come!
2.20 frystyk 614:
2.39 frystyk 615: <H3>Get a Save Stream</H3>
2.20 frystyk 616:
2.39 frystyk 617: <H4>On Entry,</H4>
2.5 timbl 618: <DL>
2.9 timbl 619: <DT>request->anchor
620: <DD> is valid anchor which
621: has previously beeing loaded
2.5 timbl 622: </DL>
623:
2.39 frystyk 624: <H4>On exit,</H4>
2.5 timbl 625: <DL>
626: <DT>returns
2.6 timbl 627: <DD> 0 if error else a stream
628: to save the object to.
2.5 timbl 629: </DL>
630:
631: <PRE>
2.40 frystyk 632: extern HTStream * HTSaveStream PARAMS((HTRequest * request));
2.39 frystyk 633: </PRE>
2.5 timbl 634:
1.1 timbl 635:
2.39 frystyk 636: <A NAME="ProtReg"><H2>Access Method Registration</H2></A>
1.1 timbl 637:
2.39 frystyk 638: An access method is defined by an HTProtocol structure which point to
639: the routines for performing the various logical operations on an
640: object: in HTTP terms, GET, PUT, and POST. The access methods
641: supported in the Library are initiated automaticly using the private
642: function <CODE>HTAccessInit()</CODE> <B>if not</B> defined
643: <CODE>NO_INIT</CODE> <P>
644:
645: Each of these routine takes as a parameter a <A NAME="z2"
646: HREF="#z1">request structure</A> containing details of the request.
647: When the protocol class routine is called, the anchor element in the
648: request is already valid (made valid by HTAccess).
649:
650: <PRE>
651: typedef enum _HTSocBlock {
652: SOC_BLOCK,
2.42 frystyk 653: SOC_NON_BLOCK
2.39 frystyk 654: } HTSocBlock;
655:
656: typedef struct _HTProtocol {
657: char * name;
658: HTSocBlock block;
659: int (*load) PARAMS((HTRequest * request));
660: HTStream* (*saveStream) PARAMS((HTRequest * request));
661: HTStream* (*postStream) PARAMS((HTRequest * request,
662: HTParentAnchor* postTo));
663: } HTProtocol;
1.1 timbl 664:
2.40 frystyk 665: extern BOOL HTRegisterProtocol PARAMS((HTProtocol * protocol));
2.42 frystyk 666: extern void HTDisposeProtocols NOPARAMS;
2.5 timbl 667: </PRE>
1.1 timbl 668:
2.39 frystyk 669: <H3>Uses Protocol Blocking IO</H3>
1.1 timbl 670:
2.39 frystyk 671: A small function to make life easier. Returns <CODE>YES</CODE> or
2.42 frystyk 672: <CODE>NO</CODE>. If the Library is run in NON-INTERACTIVE MODE then
673: the function always returns YES;
2.38 howcome 674:
675: <PRE>
2.40 frystyk 676: extern BOOL HTProtocolBlocking PARAMS((HTRequest * request));
2.38 howcome 677: </PRE>
678:
2.39 frystyk 679: end
2.25 luotonen 680:
681: <PRE>
1.1 timbl 682: #endif /* HTACCESS_H */
2.25 luotonen 683: </PRE>
684: end of HTAccess
685: </BODY>
2.9 timbl 686: </HTML>
Webmaster