Annotation of libwww/Library/src/HTAccess.html, revision 2.45.2.2
2.9 timbl 1: <HTML>
2: <HEAD>
2.45 frystyk 3: <TITLE>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: This module is implemented by <A HREF="HTAccess.c">HTAccess.c</A>, and
23: it is a part of the <A NAME="z10"
2.45.2.2! frystyk 24: HREF="http://www.w3.org/hypertext/WWW/Library/User/Guide/Guide.html">Library
2.39 frystyk 25: of Common Code</A>. <P>
26:
27: The module contains a lot of stuff but the main topics are:
28:
29: <UL>
2.41 frystyk 30: <LI><A HREF="#Library">Initializing and Terminating the Library</A>
2.45.2.2! frystyk 31: <LI><A HREF="#log">Logging of requests</A>
2.39 frystyk 32: <LI><A HREF="#Methods">Management of access methods</A>
33: <LI><A HREF="#Addresses">A lot of hard coded addresses</A>
34: <LI><A HREF="#z1">The HTRequest structure</A>
35: <LI><A HREF="#z100">Management of the HTRequest structure</A>
36: <LI><A HREF="#LoadDoc">Functions for loading a document</A>
37: <LI><A HREF="#ClientHelp">Help functions for clients to get started</A>
38: <LI><A HREF="#PostDoc">Functions for posting a document</A>
39: <LI><A HREF="#ProtReg">Access Method Registration</H2></A>
40: </UL>
41:
2.33 frystyk 42:
43: <PRE>
44: #ifndef HTACCESS_H
1.1 timbl 45: #define HTACCESS_H
2.44 roeber 46:
2.16 luotonen 47: #include "HTList.h"
2.39 frystyk 48: #include "HTChunk.h"
2.35 frystyk 49: </PRE>
1.1 timbl 50:
2.45.2.2! frystyk 51: <H2>Global Flags</H2>
! 52:
! 53: Flags and variables which may be set to control the Library
! 54:
! 55: <H3>Redirections</H3>
! 56:
! 57: The maximum number of redirections is pr. default 10. This prevents
! 58: the library from going into an infinite loop which is kind of nice :-)
! 59:
2.35 frystyk 60: <PRE>
2.45.2.2! frystyk 61: extern int HTMaxRedirections;
2.33 frystyk 62: </PRE>
1.1 timbl 63:
2.45.2.2! frystyk 64: <H3>Other Flags</H3>
2.36 frystyk 65:
66: <PRE>
67: extern char * HTClientHost; /* Name or number of telnetting host */
68: extern BOOL HTSecure; /* Disable security holes? */
2.45.2.2! frystyk 69:
2.36 frystyk 70: extern char * HTImServer; /* If I'm cern_httpd */
71: extern BOOL HTImProxy; /* If I'm cern_httpd as a proxy */
72: </PRE>
73:
2.41 frystyk 74: <A NAME="Library"><H2>Initializing and Terminating the Library</H2></A>
75:
2.45.2.2! frystyk 76: <IMG SRC="http://www.w3.org/hypertext/WWW/Icons/32x32/warning.gif">
2.41 frystyk 77: These two functions initiates memory and settings for the Library and
78: cleans up memory kept by the Library when about to exit the
79: application. It is highly recommended that they are used!
80:
81: <PRE>
82: extern BOOL HTLibInit NOPARAMS;
83: extern BOOL HTLibTerminate NOPARAMS;
84: </PRE>
85:
2.39 frystyk 86: <A NAME="Methods"><H2>Method Management</H2></A>
2.33 frystyk 87:
2.41 frystyk 88: These are the valid methods, see <A
2.45.2.2! frystyk 89: HREF="http://www.w3.org/hypertext/WWW/Protocols/HTTP/Methods.html">HTTP
! 90: Methods</A>. <P>
! 91:
! 92: <B>NOTE:</B> the anchor list of allowed methods are not a bitflag, not
! 93: at list.
2.33 frystyk 94:
95: <PRE>
2.16 luotonen 96: typedef enum {
2.45.2.2! frystyk 97: METHOD_INVALID = 0x0,
! 98: METHOD_GET = 0x1,
! 99: METHOD_HEAD = 0x2,
! 100: METHOD_POST = 0x4,
! 101: METHOD_PUT = 0x8,
! 102: METHOD_DELETE = 0x10,
! 103: METHOD_LINK = 0x20,
! 104: METHOD_UNLINK = 0x40
2.16 luotonen 105: } HTMethod;
2.33 frystyk 106: </PRE>
107:
108: <H3>Get Method Enumeration</H3>
2.16 luotonen 109:
2.33 frystyk 110: Gives the enumeration value of the method as a function of the (char *) name.
2.16 luotonen 111:
2.33 frystyk 112: <PRE>
2.45.2.2! frystyk 113: extern HTMethod HTMethod_enum PARAMS((CONST char * name));
2.16 luotonen 114: </PRE>
115:
2.33 frystyk 116: <H3>Get Method String</H3>
2.16 luotonen 117:
2.33 frystyk 118: The reverse of <I>HTMethod_enum()</I>
2.16 luotonen 119:
2.33 frystyk 120: <PRE>
2.45.2.2! frystyk 121: extern CONST char * HTMethod_name PARAMS((HTMethod method));
2.16 luotonen 122: </PRE>
2.33 frystyk 123:
2.35 frystyk 124: <HR>
125: <EM>This section might be move to the Access Authentication Module</EM>
126:
2.36 frystyk 127: <H4>Match Template Against Filename</H4>
2.16 luotonen 128: <PRE>
2.40 frystyk 129: /* extern HTAA_templateMatch()
2.16 luotonen 130: ** STRING COMPARISON FUNCTION FOR FILE NAMES
131: ** WITH ONE WILDCARD * IN THE TEMPLATE
132: ** NOTE:
133: ** This is essentially the same code as in HTRules.c, but it
134: ** cannot be used because it is embedded in between other code.
135: ** (In fact, HTRules.c should use this routine, but then this
136: ** routine would have to be more sophisticated... why is life
137: ** sometimes so hard...)
138: **
139: ** ON ENTRY:
2.37 frystyk 140: ** tmplate is a template string to match the file name
2.16 luotonen 141: ** agaist, may contain a single wildcard
142: ** character * which matches zero or more
143: ** arbitrary characters.
144: ** filename is the filename (or pathname) to be matched
145: ** agaist the template.
146: **
147: ** ON EXIT:
148: ** returns YES, if filename matches the template.
149: ** NO, otherwise.
150: */
2.40 frystyk 151: extern BOOL HTAA_templateMatch PARAMS((CONST char * tmplate,
2.16 luotonen 152: CONST char * filename));
2.35 frystyk 153: </PRE>
154: <HR>
2.16 luotonen 155:
2.45.2.2! frystyk 156: The following have to be defined in advance of the other include files
2.10 timbl 157: because of circular references.
2.45.2.2! frystyk 158:
2.33 frystyk 159: <PRE>
160: typedef struct _HTRequest HTRequest;
2.39 frystyk 161: typedef struct _HTNetInfo HTNetInfo;
2.10 timbl 162:
2.14 luotonen 163: /*
2.39 frystyk 164: ** Callback to a protocol module
2.14 luotonen 165: */
2.39 frystyk 166: typedef int (*HTLoadCallBack) PARAMS((HTRequest * req));
2.14 luotonen 167:
2.10 timbl 168: #include "HTAnchor.h"
169: #include <A
170: NAME="z3" HREF="HTFormat.html">"HTFormat.h"</A>
2.15 luotonen 171: #include "HTAAUtil.h" /* HTAAScheme, HTAAFailReason */
2.14 luotonen 172: #include "HTAABrow.h" /* HTAASetup */
2.33 frystyk 173: </PRE>
2.10 timbl 174:
2.45.2.2! frystyk 175: <A NAME="HeaderMask"><H2>General HTTP Header Mask</H2></A>
! 176:
! 177: This mask enables and disables which automaticly generated HTTP
! 178: headers are to be sent in a request. If the bit is not turned on they
! 179: are not sent. Extra header can be generated when initializing the <A
! 180: HREF="#ExtraHeaders">ExtraHeaders field</A>. The first set is general
! 181: headers and the second is request headers.
! 182:
! 183: <PRE>
! 184: typedef enum _HeaderEnum {
! 185: HT_DATE = 0x1,
! 186: HT_MESSAGE_ID = 0x2,
! 187: HT_MIME = 0x4, /* MIME-Version */
! 188:
! 189: HT_ACCEPT = 0x8,
! 190: HT_FROM = 0x10,
! 191: HT_PRAGMA = 0x20,
! 192: HT_REFERER = 0x40,
! 193: HT_USER_AGENT = 0x80
! 194: } HeaderEnum;
! 195:
! 196: #define <A NAME="DEF_HEAD">DEFAULT_HEADERS</A> HT_ACCEPT+HT_REFERER+HT_USER_AGENT
! 197: </PRE>
! 198:
! 199: <H2>Entity Header Mask</H2>
! 200:
! 201: The entity headers contain information about the object sent in the
! 202: HTTP transaction. See the <A HREF="HTAnchor.html">Anchor module</A>,
! 203: for the storage of entity headers. This flag defines which headers are
! 204: to be sent in a request together with an entity body (the <B>O</B>
! 205: stands for <EM>object</EM>)
! 206:
! 207: <PRE>
! 208: typedef enum _EntityHeaderEnum {
! 209: HT_ALLOW = 0x1,
! 210: HT_CONTENT_ENCODING = 0x2,
! 211: HT_CONTENT_LANGUAGE = 0x4,
! 212: HT_CONTENT_LENGTH = 0x8,
! 213: HT_CTE = 0x10, /* Content-Transfer-Encoding */
! 214: HT_CONTENT_TYPE = 0x20,
! 215: HT_DERIVED_FROM = 0x40,
! 216: HT_EXPIRES = 0x80,
! 217: HT_LAST_MODIFIED = 0x200,
! 218: HT_LINK = 0x400,
! 219: HT_TITLE = 0x800,
! 220: HT_URI = 0x1000,
! 221: HT_VERSION = 0x2000
! 222: } EntityHeaderEnum;
! 223:
! 224: #define <A NAME="DEF_ENTITY">DEFAULT_ENTITY_HEADERS</A> HT_CONTENT_TYPE+HT_CONTENT_LENGTH \
! 225: +HT_DERIVED_FROM+HT_VERSION
! 226: </PRE>
! 227:
2.39 frystyk 228: <A NAME="Addresses"><H2>Default WWW Addresses</H2></A>
2.10 timbl 229:
2.33 frystyk 230: These control the home page selection. To mess with these for normal browses
2.6 timbl 231: is asking for user confusion.
2.33 frystyk 232: <PRE>
233: #define LOGICAL_DEFAULT "WWW_HOME" /* Defined to be the home page */
1.1 timbl 234:
2.6 timbl 235: #ifndef PERSONAL_DEFAULT
2.33 frystyk 236: #define PERSONAL_DEFAULT "WWW/default.html" /* in home directory */
2.6 timbl 237: #endif
2.33 frystyk 238:
2.45.2.2! frystyk 239: /* If the home page isn't found, use this file: */
! 240: #ifndef LAST_RESORT
! 241: #define LAST_RESORT "http://www.w3.org/"
2.6 timbl 242: #endif
2.33 frystyk 243:
244: /* If one telnets to an access point it will look in this file for home page */
2.7 timbl 245: #ifndef REMOTE_POINTER
2.33 frystyk 246: #define REMOTE_POINTER "/etc/www-remote.url" /* can't be file */
2.7 timbl 247: #endif
2.33 frystyk 248:
2.7 timbl 249: /* and if that fails it will use this. */
2.6 timbl 250: #ifndef REMOTE_ADDRESS
2.45.2.2! frystyk 251: #define REMOTE_ADDRESS "http://www.w3.org/remote.html" /* can't be file */
1.1 timbl 252: #endif
253:
2.45.2.2! frystyk 254: /* Default log file name */
1.1 timbl 255: #ifndef DEFAULT_LOGFILE
2.45.2.2! frystyk 256: #define DEFAULT_LOGFILE "www-log"
1.1 timbl 257: #endif
258:
2.45.2.2! frystyk 259: #ifndef LOCAL_DEFAULT_FILE
! 260: #define LOCAL_DEFAULT_FILE "/usr/local/lib/WWW/default.html"
1.1 timbl 261: #endif
262:
2.33 frystyk 263: /* This is the default cache directory: */
2.45.2.2! frystyk 264: #ifndef HT_CACHE_ROOT
! 265: #define HT_CACHE_ROOT "/tmp"
2.23 frystyk 266: #endif
267:
2.33 frystyk 268: /* The default directory for "save locally" and "save and execute" files: */
2.45.2.2! frystyk 269: #ifndef HT_TMP_ROOT
! 270: #define HT_TMP_ROOT "/tmp"
2.23 frystyk 271: #endif
2.33 frystyk 272: </PRE>
2.10 timbl 273:
2.34 frystyk 274: <H2><A NAME="HTNetInfo">Protocol Specific Information</A></H2>
275:
2.45 frystyk 276: This structure contains information about socket number, input buffer
277: for reading from the network etc. The structure is used through out
278: the protocol modules and is the refenrence point for introducing multi
279: threaded execution into the library, see specifications on <A
2.45.2.2! frystyk 280: HREF="http://www.w3.org/hypertext/WWW/Library/User/Features/multithread.html">Multiple
2.45 frystyk 281: Threads</A>.
2.34 frystyk 282:
283: <PRE>
2.45.2.2! frystyk 284: typedef enum _SocAction {
! 285: SOC_INVALID = -1,
! 286: SOC_WRITE = 0, /* By default ready to write */
! 287: SOC_READ,
! 288: SOC_INTERRUPT
! 289: } SocAction;
! 290:
2.39 frystyk 291: struct _HTNetInfo {
2.45 frystyk 292: SOCKFD sockfd; /* Socket descripter */
2.39 frystyk 293: SockA sock_addr; /* SockA is defined in tcp.h */
2.36 frystyk 294: HTInputSocket * isoc; /* Input buffer */
2.45.2.2! frystyk 295: SocAction action; /* Result of the select call */
! 296: HTStream * target; /* Target stream */
2.36 frystyk 297: int addressCount; /* Attempts if multi-homed host */
2.39 frystyk 298: time_t connecttime; /* Used on multihomed hosts */
2.36 frystyk 299: struct _HTRequest * request; /* Link back to request structure */
2.39 frystyk 300: };
2.34 frystyk 301: </PRE>
302:
2.36 frystyk 303: <EM><B>Note:</B> The AddressCount varaible is used to count the number
304: of attempt to connect to a multi-homed host so we know when to stop
305: trying new IP-addresses.</EM>
306:
2.45.2.2! frystyk 307: <H2><A NAME="z1">The Request structure</A></H2>
! 308:
! 309: When a request is handled, all kinds of things about it need to be
! 310: passed along. These are all put into a HTRequest structure. This is
! 311: the most essential structure in the library. It contains two main
! 312: categories of information regarding a request:
2.31 frystyk 313:
2.45.2.2! frystyk 314: <UL>
! 315: <LI>Application dependent information
! 316: <LI>Library dependent information
! 317: </UL>
! 318:
! 319: Applications using the Library should <EM>never</EM> use the internal
! 320: library dependent information. It's only because we dont have real
! 321: classes that we can't hide it. <P>
! 322:
! 323: <B>Note:</B> If you reuse the request structure for more than one
! 324: request then make sure that the request is re-initialized, so that no
! 325: `old' data is reused, see <A HREF="#z100">functions to manipulate
! 326: HTRequest Structure</A>. The library handles its own internal
! 327: information from request to request but the information set by the
! 328: caller is untouched. <P>
! 329:
! 330: The elements of the request structure are as follows:
2.39 frystyk 331:
332: <PRE>
333: struct _HTRequest {
334: </PRE>
2.19 timbl 335:
2.45.2.2! frystyk 336: <H3>Application Dependent - Set by the caller of HTAccess</H3>
2.19 timbl 337:
2.39 frystyk 338: <PRE>
339: <A HREF="#Methods">HTMethod</A> method;
340: </PRE>
341:
342: An enum used to specify the HTTP <A NAME="z7"
2.45.2.2! frystyk 343: HREF="../../Protocols/HTTP/Methods.html">method</A> used for the
! 344: actual request. The default value is <A
! 345: HREF="#Methods"><CODE>GET</CODE></A>.
! 346:
! 347: <H4>HTTP Header Information</H4>
2.39 frystyk 348:
349: <PRE>
350: HTList * conversions;
351: </PRE>
352:
2.45.2.2! frystyk 353: NULL, or a <EM>local</EM> list of specific conversions which the
! 354: format manager can do in order to fulfill the request. It typically
! 355: points to a list set up on initialisation time for example by <A
! 356: HREF="HTInit.html">HTInit()</A>. There is also a <A
! 357: HREF="HTFormat.html#z17"><EM>global</EM></A> list of conversions which
! 358: contains a generic set of possible conversions.
2.39 frystyk 359:
360: <PRE>
361: HTList * encodings;
362: </PRE>
363:
364: The list of encodings acceptable in the output stream.
365:
366: <PRE>
367: HTList * languages;
368: </PRE>
369:
370: The list of (human) language values acceptable in the response. The default
371: is all languages.
372:
373: <PRE>
2.45.2.2! frystyk 374: HeaderEnum HeaderMask;
! 375: EntityHeaderEnum EntityMask;
2.39 frystyk 376: </PRE>
377:
2.45.2.2! frystyk 378: These two masks defines which headers to include in a HTTP request (or
! 379: any other MIME-like protocol). the first mask defines what
! 380: autogenerated HTTP header fields should be sent in the HTTP
! 381: request. The default value is <A
! 382: HREF="DEF_HEAD">DEFAULT_HEADERS</A>. The second defines what entity
! 383: headers should be sent along with an entity (using PUT or POST).
2.39 frystyk 384:
385: <PRE>
2.45.2.2! frystyk 386: HTParentAnchor *parentAnchor;
2.39 frystyk 387: </PRE>
388:
2.45.2.2! frystyk 389: If this parameter is set then a `Referer: <parent address> can
! 390: be generated in the request to the server, see <A
! 391: HREF="http://www.w3.org/hypertext/WWW/Protocols/HTTP/HTRQ_Headers.html#z14">
! 392: Referer field in a HTTP Request</A>
2.39 frystyk 393:
394: <PRE>
2.45.2.2! frystyk 395: <A NAME="#ExtraHeaders">char * ExtraHeaders;</A>
2.39 frystyk 396: </PRE>
397:
2.45.2.2! frystyk 398: Extra header information can be send along with a request using this
! 399: variable. The text is sent as is so it must be preformatted with
! 400: <CRLF> line terminators.
! 401:
! 402: <H4>Streams From Network to Application</H4>
2.45 frystyk 403:
404: <PRE>
2.45.2.2! frystyk 405: HTStream * output_stream;
! 406: </PRE>
! 407:
! 408: The output stream is to be used to put data down to as they come in
! 409: <B>from</B> the network and back to the application. The default value
! 410: is <CODE>NULL</CODE> which means that the stream goes to the user
! 411: (display).
! 412:
! 413: <PRE>
! 414: HTAtom * output_format;
! 415: </PRE>
! 416:
! 417: The desired format of the output stream. This can be used to get
! 418: unconverted data etc. from the library. If <CODE>NULL</CODE>, then <A
! 419: HREF="HTFormat.html#FormatTypes">WWW_PRESENT</A> is default value.
! 420:
! 421: <PRE>
! 422: HTStream* error_stream;
2.45 frystyk 423: </PRE>
424:
425: All object bodies sent from the server with status codes different
426: from <CODE>200 OK</CODE> will be put down this stream. This can be
427: used as a debug window etc. If the value is NULL (default) then the
428: stream used is <A HREF="HTFormat.html#BlackHole">HTBlackHole</A>.
2.39 frystyk 429:
430: <PRE>
2.45.2.2! frystyk 431: HTAtom * error_format;
! 432: </PRE>
! 433:
! 434: The desired format of the error stream. This can be used to get
! 435: unconverted data etc. from the library. The default value if
! 436: <CODE>WWW_HTML</CODE> as a character based only has one WWW_PRESENT.
! 437:
! 438: <H4>Streams From Application to Network</H4>
! 439:
! 440: <PRE>
! 441: HTStream * input_stream;
2.39 frystyk 442: </PRE>
443:
2.45.2.2! frystyk 444: The input stream is to be used by the <CODE>PostCallBack</CODE>
! 445: function to put data out on the network. The user should not
! 446: initialize this field.
! 447:
! 448: <PRE>
! 449: HTAtom * input_format;
! 450: </PRE>
! 451:
! 452: The desired format of the output stream. This can be used to upload
! 453: converted data to a remote server. If <CODE>NULL</CODE>, then <A
! 454: HREF="HTFormat.html#FormatTypes">WWW_SOURCE</A> is default value.
! 455:
! 456: <PRE>
! 457: int (*PostCallBack) PARAMS((struct _HTRequest * request,
! 458: HTStream * target));
! 459: </PRE>
! 460:
! 461: The call back function which is called when the current request is
! 462: ready for sending (posting) the data object. The request is the
! 463: current request so that the application knows which post we are
! 464: handling. The function must have the same return values as the other
! 465: <A HREF="#LoadDoc">Load functions</A>.
! 466:
! 467: <H4>Other Flags</H4>
2.39 frystyk 468:
469: <PRE>
2.43 frystyk 470: BOOL BlockingIO;
2.45.2.2! frystyk 471: BOOL ForceReload;
2.43 frystyk 472: </PRE>
473:
474: This flag can be set to override if a protocol module is registered as
475: using non-blocking IO.
476:
477: <PRE>
2.45.2.2! frystyk 478: BOOL (*<A NAME="z9"> callback</A> ) PARAMS((struct _HTRequest* request,
! 479: void *param));
2.39 frystyk 480: </PRE>
481:
2.45.2.2! frystyk 482: A function to be called back in the event that a file has been saved
! 483: to disk by HTSaveAndCallBack for example.
2.39 frystyk 484:
2.45.2.2! frystyk 485: <PRE>
! 486: void * context;
! 487: </PRE>
2.39 frystyk 488:
2.45.2.2! frystyk 489: An arbitrary pointer passed to HTAccess and passed back as a parameter
! 490: to the <A NAME="z10" HREF="#z9">callback</A>.
! 491:
! 492: <H3>Library Dependent - Set by Library</H3>
! 493:
! 494: None of the bits below may be looked at by a WWW application. The
! 495: Library handles the cleanup by itself.
2.39 frystyk 496:
497: <PRE>
498: HTParentAnchor* anchor;
499: </PRE>
500:
501: The anchor for the object in question. Set immediately by HTAcesss.
502: Used by the protocol and parsing modules. Valid thoughout the access.
503:
504: <PRE>
505: HTChildAnchor * childAnchor; /* For element within the object */
506: </PRE>
507:
508: The anchor for the sub object if any. The object builder should
2.45.2.2! frystyk 509: ensure that is is selected, highlighted, etc when the object is
2.39 frystyk 510: loaded.
511:
512: <PRE>
2.45.2.2! frystyk 513: struct _HTRequest * CopyRequest;
! 514: </PRE>
! 515:
! 516: We need to know if we have a remote request sending data along with
! 517: this request.
! 518:
! 519: <PRE>
! 520: void * using_cache;
! 521: BOOL using_proxy;
2.39 frystyk 522: </PRE>
523:
2.45.2.2! frystyk 524: Pointer to cache element if cache hit anfd if using proxy
2.19 timbl 525:
2.25 luotonen 526: <PRE>
2.45.2.2! frystyk 527: BOOL error_block; /* YES if stream has been used */
! 528: HTList * error_stack; /* List of errors */
! 529: </PRE>
2.25 luotonen 530:
2.45.2.2! frystyk 531: These two fields are used by the error reporting system to keep a
! 532: stack of messages.
! 533:
! 534: <PRE>
! 535: HTNetInfo * net_info; /* Information about socket etc. */
! 536: int redirections; /* Number of redirections */
! 537: time_t retry_after; /* Absolut time for a retry */
2.34 frystyk 538: </PRE>
2.45.2.2! frystyk 539:
! 540: Protocol specific information, socket number etc.
! 541:
2.34 frystyk 542: <PRE>
2.45.2.2! frystyk 543: char * redirect; /* Location or URI */
! 544: char * WWWAAScheme; /* WWW-Authenticate scheme */
! 545: char * WWWAARealm; /* WWW-Authenticate realm */
! 546: char * WWWprotection; /* WWW-Protection-Template */
2.25 luotonen 547: </PRE>
2.39 frystyk 548:
2.45.2.2! frystyk 549: Information taken from the MIME header specifically oriented towards
! 550: the request (not the object itself)
! 551:
2.39 frystyk 552: <PRE>
2.45.2.2! frystyk 553: char * authorization; /* Authorization: field */
! 554: HTAAScheme scheme; /* Authentication scheme used */
! 555: HTInputSocket * isoc; /* InputSocket object for reading */
! 556: HTAtom * content_type; /* Content-Type: */
! 557: HTAtom * content_language; /* Language */
! 558: HTAtom * content_encoding; /* Encoding */
! 559: int content_length; /* Content-Length: */
2.39 frystyk 560: </PRE>
561:
2.45.2.2! frystyk 562: These header fields are only used by the server and will be removed at some
! 563: point.
! 564:
2.21 luotonen 565: <PRE>
2.45.2.2! frystyk 566: HTList * valid_schemes; /* Valid auth.schemes */
! 567: HTAssocList ** scheme_specifics;/* Scheme-specific parameters */
! 568: char * authenticate; /* WWW-authenticate: field */
! 569: char * prot_template; /* WWW-Protection-Template: field */
! 570: HTAASetup * setup; /* Doc protection info */
! 571: HTAARealm * realm; /* Password realm */
! 572: char * dialog_msg; /* Authentication prompt (client) */
2.19 timbl 573: </PRE>
2.45.2.2! frystyk 574:
! 575: <H3>Windows Specific Information</H3>
! 576:
2.19 timbl 577: <PRE>
2.45.2.1 cbrooks 578: #ifdef _WINDOWS
579: HWND hwnd; /* Windows handle for MSWindows */
580: unsigned long winMsg; /* msg number of Windows eloop */
581: #endif /* _WINDOWS */
2.45.2.2! frystyk 582: </PRE>
2.9 timbl 583:
2.45.2.2! frystyk 584: These fields are used by the HTTP access authentication used by a
! 585: client application.
! 586:
! 587: <PRE>
! 588: };
2.31 frystyk 589: </PRE>
590:
591: <H2><A NAME="z100">Functions to Manipulate a HTRequest Structure</A></H2>
592:
593: Just to make things easier especially for clients, here are some functions to
594: manipulate the request structure:
595:
596: <H3>Create blank request</H3>This request has defaults in -- in
2.9 timbl 597: most cases it will need some information
598: added before being passed to HTAccess,
599: but it will work as is for a simple
600: request.
2.14 luotonen 601: <PRE>
2.40 frystyk 602: extern HTRequest * HTRequest_new NOPARAMS;
2.31 frystyk 603: </PRE>
2.14 luotonen 604:
2.31 frystyk 605: <H3>Delete request structure</H3>Frees also conversion list hanging
2.19 timbl 606: from req->conversions.
2.14 luotonen 607: <PRE>
2.40 frystyk 608: extern void HTRequest_delete PARAMS((HTRequest * req));
2.31 frystyk 609: </PRE>
1.1 timbl 610:
2.31 frystyk 611: <H3>Clear a request structure</H3>
2.45.2.2! frystyk 612:
! 613: Clears a request structure so that it can be reused. The only thing
! 614: that differs from using free/new is that the list of conversions is
! 615: kept. <P>
! 616:
! 617: <B>NOTE:</B> It is <B>NOT</B> recommended to reuse a request structure!!!
! 618:
2.31 frystyk 619: <PRE>
620: extern void HTRequest_clear PARAMS((HTRequest * req));
621: </PRE>
2.9 timbl 622:
2.39 frystyk 623: <A NAME="LoadDoc"><H2>Functions for Loading a Document</H2></A>
624:
625: There are several different ways of loading a document. However, the
626: major difference between them is whether the document is referenced by
627:
628: <UL>
629: <LI><A HREF="#Relative">Relative URI</A>
630: <LI><A HREF="#Absolute">Absolute URI</A>
631: <LI><A HREF="#Anchor">Anchor element</A> or
632: <LI>Contains keywords for <A HREF="#RelSearch">searching an relative URI</A>
633: <LI>Contains keywords for <A HREF="#AbsSearch">searching an absolute URI</A>
634: </UL>
635:
636: <B>NOTE:</B> From release 3.0 of the Library, the return codes from
637: the loading functions are no mode <CODE>BOOL</CODE>, that is
638: <CODE>YES</CODE> or <CODE>NO</CODE>. Insted they have been replaced
639: with the following set of return codes defined in the <A
640: HREF="HTUtils.html#ReturnCodes">Utility module</A>:
641:
2.5 timbl 642: <DL>
2.39 frystyk 643: <DT>HT_WOULD_BLOCK
644: <DD>An I/O operation would block
645:
646: <DT>HT_ERROR
647: <DD>Error has occured
648:
649: <DT>HT_LOADED
650: <DD>Success
651:
652: <DT>HT_NO_DATA
653: <DD>Success, but no document loaded. This might be the situation when a
654: telnet sesssion is started etc.
2.45.2.2! frystyk 655:
! 656: <DT>HT_RETRY
! 657: <DD>The remote server is down but will serve documents from the
! 658: calendar time indicated in HTRequest->retry_after.
! 659:
2.5 timbl 660: </DL>
661:
2.39 frystyk 662: However, a general rule about the return codes is that <B>ERRORS</B>
663: have a <EM>negative</EM> value whereas <B>SUCCESS</B> has a
664: <EM>positive</EM> value. <P>
1.1 timbl 665:
2.39 frystyk 666: There are also some functions to help the client getting started with
667: <A HREF="#ClientHelp">the first URI</A>.
1.1 timbl 668:
2.45.2.2! frystyk 669: <A NAME="Relative"><H3>Load a document from relative URL</H3></A>
1.1 timbl 670:
2.39 frystyk 671: <PRE>
672: extern int HTLoadRelative PARAMS((CONST char * relative_name,
673: HTParentAnchor* here,
674: HTRequest * request));
2.5 timbl 675: </PRE>
2.39 frystyk 676:
2.45.2.2! frystyk 677: <A NAME="Absolute"></A><H3>Load a document from absolute URL</H3>
1.1 timbl 678:
2.5 timbl 679: <PRE>
2.39 frystyk 680: extern int HTLoadAbsolute PARAMS((CONST char * addr,
681: HTRequest * request));
2.5 timbl 682: </PRE>
2.39 frystyk 683:
684: <H3>Load a document from absolute name to a stream</H3>
685:
2.5 timbl 686: <PRE>
2.39 frystyk 687: extern int HTLoadToStream PARAMS((CONST char * addr,
688: BOOL filter,
689: HTRequest * request));
2.5 timbl 690: </PRE>
1.1 timbl 691:
2.45.2.2! frystyk 692: <A NAME="Anchor"><H3>Load a document from anchor</H3></A>
1.1 timbl 693:
2.39 frystyk 694: The anchor parameter may be a child anchor. The anchor in the request
695: is set to the parent anchor. The recursive function keeps the error
696: stack in the request structure so that no information is lost having
697: more than one call. See also <A HREF="#BindAnchor">HTBindAnchor()</A>.
1.1 timbl 698:
2.39 frystyk 699: <PRE>
2.41 frystyk 700: extern int HTLoadAnchor PARAMS((HTAnchor * a,
701: HTRequest * request));
2.39 frystyk 702: extern int HTLoadAnchorRecursive PARAMS((HTAnchor * a,
703: HTRequest * request));
2.5 timbl 704: </PRE>
705:
2.39 frystyk 706: <H3>Load a Document</H3>
707:
2.45.2.2! frystyk 708: These are two internal routines for loading a document which has an
2.41 frystyk 709: address AND a matching anchor. (The public routines are called with
710: one OR the other.) This is recursively called from file load module
711: to try ftp (though this will be obsolete in the next major
712: release).<P>
1.1 timbl 713:
2.39 frystyk 714: If <CODE>keep_error_stack</CODE> is YES then the error (or info) stack
715: is not cleared from the previous call.
1.1 timbl 716:
2.39 frystyk 717: <PRE>
2.41 frystyk 718: extern int HTLoad PARAMS((HTRequest * request,
719: BOOL keep_error_stack));
720: </PRE>
721:
722: <PRE>
723: extern BOOL HTLoadTerminate PARAMS((HTRequest * request, int status));
2.5 timbl 724: </PRE>
725:
2.45.2.2! frystyk 726: <A NAME="RelSearch"><H3>Search Using Relative URL</H3></A>
2.39 frystyk 727:
728: Performs a search on word given by the user. Adds the search words to
729: the end of the current address and attempts to open the new address.
730:
2.5 timbl 731: <PRE>
2.39 frystyk 732: extern int HTSearch PARAMS((CONST char * keywords,
733: HTParentAnchor* here,
734: HTRequest * request));
2.5 timbl 735: </PRE>
2.39 frystyk 736:
2.45.2.2! frystyk 737: <A NAME="AbsSearch"><H3>Search using Absolute URL</H3></A>
2.39 frystyk 738:
739: Performs a keyword search on word given by the user. Adds the keyword
740: to the end of the current address and attempts to open the new
741: address.
2.5 timbl 742:
2.33 frystyk 743: <PRE>
2.40 frystyk 744: extern int HTSearchAbsolute PARAMS((CONST char * keywords,
2.39 frystyk 745: CONST char * indexname,
746: HTRequest * request));
2.5 timbl 747: </PRE>
2.24 luotonen 748:
2.39 frystyk 749:
750: <A NAME="ClientHelp"><H2>Help Function for Clients to get started</H2></A>
751:
752: These function helps the client to load the first document. They are
753: not mandatory to use - but they make life easier!
754:
755: <A NAME="BindAnchor"><H3>Bind an anchor to a request structure without
756: loading</H3></A>
2.24 luotonen 757:
758: <PRE>
2.39 frystyk 759: extern BOOL HTBindAnchor PARAMS((HTAnchor *anchor, HTRequest *request));
2.24 luotonen 760: </PRE>
761:
2.39 frystyk 762: <A NAME="HomePage"><H3>Generate the Anchor for the Home Page</H3></A>
2.24 luotonen 763:
2.39 frystyk 764: As it involves file access, this should only be done once when the
765: program first runs. This is a default algorithm using the
766: <CODE>WWW_HOME</CODE> environment variable.
2.20 frystyk 767:
768: <PRE>
2.40 frystyk 769: extern HTParentAnchor * HTHomeAnchor NOPARAMS;
2.39 frystyk 770: </PRE>
771:
772: <H3>Find Related Name</H3>
773:
774: Creates a local file URI that can be used as a relative name when
775: calling HTParse() to expand a relative file name to an absolute
776: one. <P>
777:
2.45.2.2! frystyk 778: The code for this routine originates from the Line Mode Browser and
! 779: was moved here by <EM>howcome@dxcern.cern.ch</EM> in order for all
! 780: clients to take advantage.<P>
2.39 frystyk 781:
2.20 frystyk 782: <PRE>
2.39 frystyk 783: extern char * HTFindRelatedName NOPARAMS;
784: </PRE>
785:
786: <A NAME="PostDoc"><H2>Functions for Posting a Document</H2></A>
787:
2.45.2.2! frystyk 788: <B>NOTE:</B> The Posting functions are used to send a data object
! 789: along with the request. The functions have the same set of return
! 790: codes as for the <A HREF="#LoadDoc">Load Functions</A>.
2.20 frystyk 791:
2.39 frystyk 792: <H3>Get a Save Stream</H3>
2.20 frystyk 793:
2.39 frystyk 794: <H4>On Entry,</H4>
2.5 timbl 795: <DL>
2.9 timbl 796: <DT>request->anchor
797: <DD> is valid anchor which
798: has previously beeing loaded
2.5 timbl 799: </DL>
800:
2.39 frystyk 801: <H4>On exit,</H4>
2.5 timbl 802: <DL>
803: <DT>returns
2.6 timbl 804: <DD> 0 if error else a stream
805: to save the object to.
2.5 timbl 806: </DL>
807:
808: <PRE>
2.45.2.2! frystyk 809: extern HTStream * HTSaveStream PARAMS((HTRequest * request));
! 810: </PRE>
! 811:
! 812: <H3>Copy an Anchor</H3>
! 813:
! 814: Fetch the URL (possibly local file URL) and send it using either
! 815: <B>PUT</B> or <B>POST</B> directly to the remote destination using
! 816: HTTP, that is remote copy of object <EM>O</EM> from <EM>A</EM> to
! 817: <EM>B</EM> where <EM>A</EM> might be the host of the application. The
! 818: caller can decide the exact method used and which HTTP header fields
! 819: to transmit by setting the user fields in the destination request
! 820: structure.
! 821:
! 822: <PRE>
! 823: extern int HTCopyAnchor PARAMS((HTAnchor * src_anchor,
! 824: HTRequest * src_req,
! 825: HTParentAnchor *dest_anchor,
! 826: HTRequest * dest_req));
! 827: </PRE>
! 828:
! 829:
! 830: <H3>Upload an Anchor</H3>
! 831:
! 832: Send the contents (in hyperdoc) of the source anchor using either
! 833: <B>PUT</B> or <B>POST</B> to the remote destination using HTTP. The
! 834: caller can decide the exact method used and which HTTP header fields
! 835: to transmit by setting the user fields in the request structure.
! 836: <EM>Format conversion</EM> can be made on the fly by setting the <A
! 837: HREF="#input_format">input_format field</A> in the destination request
! 838: structure. If the content-length is unknown (-1) then a <A
! 839: HREF="HTConLen.html">content-length counter</A> is automaticly put
! 840: into the stream pipe.
! 841:
! 842:
! 843: <PRE>
! 844: extern int HTUploadAnchor PARAMS((HTAnchor * src_anchor,
! 845: HTParentAnchor *dest_anchor,
! 846: HTRequest * dest_req));
2.39 frystyk 847: </PRE>
2.5 timbl 848:
1.1 timbl 849:
2.39 frystyk 850: <A NAME="ProtReg"><H2>Access Method Registration</H2></A>
1.1 timbl 851:
2.39 frystyk 852: An access method is defined by an HTProtocol structure which point to
853: the routines for performing the various logical operations on an
854: object: in HTTP terms, GET, PUT, and POST. The access methods
855: supported in the Library are initiated automaticly using the private
856: function <CODE>HTAccessInit()</CODE> <B>if not</B> defined
2.45.2.2! frystyk 857: <CODE>HT_NO_INIT</CODE> <P>
2.39 frystyk 858:
859: Each of these routine takes as a parameter a <A NAME="z2"
860: HREF="#z1">request structure</A> containing details of the request.
861: When the protocol class routine is called, the anchor element in the
862: request is already valid (made valid by HTAccess).
863:
864: <PRE>
865: typedef enum _HTSocBlock {
866: SOC_BLOCK,
2.42 frystyk 867: SOC_NON_BLOCK
2.39 frystyk 868: } HTSocBlock;
869:
870: typedef struct _HTProtocol {
871: char * name;
872: HTSocBlock block;
873: int (*load) PARAMS((HTRequest * request));
874: HTStream* (*saveStream) PARAMS((HTRequest * request));
875: HTStream* (*postStream) PARAMS((HTRequest * request,
876: HTParentAnchor* postTo));
877: } HTProtocol;
1.1 timbl 878:
2.40 frystyk 879: extern BOOL HTRegisterProtocol PARAMS((HTProtocol * protocol));
2.42 frystyk 880: extern void HTDisposeProtocols NOPARAMS;
2.5 timbl 881: </PRE>
1.1 timbl 882:
2.39 frystyk 883: <H3>Uses Protocol Blocking IO</H3>
1.1 timbl 884:
2.39 frystyk 885: A small function to make life easier. Returns <CODE>YES</CODE> or
2.42 frystyk 886: <CODE>NO</CODE>. If the Library is run in NON-INTERACTIVE MODE then
887: the function always returns YES;
2.38 howcome 888:
889: <PRE>
2.40 frystyk 890: extern BOOL HTProtocolBlocking PARAMS((HTRequest * request));
2.38 howcome 891: </PRE>
892:
2.39 frystyk 893: end
2.25 luotonen 894:
895: <PRE>
1.1 timbl 896: #endif /* HTACCESS_H */
2.25 luotonen 897: </PRE>
898: end of HTAccess
899: </BODY>
2.9 timbl 900: </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