Annotation of libwww/Library/src/HTLink.html, revision 2.6
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>
! 39: <pre>#ifndef HTLINK_H
2.1 frystyk 40: #define HTLINK_H
41:
2.6 ! frystyk 42: typedef struct _HTLink HTLink;
2.1 frystyk 43:
44: #include "WWWUtil.h"
45: #include "HTMethod.h"
2.6 ! frystyk 46: #include "HTAnchor.h"</pre>
! 47:
! 48: <h2>Creation and Deletion Methods</h2>
! 49:
! 50: <p>These are the methods for crating and deleting new link objects</p>
! 51:
! 52: <h3>Create a new Link Object</h3>
! 53: <pre>typedef HTAtom * HTLinkType;
2.1 frystyk 54:
55: typedef enum _HTLinkResult {
56: HT_LINK_INVALID = -1,
57: HT_LINK_NONE = 0,
58: HT_LINK_ERROR,
59: HT_LINK_OK
60: } HTLinkResult;
61:
62: struct _HTLink {
2.6 ! frystyk 63: HTAnchor * dest; /* The anchor to which this leads */
! 64: HTLinkType type; /* Semantics of this link */
! 65: HTMethod method; /* Method for this link, e.g. PUT */
! 66: HTLinkResult result; /* Result of any attempt to get this link */
2.1 frystyk 67: };
68:
2.6 ! frystyk 69: HTLink * HTLink_new (void);</pre>
! 70:
! 71: <h3>Delete a Link Object</h3>
! 72:
! 73: <p>A link can be removed as any other object</p>
! 74: <pre>BOOL HTLink_delete (HTLink * link);</pre>
! 75:
! 76: <h3>Remove All Link Information from an Anchor</h3>
! 77:
! 78: <p>This is normally a part of deleting anchor objects.</p>
! 79: <pre>extern BOOL HTLink_removeAll (HTAnchor * me);</pre>
! 80:
! 81: <h2>Predefined Link Types</h2>
! 82:
! 83: <p>Just for ease of use, we define a seet of commonly used link types. You can
! 84: ofcourse use any other link type you want.</p>
! 85: <pre>#define HT_LR_PERM_REDIRECT HTAtom_for("PERMANENT_REDIRECTION")
! 86: #define HT_LR_TEMP_REDIRECT HTAtom_for("TEMPORARY_REDIRECTION")
! 87: #define HT_LR_SEE_OTHER HTAtom_for("SEE_OTHER")</pre>
! 88:
! 89: <h2>Handle Link Between Anchors</h2>
! 90:
! 91: <p>As mentioned, link objects are the ones that bind anchor objects together
! 92: in a Web like structure</p>
! 93:
! 94: <h3>Add a Link between two Anchors</h3>
! 95:
! 96: <p>This method creates a new link between two <a href="HTAnchor.html">anchor
! 97: objects</a>.</p>
! 98: <pre>extern BOOL HTLink_add (
! 99: HTAnchor * source,
! 100: HTAnchor * destination,
! 101: HTLinkType type,
! 102: HTMethod method);</pre>
! 103:
! 104: <h3>Remove All Links Between two Anchors</h3>
! 105:
! 106: <p>Removes link information from one anchor to another.</p>
! 107: <pre>extern BOOL HTLink_remove (
! 108: HTAnchor * source,
! 109: HTAnchor * destination);</pre>
! 110:
! 111: <h3>Find a Link</h3>
! 112:
! 113: <p>Find the anchor object between a destination and a source ancher. Return
! 114: link object if any, else NULL</p>
! 115: <pre>extern HTLink * HTLink_find (HTAnchor * source, HTAnchor * destination);</pre>
! 116:
! 117: <h3>Find a Link with a given link type</h3>
! 118:
! 119: <p>Returns a link with a given link type or NULL if nothing found</p>
! 120: <pre>extern HTLink * HTLink_findType (HTAnchor * me, HTLinkType type);</pre>
! 121:
! 122: <h2>Link Information</h2>
! 123:
! 124: <p>This is the set of methods for accessing the information carried by a link
! 125: object</p>
! 126:
! 127: <h3>Link Destination</h3>
! 128:
! 129: <p>The link destination is the destination anchor pointed to by the link.</p>
! 130: <pre>extern BOOL HTLink_setDestination (HTLink * link, HTAnchor * dest);
! 131: extern HTAnchor * HTLink_destination (HTLink * link);</pre>
! 132:
! 133: <h3>Link Types and Semantic Links</h3>
! 134:
! 135: <p>Each link has a sematic representation associated with it. This means that
2.1 frystyk 136: the application can distinguish between pages based on the semantics of the
2.6 ! frystyk 137: link. This is very similar to the <code>LINK</code> tag in HTML pages which
! 138: indicates the meaning if this pages to other pages.</p>
! 139: <pre>extern BOOL HTLink_setType (HTLink * link, HTLinkType type);
! 140: extern HTLinkType HTLink_type (HTLink * link);</pre>
! 141:
! 142: <h3>Link Method</h3>
! 143:
! 144: <p>The link method is the HTTP method we have performed between the two links.
! 145: For example, it can be a POST operation, or a PUT operation where the
! 146: operation on the first anchor created a new anchor.</p>
! 147: <pre>extern BOOL HTLink_setMethod (HTLink * link, HTMethod method);
! 148: extern HTMethod HTLink_method (HTLink * link);</pre>
! 149:
! 150: <h3>Link Result</h3>
! 151:
! 152: <p>When a link has been used for posting an object from a source to a
! 153: destination link, the result of the operation is stored as part of the link
! 154: information. This means that we can keep track of which operations we have
! 155: performed on a link and hence the application can ask the user whether he or
! 156: she wants to do a re-post, for example.</p>
! 157: <pre>extern BOOL HTLink_setResult (HTLink * link, HTLinkResult result);
! 158: extern HTLinkResult HTLink_result (HTLink * link);</pre>
! 159: <pre>#endif /* HTLINK_H */</pre>
! 160:
! 161: <p></p>
! 162: <hr>
! 163:
! 164: <address>
! 165: @(#) $Id: HTLink.html,v 2.5 1999/03/08 16:53:40 frystyk Exp $ </address>
! 166: </body>
! 167: </html>
Webmaster