Annotation of libwww/Library/src/HTAccess.html, revision 2.63
2.9 timbl 1: <HTML>
2: <HEAD>
2.45 frystyk 3: <TITLE>Access manager for libwww</TITLE>
2.63 ! frystyk 4: <!-- Changed by: Henrik Frystyk Nielsen, 12-Sep-1995 -->
2.19 timbl 5: <NEXTID N="z11">
2.9 timbl 6: </HEAD>
2.5 timbl 7: <BODY>
2.39 frystyk 8:
2.33 frystyk 9: <H1>Access Manager</H1>
2.39 frystyk 10:
2.41 frystyk 11: <PRE>
12: /*
2.50 frystyk 13: ** (c) COPYRIGHT MIT 1995.
2.41 frystyk 14: ** Please first read the full copyright statement in the file COPYRIGH.
15: */
16: </PRE>
17:
2.63 ! frystyk 18: This module is the application interface module to the access
! 19: manager. It contains help functions for accessing documents and for
! 20: uploading documents to a remote server.<P>
2.39 frystyk 21:
22: This module is implemented by <A HREF="HTAccess.c">HTAccess.c</A>, and
23: it is a part of the <A NAME="z10"
2.62 frystyk 24: HREF="http://www.w3.org/pub/WWW/Library/">
2.56 frystyk 25: W3C Reference Library</A>. <P>
2.39 frystyk 26:
2.33 frystyk 27: <PRE>
28: #ifndef HTACCESS_H
1.1 timbl 29: #define HTACCESS_H
2.44 roeber 30:
2.63 ! frystyk 31: #include "<A HREF="HTList.html">HTReq.h</A>"
2.52 frystyk 32: </PRE>
33:
34: <A NAME="Library"><H2>Initializing and Terminating the Library</H2></A>
35:
2.62 frystyk 36: <IMG SRC="http://www.w3.org/pub/WWW/Icons/32x32/warning.gif">
2.52 frystyk 37: These two functions initiates memory and settings for the Library and
38: cleans up memory kept by the Library when about to exit the
39: application. It is highly recommended that they are used!
40:
41: <PRE>
2.63 ! frystyk 42: extern BOOL HTLibInit (void);
! 43: extern BOOL HTLibTerminate (void);
2.52 frystyk 44: </PRE>
45:
46: <A NAME="Addresses"><H2>Default WWW Addresses</H2></A>
47:
48: These control the home page selection. To mess with these for normal browses
49: is asking for user confusion.
50: <PRE>
51: #define LOGICAL_DEFAULT "WWW_HOME" /* Defined to be the home page */
52:
53: #ifndef PERSONAL_DEFAULT
54: #define PERSONAL_DEFAULT "WWW/default.html" /* in home directory */
55: #endif
56:
57: /* If the home page isn't found, use this file: */
58: #ifndef LAST_RESORT
59: #define LAST_RESORT "http://www.w3.org/"
60: #endif
61:
62: /* If one telnets to an access point it will look in this file for home page */
63: #ifndef REMOTE_POINTER
64: #define REMOTE_POINTER "/etc/www-remote.url" /* can't be file */
65: #endif
66:
67: /* and if that fails it will use this. */
68: #ifndef REMOTE_ADDRESS
69: #define REMOTE_ADDRESS "http://www.w3.org/" /* can't be file */
70: #endif
71:
72: #ifndef LOCAL_DEFAULT_FILE
73: #define LOCAL_DEFAULT_FILE "/usr/local/lib/WWW/default.html"
74: #endif
75: </PRE>
76:
77: <A NAME="LoadDoc"><H2>Functions for Loading a Document</H2></A>
2.33 frystyk 78:
2.52 frystyk 79: There are several different ways of loading a document. However, the
80: major difference between them is whether the document is referenced by
2.33 frystyk 81:
2.52 frystyk 82: <UL>
83: <LI><A HREF="#Relative">Relative URI</A>
84: <LI><A HREF="#Absolute">Absolute URI</A>
85: <LI><A HREF="#Anchor">Anchor element</A> or
86: <LI>Contains keywords for <A HREF="#RelSearch">searching an relative URI</A>
87: <LI>Contains keywords for <A HREF="#AbsSearch">searching an absolute URI</A>
88: </UL>
2.33 frystyk 89:
2.52 frystyk 90: <B>NOTE:</B> From release 3.0 of the Library, the return codes from
91: the loading functions are no mode <CODE>BOOL</CODE>, that is
92: <CODE>YES</CODE> or <CODE>NO</CODE>. Insted they have been replaced
93: with the following set of return codes defined in the <A
94: HREF="HTUtils.html#ReturnCodes">Utility module</A>:
1.1 timbl 95:
2.52 frystyk 96: <DL>
97: <DT>HT_WOULD_BLOCK
98: <DD>An I/O operation would block
1.1 timbl 99:
2.52 frystyk 100: <DT>HT_ERROR
101: <DD>Error has occured
1.1 timbl 102:
2.52 frystyk 103: <DT>HT_LOADED
104: <DD>Success
2.23 frystyk 105:
2.52 frystyk 106: <DT>HT_NO_DATA
107: <DD>Success, but no document loaded. This might be the situation when a
108: telnet sesssion is started etc.
2.10 timbl 109:
2.52 frystyk 110: <DT>HT_RETRY
111: <DD>The remote server is down but will serve documents from the
112: calendar time indicated in HTRequest->retry_after.
2.51 frystyk 113:
2.52 frystyk 114: </DL>
2.51 frystyk 115:
2.52 frystyk 116: However, a general rule about the return codes is that <B>ERRORS</B>
117: have a <EM>negative</EM> value whereas <B>SUCCESS</B> has a
118: <EM>positive</EM> value. <P>
2.51 frystyk 119:
2.52 frystyk 120: There are also some functions to help the client getting started with
121: <A HREF="#ClientHelp">the first URI</A>.
2.51 frystyk 122:
2.52 frystyk 123: <A NAME="Relative"><H3>Load a document from relative URL</H3></A>
2.34 frystyk 124:
125: <PRE>
2.52 frystyk 126: extern int HTLoadRelative PARAMS((CONST char * relative_name,
127: HTParentAnchor* here,
128: HTRequest * request));
2.34 frystyk 129: </PRE>
130:
2.52 frystyk 131: <A NAME="Absolute"></A><H3>Load a document from absolute URL</H3>
2.39 frystyk 132:
133: <PRE>
2.52 frystyk 134: extern int HTLoadAbsolute PARAMS((CONST char * addr,
135: HTRequest * request));
2.39 frystyk 136: </PRE>
2.19 timbl 137:
2.52 frystyk 138: <H3>Load a document from absolute name to a stream</H3>
2.19 timbl 139:
2.39 frystyk 140: <PRE>
2.52 frystyk 141: extern int HTLoadToStream PARAMS((CONST char * addr,
142: BOOL filter,
143: HTRequest * request));
2.39 frystyk 144: </PRE>
145:
2.52 frystyk 146: <A NAME="Anchor"><H3>Load a document from anchor</H3></A>
2.46 frystyk 147:
2.52 frystyk 148: The anchor parameter may be a child anchor. The anchor in the request
149: is set to the parent anchor. The recursive function keeps the error
150: stack in the request structure so that no information is lost having
151: more than one call. See also <A HREF="#BindAnchor">HTBindAnchor()</A>.
2.39 frystyk 152:
153: <PRE>
2.52 frystyk 154: extern int HTLoadAnchor PARAMS((HTAnchor * a,
155: HTRequest * request));
156: extern int HTLoadAnchorRecursive PARAMS((HTAnchor * a,
157: HTRequest * request));
2.39 frystyk 158: </PRE>
159:
2.52 frystyk 160: <A NAME="RelSearch"><H3>Search Using Relative URL</H3></A>
161:
162: Performs a search on word given by the user. Adds the search words to
163: the end of the current address and attempts to open the new address.
2.51 frystyk 164:
165: <PRE>
2.52 frystyk 166: extern int HTSearch PARAMS((CONST char * keywords,
167: HTParentAnchor* here,
168: HTRequest * request));
2.46 frystyk 169: </PRE>
170:
2.52 frystyk 171: <A NAME="AbsSearch"><H3>Search using Absolute URL</H3></A>
172:
173: Performs a keyword search on word given by the user. Adds the keyword
174: to the end of the current address and attempts to open the new
175: address.
2.46 frystyk 176:
177: <PRE>
2.52 frystyk 178: extern int HTSearchAbsolute PARAMS((CONST char * keywords,
179: CONST char * indexname,
180: HTRequest * request));
2.46 frystyk 181: </PRE>
182:
2.52 frystyk 183: <A NAME="HomePage"><H3>Generate the Anchor for the Home Page</H3></A>
184:
185: As it involves file access, this should only be done once when the
186: program first runs. This is a default algorithm using the
187: <CODE>WWW_HOME</CODE> environment variable.
2.39 frystyk 188:
189: <PRE>
2.52 frystyk 190: extern HTParentAnchor * HTHomeAnchor NOPARAMS;
2.39 frystyk 191: </PRE>
192:
2.52 frystyk 193: <H3>Find Related Name</H3>
2.45 frystyk 194:
2.52 frystyk 195: Creates a local file URI that can be used as a relative name when
196: calling HTParse() to expand a relative file name to an absolute
197: one. <P>
2.45 frystyk 198:
2.52 frystyk 199: The code for this routine originates from the Line Mode Browser and
2.53 frystyk 200: was moved here by <EM>howcome@w3.org</EM> in order for all
2.52 frystyk 201: clients to take advantage.<P>
2.39 frystyk 202:
2.47 frystyk 203: <PRE>
2.52 frystyk 204: extern char * HTFindRelatedName NOPARAMS;
2.47 frystyk 205: </PRE>
206:
2.52 frystyk 207: <A NAME="PostDoc"><H2>Functions for Posting a Document</H2></A>
208:
209: <B>NOTE:</B> The Posting functions are used to send a data object
210: along with the request. The functions have the same set of return
211: codes as for the <A HREF="#LoadDoc">Load Functions</A>.
2.47 frystyk 212:
2.52 frystyk 213: <H3>Get a Save Stream</H3>
2.46 frystyk 214:
215: <PRE>
2.52 frystyk 216: extern HTStream * HTSaveStream PARAMS((HTRequest * request));
2.46 frystyk 217: </PRE>
218:
2.52 frystyk 219: <H3>Copy an Anchor</H3>
220:
221: Fetch the URL (possibly local file URL) and send it using either
222: <B>PUT</B> or <B>POST</B> directly to the remote destination using
223: HTTP, that is remote copy of object <EM>O</EM> from <EM>A</EM> to
224: <EM>B</EM> where <EM>A</EM> might be the host of the application. The
225: caller can decide the exact method used and which HTTP header fields
226: to transmit by setting the user fields in the destination request
227: structure.
2.46 frystyk 228:
229: <PRE>
2.52 frystyk 230: extern int HTCopyAnchor PARAMS((HTAnchor * src_anchor,
231: HTRequest * dest_req));
2.39 frystyk 232: </PRE>
233:
2.46 frystyk 234:
2.52 frystyk 235: <H3>Upload an Anchor</H3>
2.39 frystyk 236:
2.52 frystyk 237: Send the contents (in hyperdoc) of the source anchor using either
238: <B>PUT</B> or <B>POST</B> to the remote destination using HTTP. The
239: caller can decide the exact method used and which HTTP header fields
240: to transmit by setting the user fields in the request structure.
241: <EM>Format conversion</EM> can be made on the fly by setting the <A
242: HREF="#input_format">input_format field</A> in the destination request
243: structure. If the content-length is unknown (-1) then a <A
244: HREF="HTConLen.html">content-length counter</A> is automaticly put
245: into the stream pipe.
2.43 frystyk 246:
247:
248: <PRE>
2.52 frystyk 249: extern int HTUploadAnchor PARAMS((HTAnchor * src_anchor,
250: HTParentAnchor *dest_anchor,
251: HTRequest * dest_req));
2.46 frystyk 252: </PRE>
253:
2.25 luotonen 254: <PRE>
2.63 ! frystyk 255: #endif /* HTACCESS_H */
2.38 howcome 256: </PRE>
257:
2.52 frystyk 258: End of Declaration
2.25 luotonen 259: </BODY>
2.9 timbl 260: </HTML>
Webmaster
![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to HTAccess.html CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [Public] / libwww / Library / src