Annotation of libwww/Library/src/HTLink.html, revision 2.7
2.6 frystyk 1: <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"
2: "http://www.w3.org/TR/REC-html40/loose.dtd">
3: <html>
4: <head>
5:
6: <!-- Changed by: Henrik Frystyk Nielsen, 30-Jun-1996 -->
7: <title>W3C Sample Code Library libwww Link Class</title>
8: </head>
9: <body>
10:
11: <h1>The Link Class</h1>
12: <pre>/*
13: ** (c) COPYRIGHT MIT 1995.
14: ** Please first read the full copyright statement in the file COPYRIGH.
15: */</pre>
16:
17: <p>The <a href="HTLink.html">HTLink class</a> represents links between <a
18: href="HTAnchor.html">anchor objects</a>. By keeping the link as a object and
19: not as part of the anchor we are capable of handling link semantics in a much
20: more organized way. For example, we can then search for link types among all
21: the link objects that we have created. <a href="HTAnchor.html">Anchor
22: objects</a> are bound together using Link objects. Each anchor can be the
23: source or destination of zero, one, or more links from and to other
24: anchors.</p>
25:
26: <p>Link information can come from many places - two classic examples are the
27: HTML <code>LINK</code> element and the HTTP <code>Link</code> header field.
28: Libwww supports both - the HTML <code>LINK</code> element is handled by the <a
29: href="HTML.html">HTML parser</a> and the HTTP <code>Link</code> header field
30: is handled by the <a href="HTMIMImp.html">MIME parser</a>.</p>
31:
32: <p>The <a href="/Robot/">Webbot</a> uses the link class to maintain the
33: information of the Web that it is seeing when traversing the Web as a
34: robot.</p>
35:
36: <p>This module is implemented by <a href="HTLink.c">HTLink.c</a>, and it is a
37: part of the <a href="http://www.w3.org/Library/"> W3C Sample Code
38: Library</a>.</p>
2.7 ! vbancrof 39: <pre>
! 40: #ifndef HTLINK_H
2.1 frystyk 41: #define HTLINK_H
42:
2.7 ! vbancrof 43: #ifdef __cplusplus
! 44: extern "C" {
! 45: #endif
! 46:
2.6 frystyk 47: typedef struct _HTLink HTLink;
2.1 frystyk 48:
49: #include "WWWUtil.h"
50: #include "HTMethod.h"
2.6 frystyk 51: #include "HTAnchor.h"</pre>
52:
53: <h2>Creation and Deletion Methods</h2>
54:
55: <p>These are the methods for crating and deleting new link objects</p>
56:
57: <h3>Create a new Link Object</h3>
58: <pre>typedef HTAtom * HTLinkType;
2.1 frystyk 59:
60: typedef enum _HTLinkResult {
61: HT_LINK_INVALID = -1,
62: HT_LINK_NONE = 0,
63: HT_LINK_ERROR,
64: HT_LINK_OK
65: } HTLinkResult;
66:
67: struct _HTLink {
2.6 frystyk 68: HTAnchor * dest; /* The anchor to which this leads */
69: HTLinkType type; /* Semantics of this link */
70: HTMethod method; /* Method for this link, e.g. PUT */
71: HTLinkResult result; /* Result of any attempt to get this link */
2.1 frystyk 72: };
73:
2.6 frystyk 74: HTLink * HTLink_new (void);</pre>
75:
76: <h3>Delete a Link Object</h3>
77:
78: <p>A link can be removed as any other object</p>
79: <pre>BOOL HTLink_delete (HTLink * link);</pre>
80:
81: <h3>Remove All Link Information from an Anchor</h3>
82:
83: <p>This is normally a part of deleting anchor objects.</p>
84: <pre>extern BOOL HTLink_removeAll (HTAnchor * me);</pre>
85:
86: <h2>Predefined Link Types</h2>
87:
88: <p>Just for ease of use, we define a seet of commonly used link types. You can
89: ofcourse use any other link type you want.</p>
90: <pre>#define HT_LR_PERM_REDIRECT HTAtom_for("PERMANENT_REDIRECTION")
91: #define HT_LR_TEMP_REDIRECT HTAtom_for("TEMPORARY_REDIRECTION")
92: #define HT_LR_SEE_OTHER HTAtom_for("SEE_OTHER")</pre>
93:
94: <h2>Handle Link Between Anchors</h2>
95:
96: <p>As mentioned, link objects are the ones that bind anchor objects together
97: in a Web like structure</p>
98:
99: <h3>Add a Link between two Anchors</h3>
100:
101: <p>This method creates a new link between two <a href="HTAnchor.html">anchor
102: objects</a>.</p>
103: <pre>extern BOOL HTLink_add (
104: HTAnchor * source,
105: HTAnchor * destination,
106: HTLinkType type,
107: HTMethod method);</pre>
108:
109: <h3>Remove All Links Between two Anchors</h3>
110:
111: <p>Removes link information from one anchor to another.</p>
112: <pre>extern BOOL HTLink_remove (
113: HTAnchor * source,
114: HTAnchor * destination);</pre>
115:
116: <h3>Find a Link</h3>
117:
118: <p>Find the anchor object between a destination and a source ancher. Return
119: link object if any, else NULL</p>
120: <pre>extern HTLink * HTLink_find (HTAnchor * source, HTAnchor * destination);</pre>
121:
122: <h3>Find a Link with a given link type</h3>
123:
124: <p>Returns a link with a given link type or NULL if nothing found</p>
125: <pre>extern HTLink * HTLink_findType (HTAnchor * me, HTLinkType type);</pre>
126:
127: <h2>Link Information</h2>
128:
129: <p>This is the set of methods for accessing the information carried by a link
130: object</p>
131:
132: <h3>Link Destination</h3>
133:
134: <p>The link destination is the destination anchor pointed to by the link.</p>
135: <pre>extern BOOL HTLink_setDestination (HTLink * link, HTAnchor * dest);
136: extern HTAnchor * HTLink_destination (HTLink * link);</pre>
137:
138: <h3>Link Types and Semantic Links</h3>
139:
140: <p>Each link has a sematic representation associated with it. This means that
2.1 frystyk 141: the application can distinguish between pages based on the semantics of the
2.6 frystyk 142: link. This is very similar to the <code>LINK</code> tag in HTML pages which
143: indicates the meaning if this pages to other pages.</p>
144: <pre>extern BOOL HTLink_setType (HTLink * link, HTLinkType type);
145: extern HTLinkType HTLink_type (HTLink * link);</pre>
146:
147: <h3>Link Method</h3>
148:
149: <p>The link method is the HTTP method we have performed between the two links.
150: For example, it can be a POST operation, or a PUT operation where the
151: operation on the first anchor created a new anchor.</p>
152: <pre>extern BOOL HTLink_setMethod (HTLink * link, HTMethod method);
153: extern HTMethod HTLink_method (HTLink * link);</pre>
154:
155: <h3>Link Result</h3>
156:
157: <p>When a link has been used for posting an object from a source to a
158: destination link, the result of the operation is stored as part of the link
159: information. This means that we can keep track of which operations we have
160: performed on a link and hence the application can ask the user whether he or
161: she wants to do a re-post, for example.</p>
162: <pre>extern BOOL HTLink_setResult (HTLink * link, HTLinkResult result);
163: extern HTLinkResult HTLink_result (HTLink * link);</pre>
2.7 ! vbancrof 164: <pre>
! 165: #ifdef __cplusplus
! 166: }
! 167: #endif
! 168:
! 169: #endif /* HTLINK_H */
! 170: </pre>
2.6 frystyk 171:
172: <p></p>
173: <hr>
174:
175: <address>
2.7 ! vbancrof 176: @(#) $Id: HTLink.html,v 2.6 1999/03/29 15:51:44 frystyk Exp $ </address>
2.6 frystyk 177: </body>
178: </html>
Webmaster