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