Annotation of libwww/Library/src/HTAccess.html, revision 2.75
2.9 timbl 1: <HTML>
2: <HEAD>
2.74 frystyk 3: <TITLE>W3C Reference Library libwww access methods</TITLE>
2.75 ! frystyk 4: <!-- Changed by: Henrik Frystyk Nielsen, 23-Mar-1996 -->
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.64 frystyk 18: This module is the application interface module to the <A
19: HREF="HTReq.html">Request Manager</A>. You can use the Request Manager
20: directly but this module makes it easier to use by providing a lot of
21: small request functions using the Request Manager in different
22: ways. It contains help functions for accessing documents and for
2.63 frystyk 23: uploading documents to a remote server.<P>
2.39 frystyk 24:
25: This module is implemented by <A HREF="HTAccess.c">HTAccess.c</A>, and
2.64 frystyk 26: it is a part of the <A HREF="http://www.w3.org/pub/WWW/Library/"> W3C
27: Reference Library</A>. <P>
2.39 frystyk 28:
2.33 frystyk 29: <PRE>
30: #ifndef HTACCESS_H
1.1 timbl 31: #define HTACCESS_H
2.44 roeber 32:
2.64 frystyk 33: #include "HTReq.h"
34: #include "HTAnchor.h"
2.52 frystyk 35: </PRE>
36:
2.68 frystyk 37: <A NAME="Library"><H2>Generic Library Functions</H2></A>
38:
39: These are functions that affect the overall behavior of the Library.
40:
41: <H3><IMG SRC="../../Icons/32x32/warning.gif"> Initializing and
42: Terminating the Library</H3>
2.52 frystyk 43:
44: These two functions initiates memory and settings for the Library and
45: cleans up memory kept by the Library when about to exit the
2.65 frystyk 46: application. They <B>must</B> be used!
2.52 frystyk 47:
48: <PRE>
2.73 frystyk 49: extern BOOL HTLibInit (const char * AppName, const char * AppVersion);
2.63 frystyk 50: extern BOOL HTLibTerminate (void);
2.65 frystyk 51: </PRE>
52:
2.68 frystyk 53: <H3>Library Name and Version</H3>
2.66 frystyk 54:
55: You can get the generic name of the Library and the version by using
56: the following functions:
57:
58: <PRE>
2.73 frystyk 59: extern const char * HTLib_name (void);
60: extern const char * HTLib_version (void);
2.66 frystyk 61: </PRE>
62:
2.68 frystyk 63: <H3>Application Name and Version</H3>
2.65 frystyk 64:
65: Returns the name of the application and the version number that was
66: passed to the <CODE>HTLibInit()</CODE> function.
67:
68: <PRE>
2.73 frystyk 69: extern const char * HTLib_appName (void);
70: extern const char * HTLib_appVersion (void);
2.52 frystyk 71: </PRE>
72:
2.68 frystyk 73: <H3>Accessing the Local File System</H3>
2.64 frystyk 74:
2.66 frystyk 75: The Library does normally use the local file system for dumping
76: unknown data objects, file cache etc. In some situations this is not
77: desired and we can therefore turn it off. This mode also prevents you
78: from being able to access other resources where you have to log in, fr
79: example telnet.
2.64 frystyk 80:
81: <PRE>
2.66 frystyk 82: extern BOOL HTLib_secure (void);
83: extern void HTLib_setSecure (BOOL mode);
2.52 frystyk 84: </PRE>
85:
2.68 frystyk 86: <A NAME="LoadDoc"><H2>LOAD Request Methods</H2></A>
2.33 frystyk 87:
2.64 frystyk 88: <H3>Request a document from absolute name</H3>
2.33 frystyk 89:
2.64 frystyk 90: Request a document referencd by an absolute URL. Returns YES if
91: request accepted, else NO
2.33 frystyk 92:
2.64 frystyk 93: <PRE>
2.73 frystyk 94: extern BOOL HTLoadAbsolute (const char * url, HTRequest* request);
2.64 frystyk 95: </PRE>
2.51 frystyk 96:
2.64 frystyk 97: <H3>Request a document from absolute name to stream</H3>
2.51 frystyk 98:
2.64 frystyk 99: Request a document referencd by an absolute URL and sending the data
100: down a stream. This is _excactly_ the same as HTLoadAbsolute as the
101: ourputstream is specified using the function.
102: HTRequest_setOutputStream(). 'filter' is ignored! Returns YES if
103: request accepted, else NO
2.34 frystyk 104:
105: <PRE>
2.73 frystyk 106: extern BOOL HTLoadToStream (const char * url, BOOL filter, HTRequest *request);
2.34 frystyk 107: </PRE>
108:
2.64 frystyk 109: <H3>Request a document from relative name</H3>
2.39 frystyk 110:
2.64 frystyk 111: Request a document referenced by a relative URL. The relative URL is
112: made absolute by resolving it relative to the address of the 'base'
113: anchor. Returns YES if request accepted, else NO
2.19 timbl 114:
2.39 frystyk 115: <PRE>
2.73 frystyk 116: extern BOOL HTLoadRelative (const char * relative,
2.64 frystyk 117: HTParentAnchor * base,
118: HTRequest * request);
2.39 frystyk 119: </PRE>
120:
2.64 frystyk 121: <H3>Request an anchor</H3>
2.46 frystyk 122:
2.64 frystyk 123: Request the document referenced by the anchor Returns YES if request
124: accepted, else NO
2.39 frystyk 125:
126: <PRE>
2.64 frystyk 127: extern BOOL HTLoadAnchor (HTAnchor * anchor, HTRequest * request);
2.39 frystyk 128: </PRE>
129:
2.64 frystyk 130: <H3>Request an anchor</H3>
2.52 frystyk 131:
2.64 frystyk 132: Same as HTLoadAnchor but any information in the Error Stack in the
133: request object is kept, so that any error messages in one This
134: function is almost identical to HTLoadAnchor, but it doesn't clear the
135: error stack so that the information in there is kept. Returns YES if
136: request accepted, else NO
2.51 frystyk 137:
138: <PRE>
2.64 frystyk 139: extern BOOL HTLoadAnchorRecursive (HTAnchor * anchor, HTRequest * request);
2.46 frystyk 140: </PRE>
141:
2.64 frystyk 142: <H3>Search an Anchor</H3>
2.52 frystyk 143:
144: Performs a keyword search on word given by the user. Adds the keyword
145: to the end of the current address and attempts to open the new
2.64 frystyk 146: address. The list of keywords must be a space-separated list and
147: spaces will be converted to '+' before the request is issued. Search
148: can also be performed by HTLoadAbsolute() etc. Returns YES if request
149: accepted, else NO
2.46 frystyk 150:
151: <PRE>
2.73 frystyk 152: extern BOOL HTSearch (const char * keywords,
2.64 frystyk 153: HTParentAnchor * base,
154: HTRequest * request);
2.46 frystyk 155: </PRE>
156:
2.64 frystyk 157: <H3>Search a document from absolute name</H3>
2.52 frystyk 158:
2.64 frystyk 159: Request a document referencd by an absolute URL appended with the
160: keywords given. The URL can NOT contain any fragment identifier! The
161: list of keywords must be a space-separated list and spaces will be
162: converted to '+' before the request is issued. Returns YES if request
163: accepted, else NO
2.39 frystyk 164:
165: <PRE>
2.73 frystyk 166: extern BOOL HTSearchAbsolute (const char * keywords,
167: const char * url,
2.64 frystyk 168: HTRequest * request);
2.39 frystyk 169: </PRE>
170:
2.68 frystyk 171: <A NAME="PostDoc"><H2>POST Request Methods</H2></A>
172:
2.64 frystyk 173: <H3>Copy an anchor</H3>
2.45 frystyk 174:
2.71 frystyk 175: Fetch the URL from either local file store <B>or</B> from a remote
176: HTTP server and send it using either PUT or POST to the remote
177: destination using HTTP. The caller can decide the exact method used
178: and which HTTP header fields to transmit by setting the user fields in
179: the request structure. If posting to NNTP then we can't dispatch at
180: this level but must pass the source anchor to the news module that
181: then takes all the refs to NNTP and puts into the "newsgroups" header
2.64 frystyk 182: Returns YES if request accepted, else NO
2.39 frystyk 183:
2.47 frystyk 184: <PRE>
2.64 frystyk 185: extern BOOL HTCopyAnchor (HTAnchor * src_anchor, HTRequest * main_req);
2.47 frystyk 186: </PRE>
187:
2.52 frystyk 188: <H3>Upload an Anchor</H3>
2.39 frystyk 189:
2.71 frystyk 190: This function can be used to send data along with a request to a
191: remote server. It can for example be used to POST form data to a
192: remote HTTP server - or it can be used to post a newsletter to a NNTP
193: server. In either case, you pass a callback function which the request
194: calls when the remote destination is ready to accept data. In this
195: callback you get the current request object and a stream into where
196: you can write data. It is very important that you return the value
197: returned by this stream to the Library so that it knows what to do
198: next. The reason is that the outgoing stream might block or an error
199: may occur and in that case the Library must know about it. If you do
200: not want to handle the stream interface yourself then you can use the
201: <CODE>HTUpload_callback</CODE> which is declared below.<P>
202:
203: The source anchor represents the data object in memory and it points
204: to the destination anchor by using the <A
205: HREF="../User/Architecture/PostWeb.html">POSTWeb method</A>. The
206: source anchor contains metainformation about the data object in memory
207: and the destination anchor represents the reponse from the remote
208: server. Returns YES if request accepted, else NO
209:
210: <PRE>
211: extern BOOL HTUploadAnchor (HTAnchor * source_anchor,
212: HTRequest * request,
213: HTPostCallback * callback);
214: </PRE>
215:
216: <H3>POST Callback Handler</H3>
217:
218: Is you do not want to handle the stream interface on your own, you can
219: use this "middleman" function which does the actual writing to the
220: target stream for the anchor upload and also handles the return value
221: from the stream. Now, your application is called via the callback
222: function that you may associate with a request object. You indicate
223: when you have sent all the data you want by returning HT_LOADED from
224: the callback.
2.43 frystyk 225:
226: <PRE>
2.72 frystyk 227: extern int HTUpload_callback (HTRequest * request, HTStream * target);
2.46 frystyk 228: </PRE>
229:
2.25 luotonen 230: <PRE>
2.63 frystyk 231: #endif /* HTACCESS_H */
2.38 howcome 232: </PRE>
233:
2.75 ! frystyk 234: <HR>
! 235: <ADDRESS>
! 236: @(#) $Id: Date Author State $
! 237: </ADDRESS>
2.25 luotonen 238: </BODY>
2.9 timbl 239: </HTML>
Webmaster