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