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