Annotation of libwww/Library/src/HTAnchor.html, revision 2.51
2.7 timbl 1: <HTML>
2: <HEAD>
2.47 frystyk 3: <!-- Changed by: Henrik Frystyk Nielsen, 16-Jul-1996 -->
2.51 ! frystyk 4: <TITLE>W3C Sample Code Library libwww Anchor Class</TITLE>
2.8 timbl 5: </HEAD>
2.6 timbl 6: <BODY>
2.42 frystyk 7: <H1>
2.44 frystyk 8: The Anchor Class
2.42 frystyk 9: </H1>
2.15 frystyk 10: <PRE>
11: /*
2.23 frystyk 12: ** (c) COPYRIGHT MIT 1995.
2.15 frystyk 13: ** Please first read the full copyright statement in the file COPYRIGH.
14: */
15: </PRE>
2.42 frystyk 16: <P>
17: An anchor represents a region of a hypertext document which is linked to
18: another anchor in the same or a different document. Another name for anchors
19: would be URLs as an anchor represents all we know about a URL - including
20: where it points to and who points to it. Because the anchor objects
21: represent the part of the Web, the application has been in touch, it is often
22: useful to maintain the anchors throughout the lifetime of the application.
23: It would actually be most useful if we had persistent anchors so that an
2.44 frystyk 24: application could build up a higher knowledge about the Web topology.
2.42 frystyk 25: <P>
26: This module is implemented by <A HREF="HTAnchor.c">HTAnchor.c</A>, and it
2.51 ! frystyk 27: is a part of the <A HREF="http://www.w3.org/pub/WWW/Library/"> W3C Sample Code
2.42 frystyk 28: Library</A>.
2.15 frystyk 29: <PRE>
30: #ifndef HTANCHOR_H
1.1 timbl 31: #define HTANCHOR_H
2.24 frystyk 32:
2.18 frystyk 33: </PRE>
2.42 frystyk 34: <H2>
35: Types defined and used by the Anchor Object
36: </H2>
37: <P>
38: This is a set of videly used type definitions used through out the Library:
2.24 frystyk 39: <PRE>
2.44 frystyk 40: #include "WWWUtil.h"
2.35 frystyk 41:
2.24 frystyk 42: typedef HTAtom * HTFormat;
43: typedef HTAtom * HTLevel; /* Used to specify HTML level */
2.40 frystyk 44: typedef HTAtom * HTEncoding; /* C-E and C-T-E */
2.24 frystyk 45: typedef HTAtom * HTCharset;
46: typedef HTAtom * HTLanguage;
2.35 frystyk 47:
48: typedef struct _HTAnchor HTAnchor;
49: typedef struct _HTParentAnchor HTParentAnchor;
50: typedef struct _HTChildAnchor HTChildAnchor;
2.28 frystyk 51:
2.44 frystyk 52: #include "HTLink.h"
53: #include "HTMethod.h"
2.49 frystyk 54: #include "HTResponse.h"
2.35 frystyk 55: </PRE>
2.42 frystyk 56: <H2>
57: The Anchor Class
58: </H2>
59: <P>
60: We have three variants of the Anchor object - I guess some would call them
61: superclass and subclasses ;-) <A NAME="Generic"></A>
62: <H3>
2.44 frystyk 63: <A NAME="Generic">Anchor Base Class</A>
2.42 frystyk 64: </H3>
65: <P>
66: This is the super class of anchors. We often use this as an argument to the
67: functions that both accept parent anchors and child anchors. We separate
68: the first link from the others to avoid too many small mallocs involved by
69: a list creation. Most anchors only point to one place. <A NAME="parent"></A>
70: <H3>
71: <A NAME="parent">Anchor for a Parent Object</A>
72: </H3>
73: <P>
2.44 frystyk 74: These anchors points to the whole contents of any resource accesible by a
75: URI. The parent anchor now contains all known metainformation about that
76: object and in some cases the parent anchor also contains the document itself.
77: Often we get the metainformation about a document via the entity headers
78: in the HTTP specification.
2.42 frystyk 79: <H3>
80: <A NAME="child">Anchor for a Child Object</A>
81: </H3>
82: <P>
2.44 frystyk 83: A child anchor is a anchor object that points to a subpart of a hypertext
84: document. In HTML this is represented by the <CODE>NAME</CODE> tag of the
85: Anchor element.
2.42 frystyk 86: <P>
87: After we have defined the data structures we must define the methods that
88: can be used on them. All anchors are kept in an internal hash table so that
89: they are easier to find again.
90: <H3>
91: Find/Create a Parent Anchor
92: </H3>
93: <P>
94: This one is for a reference (link) which is found in a document, and might
95: not be already loaded. The parent anchor returned can either be created on
96: the spot or is already in the hash table.
2.18 frystyk 97: <PRE>
2.37 frystyk 98: extern HTAnchor * HTAnchor_findAddress (const char * address);
2.18 frystyk 99: </PRE>
2.42 frystyk 100: <H3>
101: Find/Create a Child Anchor
102: </H3>
103: <P>
104: This one is for a new child anchor being edited into an existing document.
105: The parent anchor must already exist but the child returned can either be
106: created on the spot or is already in the hash table. The <EM>tag</EM> is
107: the part that's after the '#' sign in a URI.
2.18 frystyk 108: <PRE>
2.32 frystyk 109: extern HTChildAnchor * HTAnchor_findChild (HTParentAnchor *parent,
2.37 frystyk 110: const char * tag);
2.7 timbl 111: </PRE>
2.42 frystyk 112: <H3>
113: Find/Create a Child Anchor and Link to Another Parent
114: </H3>
115: <P>
116: Find a child anchor anchor with a given parent and possibly a <EM>tag</EM>,
117: and (if passed) link this child to the URI given in the <EM>href</EM>. As
118: we really want typed links to the caller should also indicate what the type
119: of the link is (see HTTP spec for more information). The link is
120: <EM>relative</EM> to the address of the parent anchor.
2.18 frystyk 121: <PRE>
2.43 eric 122: extern HTChildAnchor * HTAnchor_findChildAndLink (
123: HTParentAnchor * parent, /* May not be 0 */
2.37 frystyk 124: const char * tag, /* May be "" or 0 */
125: const char * href, /* May be "" or 0 */
2.35 frystyk 126: HTLinkType ltype); /* May be 0 */
2.18 frystyk 127: </PRE>
2.42 frystyk 128: <H3>
129: Delete an Anchor
130: </H3>
131: <P>
132: All outgoing links from parent and children are deleted, and this anchor
133: is removed from the sources list of all its targets. We also delete the targets.
134: If this anchor's source list is empty, we delete it and its children.
2.18 frystyk 135: <PRE>
2.32 frystyk 136: extern BOOL HTAnchor_delete (HTParentAnchor *me);
2.20 frystyk 137: </PRE>
2.42 frystyk 138: <H3>
139: Delete all Anchors
140: </H3>
141: <P>
142: Deletes <EM>all</EM> anchors and return a list of all the objects (hyperdoc)
143: hanging of the parent anchors found while doing it. The application may keep
144: its own list of <CODE>HyperDoc</CODE>s, but this function returns it anyway.
145: It is <EM>always</EM> for the application to delete any
146: <CODE>HyperDoc</CODE>s. If NULL then no hyperdocs are returned. Return YES
147: if OK, else NO.
148: <P>
149: <B>Note:</B> This function is different from cleaning up the history list!
2.20 frystyk 150: <PRE>
2.32 frystyk 151: extern BOOL HTAnchor_deleteAll (HTList * objects);
2.18 frystyk 152: </PRE>
2.42 frystyk 153: <H2>
2.44 frystyk 154: <A NAME="links">Links and Anchors</A>
2.42 frystyk 155: </H2>
156: <P>
2.44 frystyk 157: Anchor objects are bound together by <A HREF="HTLink.html">Link objects</A>
158: that carry information about what type of link and whetther we have followed
159: the link etc. Any anchor object can have zero, one, or many links but the
160: normal case is one. Therefore we treat this is a special way.
161: <H3>
162: Handling the Main Link
163: </H3>
164: <P>
165: Any outgoing link can at any time be the main destination.
166: <PRE>
167: extern BOOL HTAnchor_setMainLink (HTAnchor * anchor, HTLink * link);
168: extern HTLink * HTAnchor_mainLink (HTAnchor * anchor);
169:
170: extern HTAnchor * HTAnchor_followMainLink (HTAnchor * anchor);
171: </PRE>
2.42 frystyk 172: <H3>
2.44 frystyk 173: Handling the Sub Links
2.42 frystyk 174: </H3>
2.44 frystyk 175: <PRE>
176: extern BOOL HTAnchor_setSubLinks (HTAnchor * anchor, HTList * list);
177: extern HTList * HTAnchor_subLinks (HTAnchor * anchor);
178: </PRE>
179: <H2>
180: Relations Between Children and Parents
181: </H2>
182: <P>
183: As always, children and parents have a compliated relationship and the libwww
184: Anchor class is no exception.
185: <H3>
2.42 frystyk 186: Who is Parent?
2.44 frystyk 187: </H3>
2.42 frystyk 188: <P>
2.18 frystyk 189: For parent anchors this returns the anchor itself
2.44 frystyk 190: <PRE>extern HTParentAnchor * HTAnchor_parent (HTAnchor *me);
2.18 frystyk 191: </PRE>
2.44 frystyk 192: <H3>
2.42 frystyk 193: Does it have any Anchors within it?
2.44 frystyk 194: </H3>
195: <P>
196: Does this parent anchor have any children
197: <PRE>extern BOOL HTAnchor_hasChildren (HTParentAnchor *me);
198: </PRE>
199: <H2>
2.45 frystyk 200: Anchor Addresses
2.44 frystyk 201: </H2>
202: <P>
203: There are two addresses of an anchor. The URI that was passed when the anchor
204: was crated and the physical address that's used when the URI is going to
205: be requested. The two addresses may be different if the request is going
2.45 frystyk 206: through a proxy or a gateway or it may have been mapped through a rule file.
2.44 frystyk 207: <H3>
208: Logical Address
209: </H3>
210: <P>
211: Returns the full URI of the anchor, child or parent as a malloc'd string
212: to be freed by the caller as when the anchor was created.
213: <PRE>extern char * HTAnchor_address (HTAnchor * me);
2.18 frystyk 214: </PRE>
2.42 frystyk 215: <H3>
2.45 frystyk 216: Expanded Logical Address
217: </H3>
218: <P>
219: When expanding URLs within a hypertext document, the base address is taken
220: as the following value if present (in that order):
221: <UL>
222: <LI>
223: <CODE>Content-Base</CODE> header
224: <LI>
225: <CODE>Content-Location</CODE> header
226: <LI>
227: Logical address
228: </UL>
229: <PRE>extern char * HTAnchor_expandedAddress (HTAnchor * me);
230: </PRE>
231: <H3>
2.44 frystyk 232: Physical address
2.42 frystyk 233: </H3>
234: <P>
2.44 frystyk 235: Contains the physical address after we haved looked for proxies etc.
236: <PRE>extern char * HTAnchor_physical (HTParentAnchor * me);
237: extern void HTAnchor_setPhysical (HTParentAnchor * me, char * protocol);
2.45 frystyk 238: extern void HTAnchor_clearPhysical (HTParentAnchor * me);
2.44 frystyk 239: </PRE>
240: <H2>
241: Entity Body Information
242: </H2>
243: <P>
2.42 frystyk 244: A parent anchor can have a data object bound to it. This data object does
245: can for example be a parsed version of a HTML that knows how to present itself
246: to the user, or it can be an unparsed data object. It's completely free for
247: the application to use this possibility, but a typical usage would to manage
248: the data object as part of a memory cache.
2.18 frystyk 249: <PRE>
2.35 frystyk 250: extern void HTAnchor_setDocument (HTParentAnchor *me, void * doc);
251: extern void * HTAnchor_document (HTParentAnchor *me);
2.18 frystyk 252: </PRE>
2.44 frystyk 253: <H2>
254: Entity Header Information
255: </H2>
256: <P>
257: The anchor object also contains all the metainformation that we know about
258: the object.
2.42 frystyk 259: <H3>
2.44 frystyk 260: Clear All header Information
2.42 frystyk 261: </H3>
2.49 frystyk 262: <PRE>
263: extern void HTAnchor_clearHeader (HTParentAnchor *me);
2.42 frystyk 264: </PRE>
265: <H3>
2.49 frystyk 266: Inherit Metainformation from the Response object
2.47 frystyk 267: </H3>
268: <P>
2.49 frystyk 269: Once we have decided to cache the object we transfer already parsed
270: metainformation from the <A HREF="HTResponse.html">HTResponse object </A>to
271: the anchor object and also the unparsed headers as we may wanna use that
272: information later.
2.47 frystyk 273: <PRE>
2.49 frystyk 274: extern BOOL HTAnchor_update (HTParentAnchor * me, HTResponse * response);
2.47 frystyk 275: </PRE>
276: <H3>
2.42 frystyk 277: Is the Anchor searchable?
278: </H3>
2.44 frystyk 279: <PRE>extern void HTAnchor_clearIndex (HTParentAnchor * me);
2.42 frystyk 280: extern void HTAnchor_setIndex (HTParentAnchor * me);
281: extern BOOL HTAnchor_isIndex (HTParentAnchor * me);
282: </PRE>
283: <H3>
2.44 frystyk 284: Anchor Title
2.42 frystyk 285: </H3>
286: <P>
287: We keep the title in the anchor as we then can refer to it later in the history
288: list etc. We can also obtain the title element if it is passed as a HTTP
289: header in the response. Any title element found in an HTML document will
290: overwrite a title given in a HTTP header.
2.44 frystyk 291: <PRE>extern const char * HTAnchor_title (HTParentAnchor *me);
2.32 frystyk 292: extern void HTAnchor_setTitle (HTParentAnchor *me,
2.37 frystyk 293: const char * title);
2.32 frystyk 294: extern void HTAnchor_appendTitle (HTParentAnchor *me,
2.37 frystyk 295: const char * title);
2.18 frystyk 296: </PRE>
2.42 frystyk 297: <H3>
2.44 frystyk 298: Content Base
299: </H3>
300: <P>
2.49 frystyk 301: The <CODE>Content-Base</CODE> header may be used for resolving
302: relative URLs within the entity. If it there is no
303: <CODE>Content-Base</CODE> header then we use the Content-Location if
304: present and absolute.
305: <PRE>
306: extern char * HTAnchor_base (HTParentAnchor * me);
2.44 frystyk 307: extern BOOL HTAnchor_setBase (HTParentAnchor * me, char * base);
308: </PRE>
309: <H3>
310: Content Location
311: </H3>
312: <P>
2.49 frystyk 313: Content location can either be an absolute or a relative URL. The URL may
314: be either absolute or relative. If it is relative then we parse it relative
315: to the <CODE>Content-Base</CODE> header of the request URI if any, otherwise
316: we use the Request URI.
317: <PRE>
318: extern char * HTAnchor_location (HTParentAnchor * me);
2.44 frystyk 319: extern BOOL HTAnchor_setLocation (HTParentAnchor * me, char * location);
320: </PRE>
321: <H3>
2.42 frystyk 322: Media Types (Content-Type)
323: </H3>
2.18 frystyk 324: <PRE>
2.32 frystyk 325: extern HTFormat HTAnchor_format (HTParentAnchor *me);
326: extern void HTAnchor_setFormat (HTParentAnchor *me,
327: HTFormat form);
2.18 frystyk 328: </PRE>
2.42 frystyk 329: <H3>
2.44 frystyk 330: Content Type Parameters
331: </H3>
332: <P>
333: The Anchor obejct stores all content parameters in an Association list so
334: here you will always be able to find them. We also have a few methods for
335: the special cases: <CODE>charset</CODE> and <CODE>level</CODE> as they are
336: often needed.
337: <PRE>
338: extern HTAssocList * HTAnchor_formatParam (HTParentAnchor * me);
339:
340: extern BOOL HTAnchor_addFormatParam (HTParentAnchor * me,
341: const char * name, const char * value);
342: </PRE>
343: <H4>
2.42 frystyk 344: Charset parameter to Content-Type
2.44 frystyk 345: </H4>
2.18 frystyk 346: <PRE>
2.32 frystyk 347: extern HTCharset HTAnchor_charset (HTParentAnchor *me);
2.44 frystyk 348: extern BOOL HTAnchor_setCharset (HTParentAnchor *me,
2.32 frystyk 349: HTCharset charset);
2.18 frystyk 350: </PRE>
2.44 frystyk 351: <H4>
2.42 frystyk 352: Level parameter to Content-Type
2.44 frystyk 353: </H4>
2.21 frystyk 354: <PRE>
2.32 frystyk 355: extern HTLevel HTAnchor_level (HTParentAnchor * me);
2.44 frystyk 356: extern BOOL HTAnchor_setLevel (HTParentAnchor * me,
2.32 frystyk 357: HTLevel level);
2.22 frystyk 358: </PRE>
2.42 frystyk 359: <H3>
360: Content Language
361: </H3>
2.22 frystyk 362: <PRE>
2.39 frystyk 363: extern HTList * HTAnchor_language (HTParentAnchor * me);
364: extern BOOL HTAnchor_addLanguage (HTParentAnchor *me, HTLanguage lang);
2.21 frystyk 365: </PRE>
2.42 frystyk 366: <H3>
367: Content Encoding
368: </H3>
2.18 frystyk 369: <PRE>
2.39 frystyk 370: extern HTList * HTAnchor_encoding (HTParentAnchor * me);
371: extern BOOL HTAnchor_addEncoding (HTParentAnchor * me, HTEncoding enc);
2.50 frystyk 372: extern BOOL HTAnchor_removeEncoding (HTParentAnchor * me, HTEncoding enc);
2.18 frystyk 373: </PRE>
2.42 frystyk 374: <H3>
375: Content Transfer Encoding
376: </H3>
2.18 frystyk 377: <PRE>
2.40 frystyk 378: extern HTEncoding HTAnchor_transfer (HTParentAnchor *me);
379: extern void HTAnchor_setTransfer (HTParentAnchor *me,
380: HTEncoding transfer);
2.18 frystyk 381: </PRE>
2.42 frystyk 382: <H3>
383: Content Length
384: </H3>
2.18 frystyk 385: <PRE>
2.41 frystyk 386: extern long int HTAnchor_length (HTParentAnchor * me);
387: extern void HTAnchor_setLength (HTParentAnchor * me, long int length);
388: extern void HTAnchor_addLength (HTParentAnchor * me, long int deltalength);
2.18 frystyk 389: </PRE>
2.42 frystyk 390: <H3>
2.44 frystyk 391: Content MD5
392: </H3>
393: <PRE>
394: extern char * HTAnchor_md5 (HTParentAnchor * me);
2.49 frystyk 395: extern BOOL HTAnchor_setMd5 (HTParentAnchor * me, const char * hash);
2.44 frystyk 396: </PRE>
397: <H3>
2.42 frystyk 398: Allowed methods (Allow)
399: </H3>
2.18 frystyk 400: <PRE>
2.49 frystyk 401: extern HTMethod HTAnchor_allow (HTParentAnchor * me);
402: extern void HTAnchor_setAllow (HTParentAnchor * me, HTMethod methodset);
403: extern void HTAnchor_appendAllow (HTParentAnchor * me, HTMethod methodset);
2.18 frystyk 404: </PRE>
2.42 frystyk 405: <H3>
406: Version
407: </H3>
2.18 frystyk 408: <PRE>
2.35 frystyk 409: extern char * HTAnchor_version (HTParentAnchor * me);
2.37 frystyk 410: extern void HTAnchor_setVersion (HTParentAnchor * me, const char * version);
2.28 frystyk 411: </PRE>
2.42 frystyk 412: <H3>
413: Date
414: </H3>
415: <P>
2.28 frystyk 416: Returns the date that was registered in the RFC822 header "Date"
417: <PRE>
2.35 frystyk 418: extern time_t HTAnchor_date (HTParentAnchor * me);
2.37 frystyk 419: extern void HTAnchor_setDate (HTParentAnchor * me, const time_t date);
2.28 frystyk 420: </PRE>
2.42 frystyk 421: <H3>
422: Last Modified Date
423: </H3>
424: <P>
2.28 frystyk 425: Returns the date that was registered in the RFC822 header "Last-Modified"
426: <PRE>
2.35 frystyk 427: extern time_t HTAnchor_lastModified (HTParentAnchor * me);
2.37 frystyk 428: extern void HTAnchor_setLastModified (HTParentAnchor * me, const time_t lm);
2.28 frystyk 429: </PRE>
2.42 frystyk 430: <H3>
2.44 frystyk 431: Entity Tag
432: </H3>
433: <P>
434: Entity tags are used for comparing two or more entities from the same requested
435: resource. It is a cache validator much in the same way <I>Date</I> can be.
436: The difference is that we can't always trust the date and time stamp and
437: hence we must have something stronger.
438: <PRE>extern char * HTAnchor_etag (HTParentAnchor * me);
439: extern void HTAnchor_setEtag (HTParentAnchor * me, const char * etag);
440: extern BOOL HTAnchor_isEtagWeak (HTParentAnchor * me);
441: </PRE>
442: <H3>
2.47 frystyk 443: Age Header
444: </H3>
445: <P>
446: The <CODE>Age</CODE> response-header field conveys the sender's estimate
447: of the amount of time since the response (or its revalidation) was generated
448: at the origin server. A cached response is "fresh" if its age does not exceed
449: its freshness lifetime.
450: <PRE>
451: extern time_t HTAnchor_age (HTParentAnchor * me);
452: extern void HTAnchor_setAge (HTParentAnchor * me, const time_t age);
453: </PRE>
454: <H3>
2.42 frystyk 455: Expires Date
456: </H3>
2.28 frystyk 457: <PRE>
2.35 frystyk 458: extern time_t HTAnchor_expires (HTParentAnchor * me);
2.37 frystyk 459: extern void HTAnchor_setExpires (HTParentAnchor * me, const time_t exp);
2.18 frystyk 460: </PRE>
2.42 frystyk 461: <H3>
462: Derived from
463: </H3>
2.18 frystyk 464: <PRE>
2.35 frystyk 465: extern char * HTAnchor_derived (HTParentAnchor *me);
2.37 frystyk 466: extern void HTAnchor_setDerived (HTParentAnchor *me, const char *derived_from);
2.18 frystyk 467: </PRE>
2.44 frystyk 468: <H2>
2.42 frystyk 469: Status of Header Parsing
2.44 frystyk 470: </H2>
2.42 frystyk 471: <P>
2.47 frystyk 472: This is primarily for internal use. It is so that we can check whether the
473: header has been parsed or not.
2.49 frystyk 474: <PRE>
475: extern BOOL HTAnchor_headerParsed (HTParentAnchor *me);
2.32 frystyk 476: extern void HTAnchor_setHeaderParsed (HTParentAnchor *me);
2.7 timbl 477: </PRE>
2.49 frystyk 478: <H3>
479: Original Response Headers
480: </H3>
481: <P>
482: The <A HREF="HTMIME.html">MIME parser</A> may add the original response headers
483: as (name,value) pairs.
484: <PRE>
485: extern BOOL HTAnchor_setHeader (HTParentAnchor * me, HTAssocList * list);
486: extern HTAssocList * HTAnchor_header (HTParentAnchor * me);
487: </PRE>
2.18 frystyk 488: <PRE>
489: #endif /* HTANCHOR_H */
490: </PRE>
2.42 frystyk 491: <P>
492: <HR>
2.39 frystyk 493: <ADDRESS>
2.51 ! frystyk 494: @(#) $Id: HTAnchor.html,v 2.50 1997/02/16 17:49:06 frystyk Exp $
2.39 frystyk 495: </ADDRESS>
2.42 frystyk 496: </BODY></HTML>
Webmaster
![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to HTAnchor.html CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [Public] / libwww / Library / src