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