Annotation of libwww/Library/src/HTAnchor.html, revision 2.44
2.7 timbl 1: <HTML>
2: <HEAD>
2.44 ! frystyk 3: <!-- Changed by: Henrik Frystyk Nielsen, 1-Jul-1996 -->
! 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>
! 208: Anchor Address
! 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
! 214: through a proxy or a gateway.
! 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.44 ! frystyk 224: Physical address
2.42 frystyk 225: </H3>
226: <P>
2.44 ! frystyk 227: Contains the physical address after we haved looked for proxies etc.
! 228: <PRE>extern char * HTAnchor_physical (HTParentAnchor * me);
! 229: extern void HTAnchor_setPhysical (HTParentAnchor * me, char * protocol);
! 230: </PRE>
! 231: <H2>
! 232: Entity Body Information
! 233: </H2>
! 234: <P>
2.42 frystyk 235: A parent anchor can have a data object bound to it. This data object does
236: can for example be a parsed version of a HTML that knows how to present itself
237: to the user, or it can be an unparsed data object. It's completely free for
238: the application to use this possibility, but a typical usage would to manage
239: the data object as part of a memory cache.
2.18 frystyk 240: <PRE>
2.35 frystyk 241: extern void HTAnchor_setDocument (HTParentAnchor *me, void * doc);
242: extern void * HTAnchor_document (HTParentAnchor *me);
2.18 frystyk 243: </PRE>
2.44 ! frystyk 244: <H2>
! 245: Entity Header Information
! 246: </H2>
! 247: <P>
! 248: The anchor object also contains all the metainformation that we know about
! 249: the object.
2.42 frystyk 250: <H3>
2.44 ! frystyk 251: Clear All header Information
2.42 frystyk 252: </H3>
2.44 ! frystyk 253: <PRE>extern void HTAnchor_clearHeader (HTParentAnchor *me);
2.42 frystyk 254: </PRE>
255: <H3>
256: Cache Information
257: </H3>
258: <P>
259: If the cache manager finds a cached object, it is registered in the anchor
260: object. This way the <A HREF="HTFile.html">file loader</A> knows that it
261: is a MIME data object. The cache manager does not know whether the data object
262: is out of date (for example if a <EM>Expires:</EM> header is in the MIME
263: header. This is for the <A HREF="HTMIME.html">MIME parser</A> to find out.
2.44 ! frystyk 264: <PRE>extern BOOL HTAnchor_cacheHit (HTParentAnchor * me);
2.42 frystyk 265: extern void HTAnchor_setCacheHit (HTParentAnchor * me, BOOL cacheHit);
266: </PRE>
267: <H3>
268: Is the Anchor searchable?
269: </H3>
2.44 ! frystyk 270: <PRE>extern void HTAnchor_clearIndex (HTParentAnchor * me);
2.42 frystyk 271: extern void HTAnchor_setIndex (HTParentAnchor * me);
272: extern BOOL HTAnchor_isIndex (HTParentAnchor * me);
273: </PRE>
274: <H3>
2.44 ! frystyk 275: Anchor Title
2.42 frystyk 276: </H3>
277: <P>
278: We keep the title in the anchor as we then can refer to it later in the history
279: list etc. We can also obtain the title element if it is passed as a HTTP
280: header in the response. Any title element found in an HTML document will
281: overwrite a title given in a HTTP header.
2.44 ! frystyk 282: <PRE>extern const char * HTAnchor_title (HTParentAnchor *me);
2.32 frystyk 283: extern void HTAnchor_setTitle (HTParentAnchor *me,
2.37 frystyk 284: const char * title);
2.32 frystyk 285: extern void HTAnchor_appendTitle (HTParentAnchor *me,
2.37 frystyk 286: const char * title);
2.18 frystyk 287: </PRE>
2.42 frystyk 288: <H3>
2.44 ! frystyk 289: Content Base
! 290: </H3>
! 291: <P>
! 292: The <CODE>Content-Base</CODE> header may be used for resolving relative URLs
! 293: within the entity.
! 294: <PRE>extern char * HTAnchor_base (HTParentAnchor * me);
! 295: extern BOOL HTAnchor_setBase (HTParentAnchor * me, char * base);
! 296: </PRE>
! 297: <H3>
! 298: Content Location
! 299: </H3>
! 300: <P>
! 301: Content location can either be an absolute or a relative URL. If it is relative
! 302: then parse it relative to the <CODE>Content-Base</CODE> header of the request
! 303: URI.
! 304: <PRE>extern char * HTAnchor_location (HTParentAnchor * me);
! 305: extern BOOL HTAnchor_setLocation (HTParentAnchor * me, char * location);
! 306: </PRE>
! 307: <H3>
2.42 frystyk 308: Media Types (Content-Type)
309: </H3>
2.18 frystyk 310: <PRE>
2.32 frystyk 311: extern HTFormat HTAnchor_format (HTParentAnchor *me);
312: extern void HTAnchor_setFormat (HTParentAnchor *me,
313: HTFormat form);
2.18 frystyk 314: </PRE>
2.42 frystyk 315: <H3>
2.44 ! frystyk 316: Content Type Parameters
! 317: </H3>
! 318: <P>
! 319: The Anchor obejct stores all content parameters in an Association list so
! 320: here you will always be able to find them. We also have a few methods for
! 321: the special cases: <CODE>charset</CODE> and <CODE>level</CODE> as they are
! 322: often needed.
! 323: <PRE>
! 324: extern HTAssocList * HTAnchor_formatParam (HTParentAnchor * me);
! 325:
! 326: extern BOOL HTAnchor_addFormatParam (HTParentAnchor * me,
! 327: const char * name, const char * value);
! 328: </PRE>
! 329: <H4>
2.42 frystyk 330: Charset parameter to Content-Type
2.44 ! frystyk 331: </H4>
2.18 frystyk 332: <PRE>
2.32 frystyk 333: extern HTCharset HTAnchor_charset (HTParentAnchor *me);
2.44 ! frystyk 334: extern BOOL HTAnchor_setCharset (HTParentAnchor *me,
2.32 frystyk 335: HTCharset charset);
2.18 frystyk 336: </PRE>
2.44 ! frystyk 337: <H4>
2.42 frystyk 338: Level parameter to Content-Type
2.44 ! frystyk 339: </H4>
2.21 frystyk 340: <PRE>
2.32 frystyk 341: extern HTLevel HTAnchor_level (HTParentAnchor * me);
2.44 ! frystyk 342: extern BOOL HTAnchor_setLevel (HTParentAnchor * me,
2.32 frystyk 343: HTLevel level);
2.22 frystyk 344: </PRE>
2.42 frystyk 345: <H3>
346: Content Language
347: </H3>
2.22 frystyk 348: <PRE>
2.39 frystyk 349: extern HTList * HTAnchor_language (HTParentAnchor * me);
350: extern BOOL HTAnchor_addLanguage (HTParentAnchor *me, HTLanguage lang);
2.21 frystyk 351: </PRE>
2.42 frystyk 352: <H3>
353: Content Encoding
354: </H3>
2.18 frystyk 355: <PRE>
2.39 frystyk 356: extern HTList * HTAnchor_encoding (HTParentAnchor * me);
357: extern BOOL HTAnchor_addEncoding (HTParentAnchor * me, HTEncoding enc);
2.18 frystyk 358: </PRE>
2.42 frystyk 359: <H3>
360: Content Transfer Encoding
361: </H3>
2.18 frystyk 362: <PRE>
2.40 frystyk 363: extern HTEncoding HTAnchor_transfer (HTParentAnchor *me);
364: extern void HTAnchor_setTransfer (HTParentAnchor *me,
365: HTEncoding transfer);
2.18 frystyk 366: </PRE>
2.42 frystyk 367: <H3>
368: Content Length
369: </H3>
2.18 frystyk 370: <PRE>
2.41 frystyk 371: extern long int HTAnchor_length (HTParentAnchor * me);
372: extern void HTAnchor_setLength (HTParentAnchor * me, long int length);
373: extern void HTAnchor_addLength (HTParentAnchor * me, long int deltalength);
2.18 frystyk 374: </PRE>
2.42 frystyk 375: <H3>
2.44 ! frystyk 376: Content MD5
! 377: </H3>
! 378: <PRE>
! 379: extern char * HTAnchor_md5 (HTParentAnchor * me);
! 380: extern void HTAnchor_setMd5 (HTParentAnchor * me, const char * hash);
! 381: </PRE>
! 382: <H3>
2.42 frystyk 383: Allowed methods (Allow)
384: </H3>
2.18 frystyk 385: <PRE>
2.36 frystyk 386: extern HTMethod HTAnchor_methods (HTParentAnchor * me);
387: extern void HTAnchor_setMethods (HTParentAnchor * me, HTMethod methodset);
388: extern void HTAnchor_appendMethods (HTParentAnchor * me, HTMethod methodset);
2.18 frystyk 389: </PRE>
2.42 frystyk 390: <H3>
391: Version
392: </H3>
2.18 frystyk 393: <PRE>
2.35 frystyk 394: extern char * HTAnchor_version (HTParentAnchor * me);
2.37 frystyk 395: extern void HTAnchor_setVersion (HTParentAnchor * me, const char * version);
2.28 frystyk 396: </PRE>
2.42 frystyk 397: <H3>
398: Date
399: </H3>
400: <P>
2.28 frystyk 401: Returns the date that was registered in the RFC822 header "Date"
402: <PRE>
2.35 frystyk 403: extern time_t HTAnchor_date (HTParentAnchor * me);
2.37 frystyk 404: extern void HTAnchor_setDate (HTParentAnchor * me, const time_t date);
2.28 frystyk 405: </PRE>
2.42 frystyk 406: <H3>
407: Last Modified Date
408: </H3>
409: <P>
2.28 frystyk 410: Returns the date that was registered in the RFC822 header "Last-Modified"
411: <PRE>
2.35 frystyk 412: extern time_t HTAnchor_lastModified (HTParentAnchor * me);
2.37 frystyk 413: extern void HTAnchor_setLastModified (HTParentAnchor * me, const time_t lm);
2.28 frystyk 414: </PRE>
2.42 frystyk 415: <H3>
2.44 ! frystyk 416: Entity Tag
! 417: </H3>
! 418: <P>
! 419: Entity tags are used for comparing two or more entities from the same requested
! 420: resource. It is a cache validator much in the same way <I>Date</I> can be.
! 421: The difference is that we can't always trust the date and time stamp and
! 422: hence we must have something stronger.
! 423: <PRE>extern char * HTAnchor_etag (HTParentAnchor * me);
! 424: extern void HTAnchor_setEtag (HTParentAnchor * me, const char * etag);
! 425: extern BOOL HTAnchor_isEtagWeak (HTParentAnchor * me);
! 426: </PRE>
! 427: <H3>
2.42 frystyk 428: Expires Date
429: </H3>
2.28 frystyk 430: <PRE>
2.35 frystyk 431: extern time_t HTAnchor_expires (HTParentAnchor * me);
2.37 frystyk 432: extern void HTAnchor_setExpires (HTParentAnchor * me, const time_t exp);
2.18 frystyk 433: </PRE>
2.42 frystyk 434: <H3>
435: Derived from
436: </H3>
2.18 frystyk 437: <PRE>
2.35 frystyk 438: extern char * HTAnchor_derived (HTParentAnchor *me);
2.37 frystyk 439: extern void HTAnchor_setDerived (HTParentAnchor *me, const char *derived_from);
2.18 frystyk 440: </PRE>
2.42 frystyk 441: <H3>
442: Extra Headers
443: </H3>
444: <P>
2.18 frystyk 445: List of unknown headers coming in from the network. Do not use the
2.42 frystyk 446: <CODE>HTAnchor_addExtra()</CODE> function to extra headers here, but use
447: the field in the <A HREF="HTReq.html#z1">request structure</A> for sending
448: test headers.
2.7 timbl 449: <PRE>
2.32 frystyk 450: extern HTList * HTAnchor_Extra (HTParentAnchor *me);
451: extern void HTAnchor_addExtra (HTParentAnchor *me,
2.37 frystyk 452: const char * header);
2.18 frystyk 453: </PRE>
2.44 ! frystyk 454: <H2>
2.42 frystyk 455: Status of Header Parsing
2.44 ! frystyk 456: </H2>
2.42 frystyk 457: <P>
2.18 frystyk 458: These are primarily for internal use
2.44 ! frystyk 459: <PRE>extern BOOL HTAnchor_headerParsed (HTParentAnchor *me);
2.32 frystyk 460: extern void HTAnchor_setHeaderParsed (HTParentAnchor *me);
2.7 timbl 461: </PRE>
2.18 frystyk 462: <PRE>
463: #endif /* HTANCHOR_H */
464: </PRE>
2.42 frystyk 465: <P>
466: <HR>
2.39 frystyk 467: <ADDRESS>
2.44 ! frystyk 468: @(#) $Id: HTAnchor.html,v 2.43 1996/06/03 19:25:02 eric Exp $
2.39 frystyk 469: </ADDRESS>
2.42 frystyk 470: </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