/*    					W3C Sample Code Library libwww Anchor Class!  The Anchor Class!*//***	(c) COPYRIGHT MIT 1995.**	Please first read the full copyright statement in the file COPYRIGH.*//*An anchor represents a region of a hypertext document which is linked toanother anchor in the same or a different document. Another name for anchorswould be URLs as an anchor represents all we know about a URL - includingwhere it points to and who points to it. Because the anchor objectsrepresent the part of the Web, the application has been in touch, it is oftenuseful to maintain the anchors throughout the lifetime of the application.It would actually be most useful if we had persistent anchors so that anapplication could build up a higher knowledge about the Web topology..When to Escape and Unescape Addresses.The URI escape policy in libwww is that all URIs created asanchors must already have been escaped. The reason for this is that ifURIs are not escaped then the URI parser is not guaranteed to work asexpected. Imagine, for example, that you have a ":" in ahost name, then you could get something like this:http://my:host:8000/ instead of http://my%3Ahost:8000/.Libwww provides support for escaping and unescapingURIs using this set of APIs.This module is implemented by HTAnchor.c, and itis a part of the  W3C Sample CodeLibrary.*/#ifndef HTANCHOR_H#define HTANCHOR_H/*.  Types defined and used by the Anchor Object.This is a set of videly used type definitions used through out the Library:*/#include "WWWUtil.h"typedef HTAtom * HTFormat;typedef HTAtom * HTLevel;		       /* Used to specify HTML level */typedef HTAtom * HTEncoding;				    /* C-E and C-T-E */typedef HTAtom * HTCharset;typedef HTAtom * HTLanguage;typedef struct _HTAnchor	HTAnchor;typedef struct _HTParentAnchor	HTParentAnchor;typedef struct _HTChildAnchor	HTChildAnchor;#include "HTLink.h"#include "HTMethod.h"#include "HTResponse.h"/*.  The Anchor Class.We have three variants of the Anchor object - I guess some would call themsuperclass and subclasses ;-) (  Anchor Base Class)This is the super class of anchors. We often use this as an argument to thefunctions that both accept parent anchors and child anchors. We separatethe first link from the others to avoid too many small mallocs involved bya list creation. Most anchors only point to one place. (  Anchor for a Parent Object)These anchors points to the whole contents of any resource accesible by aURI. The parent anchor now contains all known metainformation about thatobject and in some cases the parent anchor also contains the document itself.Often we get the metainformation about a document via the entity headersin the HTTP specification.(  Anchor for a Child Object)A child anchor is a anchor object that points to a subpart of a hypertextdocument. In HTML this is represented by the NAME tag of theAnchor element.After we have defined the data structures we must define the methods thatcan be used on them. All anchors are kept in an internal hash table so thatthey are easier to find again.(  Find/Create a Parent Anchor)This one is for a reference (link) which is found in a document, and mightnot be already loaded. The parent anchor returned can either be created onthe spot or is already in the hash table.*/extern HTAnchor * HTAnchor_findAddress		(const char * address);/*(  Find/Create a Child Anchor)This one is for a new child anchor being edited into an existing document.The parent anchor must already exist but the child returned can either becreated on the spot or is already in the hash table. The tag isthe part that's after the '#' sign in a URI.*/extern HTChildAnchor * HTAnchor_findChild	(HTParentAnchor *parent,						 const char *	tag);/*(  Find/Create a Child Anchor and Link to Another Parent)Find a child anchor anchor with a given parent and possibly a tag,and (if passed) link this child to the URI given in the href. Aswe really want typed links to the caller should also indicate what the typeof the link is (see HTTP spec for more information). The link isrelative to the address of the parent anchor.*/extern HTChildAnchor * HTAnchor_findChildAndLink (		HTParentAnchor * parent,		/* May not be 0 */		const char * tag,			/* May be "" or 0 */		const char * href,			/* May be "" or 0 */		HTLinkType ltype);			/* May be 0 *//*(  Delete an Anchor)All outgoing links from parent and children are deleted, and this anchoris removed from the sources list of all its targets. We also delete the targets.If this anchor's source list is empty, we delete it and its children.*/extern BOOL HTAnchor_delete	(HTParentAnchor *me);/*(  Clear all Anchors)Deletes all the metadata associated with anchors but doesn't deletethe anchor link structure itself. This is much safer than deleting thecomplete anchor structure as this represents the complete Web theapplication has been in touch with. It also returns a list of all theobjects (hyperdoc) hanging of the parent anchors found while doingit. These are not deleted by libwww.*/extern BOOL HTAnchor_clearAll (HTList * documents);/*(  Delete all Anchors)Deletes all anchors and return a list of all the objects (hyperdoc)hanging of the parent anchors found while doing it. The application may keepits own list of HyperDocs, but this function returns it anyway.It is always for the application to delete anyHyperDocs. If NULL then no hyperdocs are returned. Return YESif OK, else NO.Note: This function is different from cleaning up the history list!*/extern BOOL HTAnchor_deleteAll	(HTList * objects);/*(  Flatten all anchors into Array)Flattens the anchor web structure into an array.  This is useful forcalculating statistics, sorting the parent anchors etc.The caller can indicate the size of the array (total number of anchorsif known - otherwise 0).Return an array that must be freed by the caller or NULL if noanchors.*/extern HTArray * HTAnchor_getArray (int growby);/*.  Links and Anchors.Anchor objects are bound together by Link objectsthat carry information about what type of link and whetther we have followedthe link etc. Any anchor object can have zero, one, or many links but thenormal case is one. Therefore we treat this is a special way.(  Handling the Main Link)Any outgoing link can at any time be the main destination.*/extern BOOL HTAnchor_setMainLink	(HTAnchor * anchor, HTLink * link);extern HTLink * HTAnchor_mainLink	(HTAnchor * anchor);extern HTAnchor * HTAnchor_followMainLink (HTAnchor * anchor);/*(  Handling the Sub Links)*/extern BOOL HTAnchor_setSubLinks	(HTAnchor * anchor, HTList * list);extern HTList * HTAnchor_subLinks	(HTAnchor * anchor);/*(  Search for a Link Type)Links can have relations (indicated by the "rel" or "rev" HTML linkattributes).  This function can search an anchor looking for aspecific type, for example "stylesheet".*/extern HTLink * HTAnchor_findLinkType (HTAnchor * me, HTLinkType type);/*.  Relations Between Children and Parents.As always, children and parents have a compliated relationship and the libwwwAnchor class is no exception.(  Who is Parent?)For parent anchors this returns the anchor itself*/extern HTParentAnchor * HTAnchor_parent	(HTAnchor *me);/*(  Does it have any Anchors within it?)Does this parent anchor have any children*/extern BOOL HTAnchor_hasChildren	(HTParentAnchor *me);/*(  Is this anchor a Child?)*/extern BOOL HTAnchor_isChild (HTAnchor * me);/*(  Get the Tag/Fragment/View of this anchor)If this is a child anchor then it has a tag (often also called a "fragment"), whichis essentially a specific view of a document. This is why I like to call ita view instead of a fragment. The string returned (if non-NULL) must be freed by thecaller.*/extern char * HTAnchor_view (HTAnchor * me);/*.  Anchor Addresses.There are two addresses of an anchor. The URI that was passed when the anchorwas crated and the physical address that's used when the URI is going tobe requested. The two addresses may be different if the request is goingthrough a proxy or a gateway or it may have been mapped through a rule file.(  Logical Address)Returns the full URI of the anchor, child or parent as a malloc'd stringto be freed by the caller as when the anchor was created.*/extern char * HTAnchor_address		(HTAnchor * me);/*(  Expanded Logical Address)When expanding URLs within a hypertext document, the base address is takenas the following value if present (in that order):	 	   o 	     Content-Base header  o 	     Content-Location header  o 	     Logical address	 	 */extern char * HTAnchor_expandedAddress  (HTAnchor * me);/*(  Physical address)