Annotation of libwww/Library/src/HTAnchor.html, revision 2.37
2.7 timbl 1: <HTML>
2: <HEAD>
2.35 frystyk 3: <TITLE>Public Anchor Object</TITLE>
2.36 frystyk 4: <!-- Changed by: Henrik Frystyk Nielsen, 26-Feb-1996 -->
2.8 timbl 5: </HEAD>
2.6 timbl 6: <BODY>
2.15 frystyk 7:
2.35 frystyk 8: <H1>Public Anchor Object</H1>
2.15 frystyk 9:
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>
16:
17: An anchor represents a region of a hypertext document which is linked
2.18 frystyk 18: to another anchor in the same or a different document. As always we
19: must emulate the fancy features of C++ by hand :-(. In this module you
20: find:
21:
22: <UL>
23: <LI><A HREF="#creation">Creation and deletion methods</A>
2.21 frystyk 24: <LI><A HREF="#links">Manipulation of Links</A>
2.18 frystyk 25: <LI><A HREF="#access">Access Methods for information</A>
26: </UL>
2.15 frystyk 27:
28: This module is implemented by <A HREF="HTAnchor.c">HTAnchor.c</A>, and
2.32 frystyk 29: it is a part of the <A HREF="http://www.w3.org/pub/WWW/Library/"> W3C
30: Reference Library</A>.
2.15 frystyk 31:
32: <PRE>
33: #ifndef HTANCHOR_H
1.1 timbl 34: #define HTANCHOR_H
2.24 frystyk 35:
2.17 frystyk 36: #include "HTList.h"
37: #include "HTAtom.h"
2.25 frystyk 38: #include "HTMethod.h"
2.18 frystyk 39: </PRE>
1.1 timbl 40:
2.35 frystyk 41: <H2>Types defined by the Anchor Object</H2>
2.24 frystyk 42:
43: This is a set of videly used type definitions used through out the
44: Library:
45:
46: <PRE>
2.35 frystyk 47: typedef struct _HTLink HTLink;
48:
2.24 frystyk 49: typedef HTAtom * HTFormat;
50: typedef HTAtom * HTLevel; /* Used to specify HTML level */
51: typedef HTAtom * HTEncoding; /* Content Encoding */
52: typedef HTAtom * HTCte; /* Content transfer encoding */
53: typedef HTAtom * HTCharset;
54: typedef HTAtom * HTLanguage;
2.35 frystyk 55:
56: typedef struct _HTAnchor HTAnchor;
57: typedef struct _HTParentAnchor HTParentAnchor;
58: typedef struct _HTChildAnchor HTChildAnchor;
2.24 frystyk 59: </PRE>
60:
2.35 frystyk 61: <A NAME="links"><H2>The Link Object</H2></A>
1.1 timbl 62:
2.35 frystyk 63: Anchors are bound together using link objects. Each anchor can be the
64: source or destination of zero, one, or more links from and to other
65: anchors.
66:
67: <H3>Link Destination</H3>
1.1 timbl 68:
2.18 frystyk 69: <PRE>
2.35 frystyk 70: extern BOOL HTLink_setDestination (HTLink * link, HTAnchor * dest);
71: extern HTAnchor * HTLink_destination (HTLink * link);
2.18 frystyk 72: </PRE>
1.1 timbl 73:
2.35 frystyk 74: <H3>Link Result</H3>
75:
76: When a link has been used for posting an object from a source to a
77: destination link, the result of the operation is stored as part of the
78: link information.
2.18 frystyk 79:
80: <PRE>
2.35 frystyk 81: typedef enum _HTLinkResult {
2.28 frystyk 82: HT_LINK_INVALID = -1,
83: HT_LINK_NONE = 0,
84: HT_LINK_ERROR,
85: HT_LINK_OK
86: } HTLinkResult;
87:
2.35 frystyk 88: extern BOOL HTLink_setResult (HTLink * link, HTLinkResult result);
89: extern HTLinkResult HTLink_result (HTLink * link);
90: </PRE>
91:
92: <H3>Link Method</H3>
93:
94: The method used in a link can be PUT, or POST, for example
95:
96: <PRE>
97: extern BOOL HTLink_setMethod (HTLink * link, HTMethod method);
98: extern HTMethod HTLink_method (HTLink * link);
99: </PRE>
100:
101: <H3>Link Type</H3>
102:
103: This is used for typed links.
104:
105: <PRE>
106: typedef HTAtom * HTLinkType;
107:
108: extern BOOL HTLink_setType (HTLink * link, HTLinkType type);
109: extern HTLinkType HTLink_type (HTLink * link);
110: </PRE>
111:
112: <H2>Relations between Links and Anchors</H2>
113:
114: <H3>Link this Anchor to another given one</H3>
115:
116: A single anchor may have many outgoing links of which the default is
117: the <EM>main link</EM>. If one already exists then this new link is
118: simply added to the list.
119:
120: <PRE>
121: extern BOOL HTAnchor_link (HTAnchor * source,
122: HTAnchor * destination,
123: HTLinkType type,
124: HTMethod method);
125: </PRE>
126:
127: <H3>Find the Link Object that Binds two Anchors</H3>
128:
129: If the destination anchor is a target of a link from the source anchor
130: then return the link object, else NULL.
131:
132: <PRE>
133: extern HTLink * HTAnchor_findLink (HTAnchor *src, HTAnchor *dest);
134: </PRE>
135:
136: <H3>Find destination with given relationship</H3>
137:
138: Return the anchor with a given typed link.
139:
140: <PRE>
141: extern HTAnchor * HTAnchor_followTypedLink (HTAnchor *me, HTLinkType type);
142: </PRE>
143:
144: <H3>Handling the Main Link</H3>
145:
146: Any outgoing link can at any time be the main destination.
147:
148: <PRE>
149: extern BOOL HTAnchor_setMainLink (HTAnchor * anchor, HTLink * link);
150: extern HTLink * HTAnchor_mainLink (HTAnchor * anchor);
151:
152: extern HTAnchor * HTAnchor_followMainLink (HTAnchor * anchor);
153: </PRE>
154:
155: <H3>Handling the Sub Links</H3>
156:
157: <PRE>
158: extern BOOL HTAnchor_setSubLinks (HTAnchor * anchor, HTList * list);
159: extern HTList * HTAnchor_subLinks (HTAnchor * anchor);
2.18 frystyk 160: </PRE>
1.1 timbl 161:
2.35 frystyk 162: <H3>Move Link Information</H3>
163:
164: Move all link information form one anchor to another. This is useful
165: when we get a redirection on a request and want to inherit the link
166: information to the new anchor and change the link information in the
167: old one to "redirect".
168:
169: <PRE>
170: extern BOOL HTAnchor_moveAllLinks (HTAnchor *src, HTAnchor *dest);
171: </PRE>
172:
173: <H3>Remove Link Information</H3>
174:
175: Delete link information between two or more anchors
176:
177: <PRE>
178: extern BOOL HTAnchor_removeLink (HTAnchor *src, HTAnchor *dest);
179: extern BOOL HTAnchor_removeAllLinks (HTAnchor * me);
180: </PRE>
181:
182: <H3>Move a child anchor to the head of the list of its siblings</H3>
183:
184: This is to ensure that an anchor which might have already existed is
185: put in the correct order as we load the document.
186:
187: <PRE>
188: extern void HTAnchor_makeLastChild (HTChildAnchor *me);
189: </PRE>
190:
191: <H2>Anchor Objects</H2>
192:
193: We have three variants of the Anchor object - I guess some would call
194: them superclass and subclasses ;-)
195:
2.14 frystyk 196: <A NAME="Generic"><H3>Generic Anchor type</H3></A>
2.18 frystyk 197:
198: This is the super class of anchors. We often use this as an argument
199: to the functions that both accept parent anchors and child anchors. We
200: separate the first link from the others to avoid too many small
201: mallocs involved by a list creation. Most anchors only point to one
202: place.
203:
204: <A NAME="parent"><H3>Anchor for a Parent Object</H3></A>
205:
206: These anchors points to the whole contents of a graphic object
207: (document). The parent anchor of a parent anchor is itself. The parent
208: anchor now contains all meta information about the object. This is
2.21 frystyk 209: largely the entity headers in the HTTP specification.
2.18 frystyk 210:
211: <A NAME="child"><H3>Anchor for a Child Object</H3></A>
1.1 timbl 212:
2.18 frystyk 213: A child anchor is a anchor object that points to a subpart of a
214: graphic object (document)
215:
216: <A NAME="creation"><H2>Creation and Deletion Methods</H2></A>
217:
218: After we have defined the data structures we must define the methods
2.21 frystyk 219: that can be used on them. All anchors are kept in an internal hash
220: table so that they are easier to find again.
2.18 frystyk 221:
222: <H3>Find/Create a Parent Anchor</H3>
223:
224: This one is for a reference (link) which is found in a document, and
225: might not be already loaded. The parent anchor returned can either be
226: created on the spot or is already in the hash table.
227:
228: <PRE>
2.37 ! frystyk 229: extern HTAnchor * HTAnchor_findAddress (const char * address);
2.18 frystyk 230: </PRE>
231:
232: <H3>Find/Create a Child Anchor</H3>
1.1 timbl 233:
2.18 frystyk 234: This one is for a new child anchor being edited into an existing
235: document. The parent anchor must already exist but the child returned
236: can either be created on the spot or is already in the hash table. The
237: <EM>tag</EM> is the part that's after the '#' sign in a URI.
238:
239: <PRE>
2.32 frystyk 240: extern HTChildAnchor * HTAnchor_findChild (HTParentAnchor *parent,
2.37 ! frystyk 241: const char * tag);
2.7 timbl 242: </PRE>
243:
2.18 frystyk 244: <H3>Find/Create a Child Anchor and Link to Another Parent</H3>
245:
246: Find a child anchor anchor with a given parent and possibly a
247: <EM>tag</EM>, and (if passed) link this child to the URI given in the
248: <EM>href</EM>. As we really want typed links to the caller should also
249: indicate what the type of the link is (see HTTP spec for more
250: information). The link is <EM>relative</EM> to the address of the
251: parent anchor.
252:
253: <PRE>
254: extern HTChildAnchor * HTAnchor_findChildAndLink
2.32 frystyk 255: (HTParentAnchor * parent, /* May not be 0 */
2.37 ! frystyk 256: const char * tag, /* May be "" or 0 */
! 257: const char * href, /* May be "" or 0 */
2.35 frystyk 258: HTLinkType ltype); /* May be 0 */
2.18 frystyk 259: </PRE>
260:
261: <H3>Delete an Anchor</H3>
262:
2.21 frystyk 263: All outgoing links from parent and children are deleted, and this
264: anchor is removed from the sources list of all its targets. We also
265: delete the targets. If this anchor's source list is empty, we delete
266: it and its children.
2.18 frystyk 267:
268: <PRE>
2.32 frystyk 269: extern BOOL HTAnchor_delete (HTParentAnchor *me);
2.20 frystyk 270: </PRE>
271:
272: <H3>Delete all Anchors</H3>
273:
2.35 frystyk 274: Deletes <EM>all</EM> anchors and return a list of all the objects
275: (hyperdoc) hanging of the parent anchors found while doing it. The
276: application may keep its own list of <CODE>HyperDoc</CODE>s, but this
277: function returns it anyway. It is <EM>always</EM> for the application
278: to delete any <CODE>HyperDoc</CODE>s. If NULL then no hyperdocs are
279: returned. Return YES if OK, else NO. <P>
2.21 frystyk 280:
281: <B>Note:</B> This function is different from cleaning up the history
282: list!
2.20 frystyk 283:
284: <PRE>
2.32 frystyk 285: extern BOOL HTAnchor_deleteAll (HTList * objects);
2.18 frystyk 286: </PRE>
287:
288:
289: <A NAME="access"><H2>Access Methods of an Anchor</H2></A>
290:
291: These functions should be used to access information within the anchor
292: structures.
293:
294: <H3>Relations to Other Anchors</H3>
295:
296: <H4>Who is Parent?</H4>
297:
298: For parent anchors this returns the anchor itself
299:
300: <PRE>
2.32 frystyk 301: extern HTParentAnchor * HTAnchor_parent (HTAnchor *me);
2.18 frystyk 302: </PRE>
303:
304: <H4>Does it have any Anchors within it?</H4>
305:
306: <PRE>
2.32 frystyk 307: extern BOOL HTAnchor_hasChildren (HTParentAnchor *me);
2.18 frystyk 308: </PRE>
309:
2.35 frystyk 310: <H3>Binding a Data Object to an Anchor</H3>
2.18 frystyk 311:
2.35 frystyk 312: A parent anchor can have a data object bound to it. This data object
313: does can for example be a parsed version of a HTML that knows how to
314: present itself to the user, or it can be an unparsed data object. It's
315: completely free for the application to use this possibility, but a
316: typical usage would to manage the data object as part of a memory
317: cache.
2.18 frystyk 318:
319: <PRE>
2.35 frystyk 320: extern void HTAnchor_setDocument (HTParentAnchor *me, void * doc);
321: extern void * HTAnchor_document (HTParentAnchor *me);
2.18 frystyk 322: </PRE>
323:
324: <H3>URI Information of Anchors</H3>
325:
326: There are two addresses of an anchor. The URI that was passed when the
327: anchor was crated and the physical address that's used when the URI is
328: going to be requested. The two addresses may be different if the
329: request is going through a proxy or a gateway.
330:
331: <H4>Get URI Address</H4>
332:
333: Returns the full URI of the anchor, child or parent as a malloc'd
2.35 frystyk 334: string to be freed by the caller as when the anchor was created.
2.18 frystyk 335:
336: <PRE>
2.32 frystyk 337: extern char * HTAnchor_address (HTAnchor *me);
2.27 frystyk 338: </PRE>
339:
340: <H3>Cache Information</H3>
341:
2.35 frystyk 342: If the cache manager finds a cached object, it is registered in the
2.27 frystyk 343: anchor object. This way the <A HREF="HTFile.html">file loader</A>
344: knows that it is a MIME data object. The cache manager does not know
345: whether the data object is out of date (for example if a
346: <EM>Expires:</EM> header is in the MIME header. This is for the <A
347: HREF="HTMIME.html">MIME parser</A> to find out.
348:
349: <PRE>
2.32 frystyk 350: extern BOOL HTAnchor_cacheHit (HTParentAnchor *me);
351: extern void HTAnchor_setCacheHit (HTParentAnchor *me, BOOL cacheHit);
2.7 timbl 352: </PRE>
2.18 frystyk 353:
2.7 timbl 354: <H3>Physical address</H3>
1.1 timbl 355:
2.18 frystyk 356: Contains the physical address after we haved looked for proxies etc.
1.1 timbl 357:
2.18 frystyk 358: <PRE>
2.32 frystyk 359: extern char * HTAnchor_physical (HTParentAnchor * me);
2.18 frystyk 360:
2.32 frystyk 361: extern void HTAnchor_setPhysical (HTParentAnchor * me, char * protocol);
2.7 timbl 362: </PRE>
2.18 frystyk 363:
364: <H3>Is the Anchor searchable?</H3>
365:
366: <PRE>
2.32 frystyk 367: extern void HTAnchor_clearIndex (HTParentAnchor *me);
368: extern void HTAnchor_setIndex (HTParentAnchor *me);
369: extern BOOL HTAnchor_isIndex (HTParentAnchor *me);
2.18 frystyk 370: </PRE>
371:
372: <H3>Title handling</H3>
373:
374: We keep the title in the anchor as we then can refer to it later in
375: the history list etc. We can also obtain the title element if it is
376: passed as a HTTP header in the response. Any title element found in an
377: HTML document will overwrite a title given in a HTTP header.
378:
379: <PRE>
2.37 ! frystyk 380: extern const char * HTAnchor_title (HTParentAnchor *me);
2.18 frystyk 381:
2.32 frystyk 382: extern void HTAnchor_setTitle (HTParentAnchor *me,
2.37 ! frystyk 383: const char * title);
2.18 frystyk 384:
2.32 frystyk 385: extern void HTAnchor_appendTitle (HTParentAnchor *me,
2.37 ! frystyk 386: const char * title);
2.18 frystyk 387: </PRE>
388:
389: <H3>Media Types (Content-Type)</H3>
390:
391: <PRE>
2.32 frystyk 392: extern HTFormat HTAnchor_format (HTParentAnchor *me);
393: extern void HTAnchor_setFormat (HTParentAnchor *me,
394: HTFormat form);
2.18 frystyk 395: </PRE>
396:
397: <H3>Charset parameter to Content-Type</H3>
398:
399: <PRE>
2.32 frystyk 400: extern HTCharset HTAnchor_charset (HTParentAnchor *me);
401: extern void HTAnchor_setCharset (HTParentAnchor *me,
402: HTCharset charset);
2.18 frystyk 403: </PRE>
404:
2.21 frystyk 405: <H3>Level parameter to Content-Type</H3>
406:
407: <PRE>
2.32 frystyk 408: extern HTLevel HTAnchor_level (HTParentAnchor * me);
409: extern void HTAnchor_setLevel (HTParentAnchor * me,
410: HTLevel level);
2.22 frystyk 411: </PRE>
412:
413: <H3>Content Language</H3>
414:
415: <PRE>
2.32 frystyk 416: extern HTLanguage HTAnchor_language (HTParentAnchor *me);
417: extern void HTAnchor_setLanguage (HTParentAnchor *me,
418: HTLanguage language);
2.21 frystyk 419: </PRE>
420:
2.18 frystyk 421: <H3>Content Encoding</H3>
422:
423: <PRE>
2.32 frystyk 424: extern HTEncoding HTAnchor_encoding (HTParentAnchor *me);
425: extern void HTAnchor_setEncoding (HTParentAnchor *me,
426: HTEncoding encoding);
2.18 frystyk 427: </PRE>
428:
429: <H3>Content Transfer Encoding</H3>
430:
431: <PRE>
2.32 frystyk 432: extern HTCte HTAnchor_cte (HTParentAnchor *me);
433: extern void HTAnchor_setCte (HTParentAnchor *me,
434: HTCte cte);
2.18 frystyk 435: </PRE>
436:
437: <H3>Content Length</H3>
438:
439: <PRE>
2.32 frystyk 440: extern long int HTAnchor_length (HTParentAnchor *me);
441: extern void HTAnchor_setLength (HTParentAnchor *me,
442: long int length);
2.18 frystyk 443: </PRE>
444:
445: <H3>Allowed methods (Allow)</H3>
446:
447: <PRE>
2.36 frystyk 448: extern HTMethod HTAnchor_methods (HTParentAnchor * me);
449: extern void HTAnchor_setMethods (HTParentAnchor * me, HTMethod methodset);
450: extern void HTAnchor_appendMethods (HTParentAnchor * me, HTMethod methodset);
2.18 frystyk 451: </PRE>
452:
453: <H3>Version</H3>
454:
455: <PRE>
2.35 frystyk 456: extern char * HTAnchor_version (HTParentAnchor * me);
2.37 ! frystyk 457: extern void HTAnchor_setVersion (HTParentAnchor * me, const char * version);
2.28 frystyk 458: </PRE>
459:
460: <H3>Date</H3>
461:
462: Returns the date that was registered in the RFC822 header "Date"
463:
464: <PRE>
2.35 frystyk 465: extern time_t HTAnchor_date (HTParentAnchor * me);
2.37 ! frystyk 466: extern void HTAnchor_setDate (HTParentAnchor * me, const time_t date);
2.28 frystyk 467: </PRE>
468:
469: <H3>Last Modified Date</H3>
470:
471: Returns the date that was registered in the RFC822 header "Last-Modified"
472:
473: <PRE>
2.35 frystyk 474: extern time_t HTAnchor_lastModified (HTParentAnchor * me);
2.37 ! frystyk 475: extern void HTAnchor_setLastModified (HTParentAnchor * me, const time_t lm);
2.28 frystyk 476: </PRE>
477:
478: <H3>Expires Date</H3>
479:
480: <PRE>
2.35 frystyk 481: extern time_t HTAnchor_expires (HTParentAnchor * me);
2.37 ! frystyk 482: extern void HTAnchor_setExpires (HTParentAnchor * me, const time_t exp);
2.18 frystyk 483: </PRE>
484:
485: <H3>Derived from</H3>
486:
487: <PRE>
2.35 frystyk 488: extern char * HTAnchor_derived (HTParentAnchor *me);
2.37 ! frystyk 489: extern void HTAnchor_setDerived (HTParentAnchor *me, const char *derived_from);
2.18 frystyk 490: </PRE>
491:
492: <H3>Extra Headers</H3>
493:
494: List of unknown headers coming in from the network. Do not use the
495: <CODE>HTAnchor_addExtra()</CODE> function to extra headers here, but
2.30 frystyk 496: use the field in the <A HREF="HTReq.html#z1">request structure</A>
2.18 frystyk 497: for sending test headers.
498:
2.7 timbl 499: <PRE>
2.32 frystyk 500: extern HTList * HTAnchor_Extra (HTParentAnchor *me);
501: extern void HTAnchor_addExtra (HTParentAnchor *me,
2.37 ! frystyk 502: const char * header);
2.18 frystyk 503: </PRE>
504:
2.24 frystyk 505: <H3>Status of Header Parsing</H3>
2.18 frystyk 506:
507: These are primarily for internal use
1.1 timbl 508:
2.18 frystyk 509: <PRE>
2.32 frystyk 510: extern BOOL HTAnchor_headerParsed (HTParentAnchor *me);
511: extern void HTAnchor_setHeaderParsed (HTParentAnchor *me);
2.7 timbl 512: </PRE>
1.1 timbl 513:
2.18 frystyk 514: <H3>We want to clear the header information...</H3>
515:
516: <PRE>
2.32 frystyk 517: extern void HTAnchor_clearHeader (HTParentAnchor *me);
2.10 timbl 518:
2.18 frystyk 519: #endif /* HTANCHOR_H */
520: </PRE>
521: </BODY>
2.7 timbl 522: </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