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