Annotation of libwww/Library/src/HTAccess.html, revision 2.79
2.9 timbl 1: <HTML>
2: <HEAD>
2.79 ! frystyk 3: <!-- Changed by: Henrik Frystyk Nielsen, 15-Jul-1996 -->
2.78 frystyk 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.79 ! frystyk 36: Load a Document (Method = GET)
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.79 ! frystyk 46: Load 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.79 ! frystyk 57: Load 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.79 ! frystyk 68: Load a Document 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.79 ! frystyk 77: Load a Document and Save as a Local File
! 78: </H3>
! 79: <P>
! 80: This function loads a URL and saves the contents in the file specifed. The
! 81: file does not have to be open, the load function both opens and closes the
! 82: file. If the file already exists then it asks whether the file should be
! 83: overwritten or not. the contents is saved <I>ASIS</I> - that is - we do not
! 84: touch the contents of the file!
! 85: <PRE>
! 86: extern BOOL HTLoadToFile (const char * url, HTRequest * request,
! 87: const char * filename);
! 88: </PRE>
! 89: <H3>
! 90: Load a Document and put the Contents into a Stream
! 91: </H3>
! 92: <P>
! 93: Request a document referencd by an absolute URL and sending the data down
! 94: a stream.
! 95: <PRE>
! 96: extern BOOL HTLoadToStream (const char * url, HTStream * output,
! 97: HTRequest * request);
! 98: </PRE>
! 99: <H3>
! 100: Load a Document using an Anchor
2.77 frystyk 101: </H3>
102: <P>
2.78 frystyk 103: Here the URL is represented by an <A HREF="HTAnchor.html">Anchor object</A>.
104: You can get an anchor object representing a URL by passing the URL to the
105: approproiate method in the <A HREF="HTAnchor.html">Anchor class</A>.
106: <PRE>extern BOOL HTLoadAnchor (HTAnchor * anchor, HTRequest * request);
2.52 frystyk 107: </PRE>
2.77 frystyk 108: <H3>
2.79 ! frystyk 109: Load a Document into Memory using an Anchor
2.77 frystyk 110: </H3>
111: <P>
2.78 frystyk 112: This is the same as HTLoadToChunk but instead of passing a URL string you
113: pass an anchor object. Internally, all URLs are represented as anchors which
114: contains all the information we have about the resource.
115: <PRE>extern HTChunk * HTLoadAnchorToChunk (HTAnchor * anchor, HTRequest * request);
2.77 frystyk 116: </PRE>
117: <H3>
2.79 ! frystyk 118: Recursively Request a Document using Anchors
2.77 frystyk 119: </H3>
120: <P>
2.78 frystyk 121: Same as <CODE>HTLoadAnchor()</CODE> but the information in the error stack
122: in the request object is kept, so that any error messages in one. This function
123: is almost identical to <CODE>HTLoadAnchor</CODE>, but it doesn't clear the
124: error stack so that the information in there is kept. Returns YES if request
125: accepted, else NO
126: <PRE>extern BOOL HTLoadAnchorRecursive (HTAnchor * anchor, HTRequest * request);
2.46 frystyk 127: </PRE>
2.78 frystyk 128: <H2>
2.79 ! frystyk 129: Load Special Documents
2.78 frystyk 130: </H2>
2.79 ! frystyk 131: <P>
! 132: We also have a set of functions for loading special files like rules files
! 133: which also are referenced by a URL but which do have to be treated specially.
2.77 frystyk 134: <H3>
2.79 ! frystyk 135: Load a Rule File
2.77 frystyk 136: </H3>
137: <P>
2.79 ! frystyk 138: Rule files can be loaded just like any other URL but yuou can also just use
! 139: this function which does all the work for you :-) It loads a rule find with
! 140: the URL specified and add the set of rules to the existing set.
! 141: <PRE>extern BOOL HTLoadRules (const char * url);
! 142: </PRE>
! 143: <H2>
! 144: Search a Document (Method = GET)
! 145: </H2>
! 146: <P>
! 147: The search methods all use GET as the method in the HTTP request. The functions
! 148: take the keywirds and encode them according to RFC 1866 (Hypertext Markup
! 149: language). That is, the query part is separated from the rest of the URL
! 150: by a "?" nu is treated as being part of the URL path.
! 151: <P>
! 152: The keywords are passed to the function as a <A HREF="HTChunk.html">Chunk
! 153: Object</A> and each keyword must be separated by a space ' '. This will then
! 154: be converted into a '+' before added to the URL.
! 155: <H3>
! 156: Search a Document from Absolute URL
! 157: </H3>
2.46 frystyk 158: <PRE>
2.79 ! frystyk 159: extern BOOL HTSearchAbsolute (HTChunk * keywords,
! 160: const char * base,
! 161: HTRequest * request);
2.46 frystyk 162: </PRE>
2.77 frystyk 163: <H3>
2.79 ! frystyk 164: Search a Document from Relative URL
2.77 frystyk 165: </H3>
166: <P>
2.79 ! frystyk 167: Search a document referenced by a <I>relative</I> URL. The relative URL is
! 168: made absolute by resolving it relative to the address of the '<I>base</I>'
! 169: anchor.
! 170: <PRE>
! 171: extern BOOL HTSearchRelative (HTChunk * keywords,
! 172: const char * relative,
! 173: HTParentAnchor * base,
2.64 frystyk 174: HTRequest * request);
2.39 frystyk 175: </PRE>
2.79 ! frystyk 176: <H3>
! 177: Search a Document using an Anchor
! 178: </H3>
! 179: <PRE>
! 180: extern BOOL HTSearchAnchor (HTChunk * keywords,
! 181: HTAnchor * anchor,
! 182: HTRequest * request);
! 183: </PRE>
! 184: <H3>
! 185: Search a Document using an Anchor Using a String
! 186: </H3>
! 187: <P>
! 188: This works exactly as the <CODE>HTSearchAnchor()</CODE> function but takes
! 189: a C string instead of a <A HREF="HTChunk.html">chunk object</A>.
! 190: <PRE>
! 191: extern BOOL HTSearchString (const char * keywords,
! 192: HTAnchor * anchor,
! 193: HTRequest * request);
! 194: </PRE>
! 195: <H2>
! 196: Handle Forms Using GET Method
! 197: </H2>
! 198: <P>
! 199: Form data can be sent to a HTTP server in two ways - it can either use a
! 200: GET method or it can use a POST method. The difference is whether the request
! 201: "has side effects" or not. For example, if you are ordering a pizza then
! 202: the (hopefully positive) sideeffect is that you actually get one delivered.
! 203: However, if you are issuing search data - for example to Alta Vista, then
! 204: there is no sideeffect. In the former example you would use the GET form
! 205: and in the latter you would use the POST form.
! 206: <H3>
! 207: Send a Form from Absolute URL using GET
! 208: </H3>
! 209: <P>
! 210: Request a document referencd by an absolute URL appended with the formdata
! 211: given. The URL can NOT contain any fragment identifier! The list of form
! 212: data must be given as an association list where the name is the field name
! 213: and the value is the value of the field.
! 214: <PRE>
! 215: extern BOOL HTGetFormAbsolute (HTAssocList * formdata,
! 216: const char * base,
! 217: HTRequest * request);
! 218: </PRE>
! 219: <H3>
! 220: Send a Form from Relative URL using GET
! 221: </H3>
! 222: <P>
! 223: Request a document referencd by a relative URL appended with the formdata
! 224: given. The URL can NOT contain any fragment identifier! The list of form
! 225: data must be given as an association list where the name is the field name
! 226: and the value is the value of the field.
! 227: <PRE>
! 228: extern BOOL HTGetFormRelative (HTAssocList * formdata,
! 229: const char * relative,
! 230: HTParentAnchor * base,
! 231: HTRequest * request);
! 232: </PRE>
! 233: <H3>
! 234: Send a Form using an Anchor and the GET Method
! 235: </H3>
! 236: <P>
! 237: Request a document referencd by an anchor object appended with the formdata
! 238: given. The URL can NOT contain any fragment identifier! The list of form
! 239: data must be given as an association list where the name is the field name
! 240: and the value is the value of the field.
! 241: <PRE>
! 242: extern BOOL HTGetFormAnchor (HTAssocList * formdata,
! 243: HTAnchor * anchor,
! 244: HTRequest * request);
! 245: </PRE>
! 246: <H2>
! 247: Handle Forms Using POST Method
! 248: </H2>
! 249: <P>
! 250: The main difference between a <CODE>GET</CODE> form and a <CODE>POST</CODE>
! 251: form is that the data in a <CODE>POST</CODE> form is sent as the body part
! 252: of the <A HREF="http://www.w3.org/pub/WWW/Protocols/">HTTP</A> message whereas
! 253: a <CODE>GET</CODE> form wraps it all up into the URL. In order to be able
! 254: to use the <CODE>POST</CODE> data object at a later point in time, we create
! 255: a new anchor on the fly. This anchor has a URL file location which points
! 256: into the temporary area given by the <A HREF="HTUser.html">User Profile
! 257: Object</A>. That is - you can actually save the anchor using a PUT request
! 258: and then be able to retrive the form data at a later point in time. Even
! 259: though this may seem "ambitious" for posting form data, it is really just
! 260: a special example of sending any kind of data to a remote server. All
! 261: <CODE>POST</CODE> form functions return the new anchor or <CODE>NULL</CODE>
! 262: if they fail.
! 263: <H3>
! 264: Send a Form from Absolute URL using POST
! 265: </H3>
! 266: <P>
! 267: Request a document referencd by an absolute URL appended with the formdata
! 268: given. The URL can NOT contain any fragment identifier! The list of form
! 269: data must be given as an association list where the name is the field name
! 270: and the value is the value of the field.
! 271: <PRE>
! 272: extern HTParentAnchor * HTPostFormAbsolute (HTAssocList * formdata,
! 273: const char * base,
! 274: HTRequest * request);
! 275: </PRE>
! 276: <H3>
! 277: Send a Form from a Relative URL using GET
! 278: </H3>
! 279: <P>
! 280: Request a document referencd by a relative URL appended with the formdata
! 281: given. The URL can NOT contain any fragment identifier! The list of form
! 282: data must be given as an association list where the name is the field name
! 283: and the value is the value of the field.
! 284: <PRE>
! 285: extern HTParentAnchor * HTPostFormRelative (HTAssocList * formdata,
! 286: const char * relative,
! 287: HTParentAnchor * base,
! 288: HTRequest * request);
! 289: </PRE>
! 290: <H3>
! 291: Send a Form using an Anchor and the POST Method
! 292: </H3>
! 293: <P>
! 294: Request a document referencd by an anchor object appended with the formdata
! 295: given. The URL can NOT contain any fragment identifier! The list of form
! 296: data must be given as an association list where the name is the field name
! 297: and the value is the value of the field.
! 298: <PRE>
! 299: extern HTParentAnchor * HTPostFormAnchor (HTAssocList * formdata,
! 300: HTAnchor * anchor,
! 301: HTRequest * request);
! 302: </PRE>
2.77 frystyk 303: <H2>
2.79 ! frystyk 304: Get Metainformation about a Document (Method = HEAD)
! 305: </H2>
! 306: <P>
! 307: If you are not interested in the document itself but only in the
! 308: <I>metainformation</I> that you can get <I>describing</I> the document then
! 309: you should use the <CODE>HEAD</CODE> method in your request.
! 310: <H3>
! 311: Get Metainformation about a Document from Absolute URL
! 312: </H3>
! 313: <P>
! 314: Request metainfomration about a document referencd by an <I>absolute</I>
! 315: URL.
! 316: <PRE>extern BOOL HTHeadAbsolute (const char * url, HTRequest * request);
! 317: </PRE>
! 318: <H3>
! 319: Get Metainformation about a Document from Relative URL
! 320: </H3>
! 321: <P>
! 322: Request metainformation about a document referenced by a <I>relative</I>
! 323: URL.
! 324: <PRE>extern BOOL HTHeadRelative (const char * relative,
! 325: HTParentAnchor * base,
! 326: HTRequest * request);
! 327: </PRE>
! 328: <H3>
! 329: Get Metainformation about a Document using an Anchor
! 330: </H3>
! 331: <P>
! 332: Here the URL is represented by an <A HREF="HTAnchor.html">Anchor object</A>.
! 333: You can get an anchor object representing a URL by passing the URL to the
! 334: approproiate method in the <A HREF="HTAnchor.html">Anchor class</A>.
! 335: <PRE>extern BOOL HTHeadAnchor (HTAnchor * anchor, HTRequest * request);
! 336: </PRE>
! 337: <H2>
! 338: Delete a URL
! 339: </H2>
! 340: <P>
! 341: If you want to delete a document (or make the document inaccessible for future
! 342: references) then you can use the <CODE>DELETE</CODE> method in your request.
! 343: <H3>
! 344: Delete a Document from Absolute URL
! 345: </H3>
! 346: <P>
! 347: Request metainfomration about a document referencd by an <I>absolute</I>
! 348: URL.
! 349: <PRE>extern BOOL HTDeleteAbsolute (const char * url, HTRequest * request);
! 350: </PRE>
! 351: <H3>
! 352: Delete a Document from Relative URL
! 353: </H3>
! 354: <P>
! 355: Request metainformation about a document referenced by a <I>relative</I>
! 356: URL.
! 357: <PRE>extern BOOL HTDeleteRelative (const char * relative,
! 358: HTParentAnchor * base,
! 359: HTRequest * request);
! 360: </PRE>
! 361: <H3>
! 362: Delete a Document using an Anchor
! 363: </H3>
! 364: <P>
! 365: Here the URL is represented by an <A HREF="HTAnchor.html">Anchor object</A>.
! 366: You can get an anchor object representing a URL by passing the URL to the
! 367: approproiate method in the <A HREF="HTAnchor.html">Anchor class</A>.
! 368: <PRE>extern BOOL HTDeleteAnchor (HTAnchor * anchor, HTRequest * request);
! 369: </PRE>
! 370: <H2>
! 371: Save a URL
2.77 frystyk 372: </H2>
373: <H3>
374: Copy an anchor
375: </H3>
376: <P>
377: Fetch the URL from either local file store <B>or</B> from a remote HTTP server
378: and send it using either PUT or POST to the remote destination using HTTP.
379: The caller can decide the exact method used and which HTTP header fields
380: to transmit by setting the user fields in the request structure. If posting
381: to NNTP then we can't dispatch at this level but must pass the source anchor
382: to the news module that then takes all the refs to NNTP and puts into the
383: "newsgroups" header Returns YES if request accepted, else NO
2.78 frystyk 384: <PRE>extern BOOL HTCopyAnchor (HTAnchor * src_anchor, HTRequest * main_req);
2.47 frystyk 385: </PRE>
2.77 frystyk 386: <H3>
387: Upload an Anchor
388: </H3>
389: <P>
390: This function can be used to send data along with a request to a remote server.
391: It can for example be used to POST form data to a remote HTTP server - or
392: it can be used to post a newsletter to a NNTP server. In either case, you
393: pass a callback function which the request calls when the remote destination
394: is ready to accept data. In this callback you get the current request object
395: and a stream into where you can write data. It is very important that you
396: return the value returned by this stream to the Library so that it knows
397: what to do next. The reason is that the outgoing stream might block or an
398: error may occur and in that case the Library must know about it. If you do
2.71 frystyk 399: not want to handle the stream interface yourself then you can use the
2.79 ! frystyk 400: <CODE>HTUpload_callback</CODE> which is declared below. The source anchor
! 401: represents the data object in memory and it points to the destination anchor
! 402: by using the <A HREF="../User/Architecture/PostWeb.html">POSTWeb method</A>.
! 403: The source anchor contains metainformation about the data object in memory
! 404: and the destination anchor represents the reponse from the remote server.
! 405: Returns YES if request accepted, else NO
2.78 frystyk 406: <PRE>extern BOOL HTUploadAnchor (HTAnchor * source_anchor,
2.71 frystyk 407: HTRequest * request,
408: HTPostCallback * callback);
409: </PRE>
2.77 frystyk 410: <H3>
411: POST Callback Handler
412: </H3>
413: <P>
414: Is you do not want to handle the stream interface on your own, you can use
415: this "middleman" function which does the actual writing to the target stream
416: for the anchor upload and also handles the return value from the stream.
417: Now, your application is called via the callback function that you may associate
418: with a request object. You indicate when you have sent all the data you want
419: by returning HT_LOADED from the callback.
2.43 frystyk 420: <PRE>
2.72 frystyk 421: extern int HTUpload_callback (HTRequest * request, HTStream * target);
2.46 frystyk 422: </PRE>
2.25 luotonen 423: <PRE>
2.63 frystyk 424: #endif /* HTACCESS_H */
2.38 howcome 425: </PRE>
2.77 frystyk 426: <P>
427: <HR>
2.75 frystyk 428: <ADDRESS>
2.79 ! frystyk 429: @(#) $Id: HTAccess.html,v 2.78 1996/06/28 16:30:50 frystyk Exp $
2.75 frystyk 430: </ADDRESS>
2.77 frystyk 431: </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