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