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