Annotation of libwww/Library/src/HTAccess.html, revision 2.78
2.9 timbl 1: <HTML>
2: <HEAD>
2.78 ! frystyk 3: <!-- Changed by: Henrik Frystyk Nielsen, 28-Jun-1996 -->
! 4: <TITLE>W3C Reference Library libwww Accessing URLs</TITLE>
2.9 timbl 5: </HEAD>
2.5 timbl 6: <BODY>
2.77 frystyk 7: <H1>
2.78 ! frystyk 8: Accessing URLs
2.77 frystyk 9: </H1>
2.41 frystyk 10: <PRE>
11: /*
2.50 frystyk 12: ** (c) COPYRIGHT MIT 1995.
2.41 frystyk 13: ** Please first read the full copyright statement in the file COPYRIGH.
14: */
15: </PRE>
2.77 frystyk 16: <P>
17: This module is the application interface module to the
2.78 ! frystyk 18: <A HREF="HTReq.html">Request class</A>. It contains a lot of methods for
! 19: loading URLs and also for uploading URLs using <CODE>PUT</CODE> or
! 20: <CODE>POST</CODE>, for example. You can use the Request class directly but
! 21: this module makes it easier to use by providing a lot of small request functions
! 22: using the Request class in different ways. It contains help functions for
! 23: accessing documents and for uploading documents to a remote server.
2.77 frystyk 24: <P>
25: This module is implemented by <A HREF="HTAccess.c">HTAccess.c</A>, and it
26: is a part of the <A HREF="http://www.w3.org/pub/WWW/Library/"> W3C Reference
27: Library</A>.
2.33 frystyk 28: <PRE>
29: #ifndef HTACCESS_H
1.1 timbl 30: #define HTACCESS_H
2.44 roeber 31:
2.64 frystyk 32: #include "HTReq.h"
33: #include "HTAnchor.h"
2.52 frystyk 34: </PRE>
2.77 frystyk 35: <H2>
2.78 ! frystyk 36: Loading a URL
2.77 frystyk 37: </H2>
38: <P>
2.78 ! frystyk 39: URLs can be accesses using a character string, for example
! 40: "<CODE>http://www.w3.org</CODE>" or it can be accessed by using the libwww
! 41: representation of a URL which is called an <A HREF="HTAnchor.html">Anchor
! 42: object</A>. Note that we call all objects accessible through URLs for
! 43: <I>documents</I> - this is a notion we have inherited from the hypertext
! 44: world.
2.77 frystyk 45: <H3>
2.78 ! frystyk 46: Request a Document from Absolute URL
2.77 frystyk 47: </H3>
48: <P>
2.78 ! frystyk 49: Request a document referencd by an <I>absolute</I> URL. The output from the
! 50: request is passed to the <A HREF="HTFormat.html">Stream Pipe Manager</A>
! 51: that figures out where to pump the data. This can for example be to the display
! 52: or to a local file depending on the set of
! 53: <A HREF="HTFormat.html#type">converters</A> registered by the application.
! 54: <PRE>extern BOOL HTLoadAbsolute (const char * url, HTRequest * request);
2.65 frystyk 55: </PRE>
2.77 frystyk 56: <H3>
2.78 ! frystyk 57: Request a Document from Relative URL
2.77 frystyk 58: </H3>
59: <P>
2.78 ! frystyk 60: Request a document referenced by a <I>relative</I> URL. The relative URL
! 61: is made absolute by resolving it relative to the address of the '<I>base</I>'
! 62: anchor.
! 63: <PRE>extern BOOL HTLoadRelative (const char * relative,
! 64: HTParentAnchor * base,
! 65: HTRequest * request);
2.66 frystyk 66: </PRE>
2.77 frystyk 67: <H3>
2.78 ! frystyk 68: Load a URL into Memory
2.77 frystyk 69: </H3>
70: <P>
2.78 ! frystyk 71: Request a document referred to by the URL and load it into a chunk object.
! 72: A <A HREF="HTChunk.html">chunk object</A> is a dynamic string so in the end
! 73: you will have a single memory buffer containing the document.
! 74: <PRE>extern HTChunk * HTLoadToChunk (const char * url, HTRequest * request);
2.52 frystyk 75: </PRE>
2.77 frystyk 76: <H3>
2.78 ! frystyk 77: Request a Document using an Anchor
2.77 frystyk 78: </H3>
79: <P>
2.78 ! frystyk 80: Here the URL is represented by an <A HREF="HTAnchor.html">Anchor object</A>.
! 81: You can get an anchor object representing a URL by passing the URL to the
! 82: approproiate method in the <A HREF="HTAnchor.html">Anchor class</A>.
! 83: <PRE>extern BOOL HTLoadAnchor (HTAnchor * anchor, HTRequest * request);
2.52 frystyk 84: </PRE>
2.77 frystyk 85: <H3>
2.78 ! frystyk 86: Load a URL into Memory using an Anchor
2.77 frystyk 87: </H3>
88: <P>
2.78 ! frystyk 89: This is the same as HTLoadToChunk but instead of passing a URL string you
! 90: pass an anchor object. Internally, all URLs are represented as anchors which
! 91: contains all the information we have about the resource.
! 92: <PRE>extern HTChunk * HTLoadAnchorToChunk (HTAnchor * anchor, HTRequest * request);
2.77 frystyk 93: </PRE>
94: <H3>
2.78 ! frystyk 95: Recursively Request a Document using an Anchor
2.77 frystyk 96: </H3>
97: <P>
2.78 ! frystyk 98: Same as <CODE>HTLoadAnchor()</CODE> but the information in the error stack
! 99: in the request object is kept, so that any error messages in one. This function
! 100: is almost identical to <CODE>HTLoadAnchor</CODE>, but it doesn't clear the
! 101: error stack so that the information in there is kept. Returns YES if request
! 102: accepted, else NO
! 103: <PRE>extern BOOL HTLoadAnchorRecursive (HTAnchor * anchor, HTRequest * request);
2.46 frystyk 104: </PRE>
2.78 ! frystyk 105: <H2>
! 106: Searching a URL
! 107: </H2>
2.77 frystyk 108: <H3>
109: Search an Anchor
110: </H3>
111: <P>
112: Performs a keyword search on word given by the user. Adds the keyword to
113: the end of the current address and attempts to open the new address. The
114: list of keywords must be a space-separated list and spaces will be converted
115: to '+' before the request is issued. Search can also be performed by
116: HTLoadAbsolute() etc. Returns YES if request accepted, else NO
2.46 frystyk 117: <PRE>
2.73 frystyk 118: extern BOOL HTSearch (const char * keywords,
2.64 frystyk 119: HTParentAnchor * base,
120: HTRequest * request);
2.46 frystyk 121: </PRE>
2.77 frystyk 122: <H3>
123: Search a document from absolute name
124: </H3>
125: <P>
126: Request a document referencd by an absolute URL appended with the keywords
127: given. The URL can NOT contain any fragment identifier! The list of keywords
128: must be a space-separated list and spaces will be converted to '+' before
129: the request is issued. Returns YES if request accepted, else NO
2.78 ! frystyk 130: <PRE>extern BOOL HTSearchAbsolute (const char * keywords,
2.73 frystyk 131: const char * url,
2.64 frystyk 132: HTRequest * request);
2.39 frystyk 133: </PRE>
2.77 frystyk 134: <H2>
2.78 ! frystyk 135: Saving a URL
2.77 frystyk 136: </H2>
137: <H3>
138: Copy an anchor
139: </H3>
140: <P>
141: Fetch the URL from either local file store <B>or</B> from a remote HTTP server
142: and send it using either PUT or POST to the remote destination using HTTP.
143: The caller can decide the exact method used and which HTTP header fields
144: to transmit by setting the user fields in the request structure. If posting
145: to NNTP then we can't dispatch at this level but must pass the source anchor
146: to the news module that then takes all the refs to NNTP and puts into the
147: "newsgroups" header Returns YES if request accepted, else NO
2.78 ! frystyk 148: <PRE>extern BOOL HTCopyAnchor (HTAnchor * src_anchor, HTRequest * main_req);
2.47 frystyk 149: </PRE>
2.77 frystyk 150: <H3>
151: Upload an Anchor
152: </H3>
153: <P>
154: This function can be used to send data along with a request to a remote server.
155: It can for example be used to POST form data to a remote HTTP server - or
156: it can be used to post a newsletter to a NNTP server. In either case, you
157: pass a callback function which the request calls when the remote destination
158: is ready to accept data. In this callback you get the current request object
159: and a stream into where you can write data. It is very important that you
160: return the value returned by this stream to the Library so that it knows
161: what to do next. The reason is that the outgoing stream might block or an
162: error may occur and in that case the Library must know about it. If you do
2.71 frystyk 163: not want to handle the stream interface yourself then you can use the
2.77 frystyk 164: <CODE>HTUpload_callback</CODE> which is declared below.
165: <P>
166: The source anchor represents the data object in memory and it points to the
167: destination anchor by using the
168: <A HREF="../User/Architecture/PostWeb.html">POSTWeb method</A>. The source
169: anchor contains metainformation about the data object in memory and the
170: destination anchor represents the reponse from the remote server. Returns
171: YES if request accepted, else NO
2.78 ! frystyk 172: <PRE>extern BOOL HTUploadAnchor (HTAnchor * source_anchor,
2.71 frystyk 173: HTRequest * request,
174: HTPostCallback * callback);
175: </PRE>
2.77 frystyk 176: <H3>
177: POST Callback Handler
178: </H3>
179: <P>
180: Is you do not want to handle the stream interface on your own, you can use
181: this "middleman" function which does the actual writing to the target stream
182: for the anchor upload and also handles the return value from the stream.
183: Now, your application is called via the callback function that you may associate
184: with a request object. You indicate when you have sent all the data you want
185: by returning HT_LOADED from the callback.
2.43 frystyk 186: <PRE>
2.72 frystyk 187: extern int HTUpload_callback (HTRequest * request, HTStream * target);
2.46 frystyk 188: </PRE>
2.25 luotonen 189: <PRE>
2.63 frystyk 190: #endif /* HTACCESS_H */
2.38 howcome 191: </PRE>
2.77 frystyk 192: <P>
193: <HR>
2.75 frystyk 194: <ADDRESS>
2.78 ! frystyk 195: @(#) $Id: HTAccess.html,v 2.77 1996/05/20 15:06:21 frystyk Exp $
2.75 frystyk 196: </ADDRESS>
2.77 frystyk 197: </BODY></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