Annotation of libwww/Library/src/HTAccess.html, revision 2.90
2.9 timbl 1: <HTML>
2: <HEAD>
2.79 frystyk 3: <!-- Changed by: Henrik Frystyk Nielsen, 15-Jul-1996 -->
2.87 frystyk 4: <TITLE>W3C Sample Code Library libwww Accessing URIs</TITLE>
2.9 timbl 5: </HEAD>
2.5 timbl 6: <BODY>
2.77 frystyk 7: <H1>
2.87 frystyk 8: Accessing URIs
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
2.87 frystyk 19: loading URIs and also for uploading URIs using <CODE>PUT</CODE> or
2.78 frystyk 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>
2.87 frystyk 25: This module contains functions for handling all HTTP/1.1 methods:
26: <DL>
27: <DT>
28: GET Requests
29: <DD>
30: <UL>
31: <LI>
32: <A HREF="#Load">Various GET requests including specialized functions like
33: loading a rule file, etc.</A>
34: <LI>
35: <A HREF="#Search">Search requests based on the GET method</A>
36: <LI>
37: <A HREF="#getforms">Formdata requests based on the GET method</A>
38: </UL>
39: <DT>
40: PUT Requests
41: <DD>
42: <UL>
43: <LI>
44: <A HREF="#SaveASIS">Save a document from memory ASIS using PUT</A>
45: <LI>
46: <A HREF="#SaveStructured">Save a structured document from memory using PUT</A>
47: <LI>
48: <A HREF="#SaveURL">Save any URI (FTP, HTTP, local disk) using PUT</A>
49: </UL>
50: <DT>
51: POST Requests
52: <DD>
53: <UL>
54: <LI>
55: <A HREF="#PostForms">Post Formdata to a remote HTTP server</A>
56: <LI>
57: <A HREF="#PostASIS">Post a document from memory ASIS to a remote HTTP
58: server</A>
59: </UL>
60: <DT>
61: HEAD, DELETE, OPTIONS, and TRACE requests
62: <DD>
63: <UL>
64: <LI>
65: <A HREF="#Head">Get metainformation about a document using HEAD requests</A>
66: <LI>
67: <A HREF="#Delete">Delete documents based on the DELETE method</A>
68: <LI>
69: <A HREF="#OPTIONS">Get information about the features supoprted by a resource
70: using OPTIONS</A>
71: <LI>
72: <A HREF="#TRACE">Trace a request using the TRACE method</A>
73: </UL>
74: </DL>
75: <P>
2.88 frystyk 76: Furthermore, it contains a <A HREF="#serve">few access methods for handling
77: incoming requests</A> - in orther words acting as a server. Although libwww
78: is primarily for clients, it is in fact symmetric in that it can handle both
79: client requests and server requests.
80: <P>
2.77 frystyk 81: This module is implemented by <A HREF="HTAccess.c">HTAccess.c</A>, and it
2.84 frystyk 82: is a part of the <A HREF="http://www.w3.org/Library/"> W3C Sample Code
2.77 frystyk 83: Library</A>.
2.33 frystyk 84: <PRE>
85: #ifndef HTACCESS_H
1.1 timbl 86: #define HTACCESS_H
2.44 roeber 87:
2.64 frystyk 88: #include "HTReq.h"
89: #include "HTAnchor.h"
2.90 ! vbancrof 90:
! 91: #ifdef __cplusplus
! 92: extern "C" {
! 93: #endif
! 94:
2.52 frystyk 95: </PRE>
2.77 frystyk 96: <H2>
2.87 frystyk 97: <A NAME="Load">Load a Document (Method = GET)</A>
2.77 frystyk 98: </H2>
99: <P>
2.87 frystyk 100: URIs can be accesses using a character string, for example
2.78 frystyk 101: "<CODE>http://www.w3.org</CODE>" or it can be accessed by using the libwww
2.87 frystyk 102: representation of a URI called an <A HREF="HTAnchor.html">Anchor object</A>.
103: Note that we call all objects accessible through URIs for <I>documents</I>
2.80 frystyk 104: - this is a notion we have inherited from the hypertext world.
2.77 frystyk 105: <H3>
2.87 frystyk 106: Load a Document from Absolute URI
2.77 frystyk 107: </H3>
108: <P>
2.87 frystyk 109: Request a document referencd by an <I>absolute</I> URI. The output from the
2.78 frystyk 110: request is passed to the <A HREF="HTFormat.html">Stream Pipe Manager</A>
111: that figures out where to pump the data. This can for example be to the display
112: or to a local file depending on the set of
113: <A HREF="HTFormat.html#type">converters</A> registered by the application.
114: <PRE>extern BOOL HTLoadAbsolute (const char * url, HTRequest * request);
2.65 frystyk 115: </PRE>
2.77 frystyk 116: <H3>
2.87 frystyk 117: Load a Document from Relative URI
2.77 frystyk 118: </H3>
119: <P>
2.87 frystyk 120: Request a document referenced by a <I>relative</I> URI. The relative URI
2.78 frystyk 121: is made absolute by resolving it relative to the address of the '<I>base</I>'
122: anchor.
123: <PRE>extern BOOL HTLoadRelative (const char * relative,
124: HTParentAnchor * base,
125: HTRequest * request);
2.66 frystyk 126: </PRE>
2.77 frystyk 127: <H3>
2.79 frystyk 128: Load a Document into Memory
2.77 frystyk 129: </H3>
130: <P>
2.87 frystyk 131: Request a document referred to by the URI and load it into a
2.85 frystyk 132: <A HREF="HTChunk.html">HTChunk object</A>. A <A HREF="HTChunk.html">chunk
133: object</A> is a dynamic string so in the end you will have a single memory
134: buffer containing the document. The chunk must be freed by the caller.
2.78 frystyk 135: <PRE>extern HTChunk * HTLoadToChunk (const char * url, HTRequest * request);
2.52 frystyk 136: </PRE>
2.77 frystyk 137: <H3>
2.79 frystyk 138: Load a Document and Save as a Local File
139: </H3>
140: <P>
2.87 frystyk 141: This function loads a URI and saves the contents in the specifed file. The
2.80 frystyk 142: file should not be open, as the load function both opens and closes
143: the file. If the file already exists then it asks the user whether the file
144: should be overwritten or not. the contents is saved <I>ASIS</I> - that is
145: - we do not touch the contents of the file!
2.79 frystyk 146: <PRE>
147: extern BOOL HTLoadToFile (const char * url, HTRequest * request,
148: const char * filename);
149: </PRE>
150: <H3>
151: Load a Document and put the Contents into a Stream
152: </H3>
153: <P>
2.87 frystyk 154: Request a document referenced by an absolute URI and sending the data down
2.80 frystyk 155: a stream. This stream can be anny stream you like, for eample one from the
156: <A HREF="WWWStream.html">Stream Interface</A>.
2.79 frystyk 157: <PRE>
158: extern BOOL HTLoadToStream (const char * url, HTStream * output,
159: HTRequest * request);
160: </PRE>
161: <H3>
162: Load a Document using an Anchor
2.77 frystyk 163: </H3>
164: <P>
2.87 frystyk 165: Here the URI is represented by an <A HREF="HTAnchor.html">Anchor object</A>.
166: You can get an anchor object representing a URI by passing the URI to the
2.80 frystyk 167: appropriate method in the <A HREF="HTAnchor.html">Anchor class</A>.
2.78 frystyk 168: <PRE>extern BOOL HTLoadAnchor (HTAnchor * anchor, HTRequest * request);
2.52 frystyk 169: </PRE>
2.77 frystyk 170: <H3>
2.79 frystyk 171: Load a Document into Memory using an Anchor
2.77 frystyk 172: </H3>
173: <P>
2.87 frystyk 174: This is the same as <CODE>HTLoadToChunk</CODE> but instead of passing a URI
2.85 frystyk 175: string you pass an <A HREF="HTAnchor.html">HTAnchor object</A>. Internally,
2.87 frystyk 176: all URIs are represented as anchors which contains all the information we
2.85 frystyk 177: have about the resource. The chunk must be freed by the caller.
2.78 frystyk 178: <PRE>extern HTChunk * HTLoadAnchorToChunk (HTAnchor * anchor, HTRequest * request);
2.77 frystyk 179: </PRE>
180: <H3>
2.79 frystyk 181: Recursively Request a Document using Anchors
2.77 frystyk 182: </H3>
183: <P>
2.80 frystyk 184: Same as <CODE>HTLoadAnchor()</CODE> but the information in the
185: <A HREF="HTReq.html#Error">error stack</A> in the <A HREF="HTReq.html">request
186: object</A> is kept, so that any error messages in one. This function is almost
187: identical to <CODE>HTLoadAnchor</CODE>, but it doesn't clear the error stack
188: so that the information in there is kept.
2.78 frystyk 189: <PRE>extern BOOL HTLoadAnchorRecursive (HTAnchor * anchor, HTRequest * request);
2.46 frystyk 190: </PRE>
2.78 frystyk 191: <H2>
2.79 frystyk 192: Load Special Documents
2.78 frystyk 193: </H2>
2.79 frystyk 194: <P>
195: We also have a set of functions for loading special files like rules files
2.87 frystyk 196: which also are referenced by a URI but which do have to be treated specially.
2.77 frystyk 197: <H3>
2.79 frystyk 198: Load a Rule File
2.77 frystyk 199: </H3>
200: <P>
2.87 frystyk 201: Rule files can be loaded just like any other URI but you can also just use
202: these functions which do all the work for you: they load a rule find with
203: the URI specified and add the set of rules to the existing set.
204: <P>
205: They come in two flavours - one that asks the user whether it is OK to add
206: the rules and one that does it automatically without asking. As the app would
207: have to call this method explicitly, it may have other ways of protecting
208: the user.
2.86 frystyk 209: <P>
2.87 frystyk 210: Both functions use <A HREF="HTReq.html#preemptive">preemptive requests</A>
211: so that everything else stops in the meantime.
2.86 frystyk 212: <PRE>
213: extern BOOL HTLoadRules (const char * url);
214: extern BOOL HTLoadRulesAutomatically (const char * url);
2.79 frystyk 215: </PRE>
216: <H2>
2.85 frystyk 217: <A NAME="Search">Search a Document (Method = GET)</A>
2.79 frystyk 218: </H2>
219: <P>
2.80 frystyk 220: The search methods all use <CODE>GET</CODE> as the method in the
2.85 frystyk 221: <A HREF="http://www.w3.org/Protocols/">HTTP request</A>. The functions take
222: the keywords and encode them according to
2.80 frystyk 223: <A HREF="http://info.internet.isi.edu:80/in-notes/rfc/files/rfc1866.txt">RFC
224: 1866 (Hypertext Markup language)</A>. That is, the query part is separated
2.87 frystyk 225: from the rest of the URI by a "?".
2.79 frystyk 226: <P>
227: The keywords are passed to the function as a <A HREF="HTChunk.html">Chunk
2.80 frystyk 228: Object</A> and each keyword <B>must</B> be separated by a space ' '. This
2.87 frystyk 229: will then be converted into a '+' before added to the URI.
2.79 frystyk 230: <H3>
2.87 frystyk 231: Search a Document from Absolute URI
2.79 frystyk 232: </H3>
2.46 frystyk 233: <PRE>
2.79 frystyk 234: extern BOOL HTSearchAbsolute (HTChunk * keywords,
235: const char * base,
236: HTRequest * request);
2.46 frystyk 237: </PRE>
2.77 frystyk 238: <H3>
2.87 frystyk 239: Search a Document from Relative URI
2.77 frystyk 240: </H3>
241: <P>
2.87 frystyk 242: Search a document referenced by a <I>relative</I> URI. The relative URI is
2.79 frystyk 243: made absolute by resolving it relative to the address of the '<I>base</I>'
244: anchor.
245: <PRE>
246: extern BOOL HTSearchRelative (HTChunk * keywords,
247: const char * relative,
248: HTParentAnchor * base,
2.64 frystyk 249: HTRequest * request);
2.39 frystyk 250: </PRE>
2.79 frystyk 251: <H3>
252: Search a Document using an Anchor
253: </H3>
254: <PRE>
255: extern BOOL HTSearchAnchor (HTChunk * keywords,
256: HTAnchor * anchor,
257: HTRequest * request);
258: </PRE>
259: <H3>
260: Search a Document using an Anchor Using a String
261: </H3>
262: <P>
263: This works exactly as the <CODE>HTSearchAnchor()</CODE> function but takes
264: a C string instead of a <A HREF="HTChunk.html">chunk object</A>.
265: <PRE>
266: extern BOOL HTSearchString (const char * keywords,
267: HTAnchor * anchor,
268: HTRequest * request);
269: </PRE>
270: <H2>
2.87 frystyk 271: <A NAME="getforms">Submit Forms Using GET Method</A>
2.79 frystyk 272: </H2>
273: <P>
2.87 frystyk 274: Formdata can be sent to an HTTP server in two ways - it can either use a
2.80 frystyk 275: <CODE>GET</CODE> method or it can use a <CODE>POST</CODE> method. The difference
276: is whether the request "has side effects" or not. For example, if you are
277: ordering a pizza then the (hopefully positive) sideeffect is that you actually
278: get one delivered. However, if you are issuing search data - for example
279: to Alta Vista, then there is no sideeffect. In the former example you would
280: use the <CODE>GET</CODE> form and in the latter you would use the
281: <CODE>POST</CODE> form.
2.79 frystyk 282: <H3>
2.87 frystyk 283: Submit Form from Absolute URI using GET
2.79 frystyk 284: </H3>
285: <P>
2.87 frystyk 286: Submit formdata using GET to the address indicated as the "base" which must
287: be an absolute URI. The list of form data must be given as an
2.80 frystyk 288: <A HREF="HTAssoc.html">association list</A> where the name is the field name
2.87 frystyk 289: and the value is the value of the field.
2.79 frystyk 290: <PRE>
291: extern BOOL HTGetFormAbsolute (HTAssocList * formdata,
292: const char * base,
293: HTRequest * request);
294: </PRE>
295: <H3>
2.87 frystyk 296: Submit Form from Relative URI using GET
2.79 frystyk 297: </H3>
298: <P>
2.87 frystyk 299: Submit formdata using GET to the address indicated relative to the address
300: of the base anchor. The list of form data must be given as an
2.80 frystyk 301: <A HREF="HTAssoc.html">association list</A> where the name is the field name
2.79 frystyk 302: and the value is the value of the field.
303: <PRE>
304: extern BOOL HTGetFormRelative (HTAssocList * formdata,
305: const char * relative,
306: HTParentAnchor * base,
307: HTRequest * request);
308: </PRE>
309: <H3>
310: Send a Form using an Anchor and the GET Method
311: </H3>
312: <P>
2.87 frystyk 313: Submit formdata using GET to the address indicated of the anchor. The list
314: of form data must be given as an <A HREF="HTAssoc.html">association list</A>
315: where the name is the field name and the value is the value of the field.
2.79 frystyk 316: <PRE>
317: extern BOOL HTGetFormAnchor (HTAssocList * formdata,
318: HTAnchor * anchor,
319: HTRequest * request);
320: </PRE>
321: <H2>
2.87 frystyk 322: <A NAME="PostForms">Submit Forms Using POST Method</A>
2.79 frystyk 323: </H2>
324: <P>
2.87 frystyk 325: The data in a <CODE>POST</CODE> form is sent as the body part of the
326: <A HREF="http://www.w3.org/Protocols/">HTTP</A> message whereas a
327: <CODE>GET</CODE> form wraps it all up into the URI. In order to be able to
2.85 frystyk 328: use the <CODE>POST</CODE> data object at a later point in time, we create
2.87 frystyk 329: a new anchor on the fly. This anchor has a URI file location which points
2.79 frystyk 330: into the temporary area given by the <A HREF="HTUser.html">User Profile
2.80 frystyk 331: Object</A>. That is - you can actually save the anchor using a
332: <CODE>PUT</CODE> request and then be able to retrive the form data at a later
333: point in time. Even though this may seem "ambitious" for posting form data,
334: it is really just a special example of sending any kind of data to a remote
335: server. All <CODE>POST</CODE> form functions return the new anchor or
336: <CODE>NULL</CODE> if they fail.
2.79 frystyk 337: <H3>
2.87 frystyk 338: Submit Form from Absolute URI using POST
2.79 frystyk 339: </H3>
340: <P>
2.87 frystyk 341: Submit formdata using POST to the address indicated as the "base" which must
342: be an absolute URI. The list of form data must be given as an
343: <A HREF="HTAssoc.html">association list</A> where the name is the field name
344: and the value is the value of the field.
2.79 frystyk 345: <PRE>
346: extern HTParentAnchor * HTPostFormAbsolute (HTAssocList * formdata,
347: const char * base,
348: HTRequest * request);
349: </PRE>
350: <H3>
2.87 frystyk 351: Submit Form from a Relative URI using GET
2.79 frystyk 352: </H3>
353: <P>
2.87 frystyk 354: Submit formdata using POST to the address indicated relative to the address
355: of the base anchor. The list of form data must be given as an association
356: list where the name is the field name and the value is the value of the field.
2.79 frystyk 357: <PRE>
358: extern HTParentAnchor * HTPostFormRelative (HTAssocList * formdata,
359: const char * relative,
360: HTParentAnchor * base,
361: HTRequest * request);
362: </PRE>
363: <H3>
2.87 frystyk 364: Submit Form using an Anchor and the POST Method
2.79 frystyk 365: </H3>
366: <P>
2.87 frystyk 367: Submit formdata using POST to the address indicated of the anchor. The list
368: of form data must be given as an <A HREF="HTAssoc.html">association list</A>
369: where the name is the field name and the value is the value of the field.
2.79 frystyk 370: <PRE>
371: extern HTParentAnchor * HTPostFormAnchor (HTAssocList * formdata,
372: HTAnchor * anchor,
373: HTRequest * request);
374: </PRE>
2.85 frystyk 375: <H3>
2.87 frystyk 376: Submit Form and Save the Result in a Memory Buffer
2.85 frystyk 377: </H3>
378: <P>
2.87 frystyk 379: Submit formdata to the address referred to by the
380: <A HREF="HTAnchor.html">HTAnchor object</A> and load the result of the POST
381: into a <A HREF="HTChunk.html">HTChunk object</A>. A
382: <A HREF="HTChunk.html">chunk object</A> is a dynamic memory buffer so in
383: the end you will have a single memory buffer containing the document. The
384: chunk must be freed by the caller.
2.85 frystyk 385: <PRE>
386: extern HTChunk * HTPostFormAnchorToChunk (HTAssocList * formdata,
387: HTAnchor * anchor,
388: HTRequest * request);
389: </PRE>
2.77 frystyk 390: <H2>
2.80 frystyk 391: <A NAME="Head">Get Metainformation about a Document (Method = HEAD)</A>
2.79 frystyk 392: </H2>
393: <P>
394: If you are not interested in the document itself but only in the
2.87 frystyk 395: <I>metainformation</I> that <I>describes</I> the document then you should
396: use the <CODE>HEAD</CODE> method in your request.
2.79 frystyk 397: <H3>
2.87 frystyk 398: Get Metainformation about a Document from Absolute URI
2.79 frystyk 399: </H3>
400: <P>
401: Request metainfomration about a document referencd by an <I>absolute</I>
2.87 frystyk 402: URI.
2.79 frystyk 403: <PRE>extern BOOL HTHeadAbsolute (const char * url, HTRequest * request);
404: </PRE>
405: <H3>
2.87 frystyk 406: Get Metainformation about a Document from Relative URI
2.79 frystyk 407: </H3>
408: <P>
409: Request metainformation about a document referenced by a <I>relative</I>
2.87 frystyk 410: URI.
2.79 frystyk 411: <PRE>extern BOOL HTHeadRelative (const char * relative,
412: HTParentAnchor * base,
413: HTRequest * request);
414: </PRE>
415: <H3>
416: Get Metainformation about a Document using an Anchor
417: </H3>
418: <P>
2.87 frystyk 419: Here the URI is represented by an <A HREF="HTAnchor.html">Anchor object</A>.
420: You can get an anchor object representing a URI by passing the URI to the
2.79 frystyk 421: approproiate method in the <A HREF="HTAnchor.html">Anchor class</A>.
422: <PRE>extern BOOL HTHeadAnchor (HTAnchor * anchor, HTRequest * request);
423: </PRE>
424: <H2>
2.80 frystyk 425: <A NAME="Delete">Delete a Document (Method = DELETE)</A>
2.79 frystyk 426: </H2>
427: <P>
428: If you want to delete a document (or make the document inaccessible for future
429: references) then you can use the <CODE>DELETE</CODE> method in your request.
430: <H3>
2.87 frystyk 431: Delete a Document from Absolute URI
2.79 frystyk 432: </H3>
433: <P>
434: Request metainfomration about a document referencd by an <I>absolute</I>
2.87 frystyk 435: URI.
2.79 frystyk 436: <PRE>extern BOOL HTDeleteAbsolute (const char * url, HTRequest * request);
437: </PRE>
438: <H3>
2.87 frystyk 439: Delete a Document from Relative URI
2.79 frystyk 440: </H3>
441: <P>
442: Request metainformation about a document referenced by a <I>relative</I>
2.87 frystyk 443: URI.
2.79 frystyk 444: <PRE>extern BOOL HTDeleteRelative (const char * relative,
445: HTParentAnchor * base,
446: HTRequest * request);
447: </PRE>
448: <H3>
449: Delete a Document using an Anchor
450: </H3>
451: <P>
2.87 frystyk 452: Here the URI is represented by an <A HREF="HTAnchor.html">Anchor object</A>.
453: You can get an anchor object representing a URI by passing the URI to the
2.79 frystyk 454: approproiate method in the <A HREF="HTAnchor.html">Anchor class</A>.
455: <PRE>extern BOOL HTDeleteAnchor (HTAnchor * anchor, HTRequest * request);
456: </PRE>
457: <H2>
2.87 frystyk 458: <A NAME="SaveASIS">Save a Document ASIS From Memory (Method = PUT)</A>
2.80 frystyk 459: </H2>
460: <P>
2.87 frystyk 461: If you already have a document in memory and it is associated with an
462: <A HREF="HTAnchor.html">Anchor object</A> then you can PUT this document
463: to a remote server using the following methods. Other information that you
464: can set in the anchor is metadata like the media type, the document length,
465: the language, or any other information that you want to associate with the
466: document to be uploaded.
467: <P>
468: This set of functions takes the document <B>ASIS</B> - that it the
469: <I>exact</I> content of the document associated with this anchor will be
470: sent to the remote server. If your anchor represents a structured content
2.80 frystyk 471: and the document itself is a parse tree, for example, then you can use the
2.87 frystyk 472: <A HREF="#SaveStructured">structured PUT functions</A>.
2.80 frystyk 473: <P>
2.87 frystyk 474: If your application is an editor, then you may want to create a new anchor
2.80 frystyk 475: on the fly for temporary backups on local disk before you save it to a remote
2.87 frystyk 476: server. An easy way to get a new anchor with a local file URI is to use the
477: <A HREF="HTHome.html#temp">HTTmpAnchor</A> function which is part of the
478: <A HREF="WWWApp.html">WWWApp interface</A>.
2.80 frystyk 479: <H3>
2.87 frystyk 480: Save a Document ASIS from Memory Using Absolute URI (PUT)
2.80 frystyk 481: </H3>
482: <P>
2.87 frystyk 483: The source is an anchor with the contents already in memory and the destination
484: is an absolute URI.
2.80 frystyk 485: <PRE>
486: extern BOOL HTPutAbsolute (HTParentAnchor * source,
487: const char * destination,
488: HTRequest * request);
489: </PRE>
490: <H3>
2.87 frystyk 491: Save a Document ASIS from Memory Using Relative URI (PUT)
2.80 frystyk 492: </H3>
493: <P>
2.87 frystyk 494: The source is an anchor with the contents already in memory and the destination
495: is a relative URI relative to the destination anchor
2.80 frystyk 496: <PRE>
497: extern BOOL HTPutRelative (HTParentAnchor * source,
498: const char * relative,
499: HTParentAnchor * destination_base,
500: HTRequest * request);
501: </PRE>
502: <H3>
2.87 frystyk 503: Save a Document ASIS from Memory Using an Anchor (PUT)
2.80 frystyk 504: </H3>
505: <P>
2.87 frystyk 506: Both the source and the anchor are anchor objects. The source anchor already
507: has the contents in memory
2.80 frystyk 508: <PRE>
509: extern BOOL HTPutAnchor (HTParentAnchor * source,
510: HTAnchor * dest,
511: HTRequest * request);
512: </PRE>
513: <H2>
514: <A NAME="SaveStructured">Save a Structured Document (Using PUT)</A>
2.77 frystyk 515: </H2>
2.80 frystyk 516: <P>
2.87 frystyk 517: If you want to save a document from memory but it contains structured information
518: (for example, it is in the form of a parse tree) then you can use this interface.
519: The only difference from above is that the caller must provide the function
520: that provides data while sending it accross the network - we can't just take
521: it as a block. You can for example have a look at the
522: <CODE>HTEntity_callback</CODE> function which is used in the
523: <A HREF="#SaveASIS"><B>ASIS</B> interface</A> if you want to write your own
524: data feeding method.
525: <H3>
526: Save a Structured Document from Memory to Absolute URI (PUT)
527: </H3>
528: <P>
529: Upload a document referenced by an absolute URI.
2.80 frystyk 530: <PRE>
531: extern BOOL HTPutStructuredAbsolute (HTParentAnchor * source,
532: const char * destination,
533: HTRequest * request,
534: HTPostCallback * input);
535: </PRE>
536: <H3>
2.87 frystyk 537: Save a Structured Document from Memory to Relative URI (PUT)
2.80 frystyk 538: </H3>
539: <P>
2.87 frystyk 540: The source is an anchor with the contents already in memory and the destination
541: is a relative URI relative to the destination anchor
2.80 frystyk 542: <PRE>
543: extern BOOL HTPutStructuredRelative (HTParentAnchor * source,
544: const char * relative,
545: HTParentAnchor * destination_base,
546: HTRequest * request,
547: HTPostCallback * input);
548: </PRE>
549: <H3>
550: Save a Structured Document Using an Anchor and the PUT Method
551: </H3>
552: <P>
2.87 frystyk 553: The source is an anchor with the contents already in memory and the destination
554: is a relative URI. The HTPostCallback function type is declared in the HTRequest
2.80 frystyk 555: object.
556: <PRE>
557: extern BOOL HTPutStructuredAnchor (HTParentAnchor * source,
558: HTAnchor * destination,
559: HTRequest * request,
560: HTPostCallback * input);
561: </PRE>
562: <H2>
2.87 frystyk 563: <A NAME="SaveURL">Save a Remote Document (Using PUT)</A>
2.80 frystyk 564: </H2>
565: <P>
2.87 frystyk 566: If the content of the document associated with the anchor is <B>NOT</B> in
567: memory then you can use this interface. These methods make two requests:
568: first they go out and get the source which can be on an FTP server, on local
569: disk, on another HTTP server etc. and then they PUT this document ASIS to
570: the destination HTTP server.
2.80 frystyk 571: <H3>
2.87 frystyk 572: Save a Document from Absolute URI using PUT
2.80 frystyk 573: </H3>
574: <P>
2.87 frystyk 575: Get the source and PUT it to the destination which is an absolute URI
2.80 frystyk 576: <PRE>
577: extern BOOL HTPutDocumentAbsolute (HTParentAnchor * source,
578: const char * destination,
579: HTRequest * request);
580: </PRE>
581: <H3>
2.87 frystyk 582: Save a Document from Relative URI using PUT
2.80 frystyk 583: </H3>
584: <P>
2.87 frystyk 585: Get the source and PUT it to the destination which is a relative URI
2.80 frystyk 586: <PRE>
587: extern BOOL HTPutDocumentRelative (HTParentAnchor * source,
588: const char * relative,
589: HTParentAnchor * destination_base,
590: HTRequest * request);
591: </PRE>
592: <H3>
593: Save a Document Using an Anchor and the PUT Method
594: </H3>
595: <P>
2.87 frystyk 596: Get the source and PUT it to the destination which is an anchor object.
2.80 frystyk 597: <PRE>
598: extern BOOL HTPutDocumentAnchor (HTParentAnchor * source,
599: HTAnchor * destination,
600: HTRequest * request);
601: </PRE>
602: <H2>
2.87 frystyk 603: <A NAME="PostASIS">Post a Document from Memory ASIS (Method = POST)</A>
2.81 frystyk 604: </H2>
605: <P>
2.87 frystyk 606: If you already have a document in memory and it is associated with an
607: <A HREF="HTAnchor.html">Anchor object</A> then you can POST this document
608: to a remote server using the following methods. Other information that you
609: can set in the anchor is metadata like the media type, the document length,
610: the language, or any other information that you want to associate with the
611: document to be uploaded.
2.81 frystyk 612: <P>
2.87 frystyk 613: This set of functions takes the document <B>ASIS</B> - that it the
614: <I>exact</I> content of the document associated with this anchor will be
615: sent to the remote server.
2.81 frystyk 616: <P>
2.87 frystyk 617: If your application is an editor, then you may want to create a new anchor
2.81 frystyk 618: on the fly for temporary backups on local disk before you save it to a remote
2.87 frystyk 619: server. An easy way to get a new anchor with a local file URI is to use the
620: <A HREF="HTHome.html#temp">HTTmpAnchor</A> function which is part of the
621: <A HREF="WWWApp.html">WWWApp interface</A>.
2.81 frystyk 622: <H3>
2.87 frystyk 623: Post a Document from Memory ASIS using Absolute URI (POST)
2.81 frystyk 624: </H3>
625: <P>
2.87 frystyk 626: Upload a document using POST referenced by an absolute URI.
2.81 frystyk 627: <PRE>
628: extern BOOL HTPostAbsolute (HTParentAnchor * source,
629: const char * destination,
630: HTRequest * request);
631: </PRE>
632: <H3>
2.87 frystyk 633: Post a Document from Memory ASIS using Relative URI (POST)
2.81 frystyk 634: </H3>
635: <P>
2.87 frystyk 636: Upload a document using POST referenced by a relative URI.
2.81 frystyk 637: <PRE>
638: extern BOOL HTPostRelative (HTParentAnchor * source,
639: const char * relative,
640: HTParentAnchor * destination_base,
641: HTRequest * request);
642: </PRE>
643: <H3>
2.87 frystyk 644: Post a Document from Memory ASIS using an Anchor (POST)
2.81 frystyk 645: </H3>
646: <P>
2.87 frystyk 647: POST an anchor - here both the source and the anchor are anchor objects.
648: The source anchor already has the contents in memory.
2.81 frystyk 649: <PRE>
650: extern BOOL HTPostAnchor (HTParentAnchor * source,
651: HTAnchor * dest,
652: HTRequest * request);
653: </PRE>
654: <H2>
2.87 frystyk 655: <A NAME="OPTIONS">Get Available Options for a Document (Method = OPTIONS)</A>
2.80 frystyk 656: </H2>
657: <P>
658: If you want to get information about a document then you can use the the
659: <CODE>OPTIONS</CODE> method in your request. The <CODE>OPTIONS</CODE> method
660: represents a request for information about the communication options available
2.82 frystyk 661: on the request/response chain identified by the <CODE>Request-URI</CODE>.
662: This method allows the client to determine the options and/or requirements
663: associated with a resource, or the capabilities of a server, without implying
664: a resource action or initiating a resource retrieval.
665: <P>
666: A speciality about the <CODE>OPTIONS</CODE> method is that the client can
667: issue a request with no pathinfo at all but only with a "<CODE>*</CODE>".
668: That is, the request line can look like this "<CODE>OPTIONS * HTTP/1.1</CODE>".
669: This means that we request information about the server as a whole and not
2.87 frystyk 670: only about a single URI. You can get this effect by using a URI containing
2.82 frystyk 671: the hostname alone with <B>NO</B> extra slash at the end, for example
672: <CODE>http://www.w3.org</CODE>, <CODE>http://www.cern.ch</CODE>.
2.80 frystyk 673: <H3>
2.87 frystyk 674: Options Available for Document from Absolute URI
2.80 frystyk 675: </H3>
676: <P>
2.87 frystyk 677: Request options about a document referencd by an <I>absolute</I> URI.
2.80 frystyk 678: <PRE>extern BOOL HTOptionsAbsolute (const char * url, HTRequest * request);
679: </PRE>
680: <H3>
2.87 frystyk 681: Options Available for Document from Relative URI
2.80 frystyk 682: </H3>
683: <P>
2.87 frystyk 684: Request options about a document referenced by a <I>relative</I> URI.
2.80 frystyk 685: <PRE>extern BOOL HTOptionsRelative (const char * relative,
686: HTParentAnchor * base,
687: HTRequest * request);
688: </PRE>
689: <H3>
690: Options Available for Document using an Anchor
691: </H3>
692: <P>
2.87 frystyk 693: Here the URI is represented by an <A HREF="HTAnchor.html">Anchor object</A>.
694: You can get an anchor object representing a URI by passing the URI to the
2.80 frystyk 695: appropriate method in the <A HREF="HTAnchor.html">Anchor class</A>.
696: <PRE>extern BOOL HTOptionsAnchor (HTAnchor * anchor, HTRequest * request);
697: </PRE>
698: <H2>
2.87 frystyk 699: <A NAME="TRACE">Get Trace Loop back Information for a Document (Method =
700: TRACE)</A>
2.82 frystyk 701: </H2>
702: <P>
703: The TRACE method is used to invoke a remote, application-layer loop-back
704: of the request message. The final recipient of the request SHOULD reflect
705: the message received back to the client as the entity-body of a 200 (OK)
706: response. The final recipient is either the origin server or the first proxy
707: or gateway to receive a Max-Forwards value of zero (0) in the request (see
708: section 14.31). A TRACE request MUST NOT include an entity.
709: <P>
710: TRACE allows the client to see what is being received at the other end of
711: the request chain and use that data for testing or diagnostic information.
712: The value of the Via header field (section 14.44) is of particular interest,
713: since it acts as a trace of the request chain. Use of the Max-Forwards header
714: field allows the client to limit the length of the request chain, which is
715: useful for testing a chain of proxies forwarding messages in an infinite
716: loop.
717: <P>
718: If successful, the response SHOULD contain the entire request message in
719: the entity-body, with a Content-Type of <CODE>"message/http"</CODE>. Responses
720: to this method MUST NOT be cached.
721: <H3>
2.87 frystyk 722: Traces Available for Document from Absolute URI
2.82 frystyk 723: </H3>
724: <P>
2.87 frystyk 725: Request traces about a document referencd by an <I>absolute</I> URI.
2.82 frystyk 726: <PRE>extern BOOL HTTraceAbsolute (const char * url, HTRequest * request);
727: </PRE>
728: <H3>
2.87 frystyk 729: Traces Available for Document from Relative URI
2.82 frystyk 730: </H3>
731: <P>
2.87 frystyk 732: Request traces about a document referenced by a <I>relative</I> URI.
2.82 frystyk 733: <PRE>extern BOOL HTTraceRelative (const char * relative,
734: HTParentAnchor * base,
735: HTRequest * request);
736: </PRE>
737: <H3>
738: Traces Available for Document using an Anchor
739: </H3>
740: <P>
2.87 frystyk 741: Here the URI is represented by an <A HREF="HTAnchor.html">Anchor object</A>.
742: You can get an anchor object representing a URI by passing the URI to the
2.82 frystyk 743: appropriate method in the <A HREF="HTAnchor.html">Anchor class</A>.
744: <PRE>extern BOOL HTTraceAnchor (HTAnchor * anchor, HTRequest * request);
745: </PRE>
746: <H2>
2.89 frystyk 747: <A NAME="serve">Serve a Request</A>
2.88 frystyk 748: </H2>
749: <P>
750: Although libwww is primarily for clients, it is in fact symmetric in that
751: it can handle both client requests and server requests. The way this is handled
752: is that each <A HREF="HTProt.html">protocol</A> is registered with both a
753: client handler and a server handler - depending on which type of request
754: you use, one of them is called. Note that in order to be able to serve any
755: document, there actually have to be a server handler. However, libwww only
756: comes with a <A HREF="HTSocket.html">raw socket loader</A> which isn't much
757: of a server. There is an <A HREF="HTTPServ.html">attempt of an HTTP server</A>
758: but it is not complete
759: <P>
760: The protocol handler used to serve the request is determined by the URI -
761: just as for client side requests. That is, libwww can in fact simultaneously
762: be the server for multiple protocols if you really want to. Examples of URIs
763: that you can use are <TT>noop://localhost:8888</TT> which means that libwww
764: starts listening on port 8888 (see the <A HREF="../Examples/listen.c">listen
765: example</A> for details). Other examples are <TT>http://localhost:7777</TT>
766: which means that it listens for HTTP on port 7777. Again, there is no HTTP
767: server in libwww - this is just an example.
768: <PRE>
769: extern BOOL HTServeAbsolute (const char * address, HTRequest * request);
770: </PRE>
771: <H2>
2.87 frystyk 772: Save a URI To Multiple Destinations - Not supported!!!
2.80 frystyk 773: </H2>
774: <P>
2.87 frystyk 775: <STRONG>Note: This is no longer supported</STRONG>
2.80 frystyk 776: <P>
777: These are the generic versions of the <CODE>PUT</CODE> and <CODE>POST</CODE>
778: functions. They can be used to send documents to multiple destinations
779: simultanously using the PostWeb model.
2.77 frystyk 780: <H3>
2.87 frystyk 781: Copy an anchor - not supported
2.77 frystyk 782: </H3>
783: <P>
2.87 frystyk 784: Fetch the URI from either local file store <B>or</B> from a remote HTTP server
2.77 frystyk 785: and send it using either PUT or POST to the remote destination using HTTP.
786: The caller can decide the exact method used and which HTTP header fields
787: to transmit by setting the user fields in the request structure. If posting
788: to NNTP then we can't dispatch at this level but must pass the source anchor
789: to the news module that then takes all the refs to NNTP and puts into the
790: "newsgroups" header Returns YES if request accepted, else NO
2.78 frystyk 791: <PRE>extern BOOL HTCopyAnchor (HTAnchor * src_anchor, HTRequest * main_req);
2.47 frystyk 792: </PRE>
2.77 frystyk 793: <H3>
2.87 frystyk 794: Upload an Anchor - not supported
2.77 frystyk 795: </H3>
796: <P>
797: This function can be used to send data along with a request to a remote server.
798: It can for example be used to POST form data to a remote HTTP server - or
799: it can be used to post a newsletter to a NNTP server. In either case, you
800: pass a callback function which the request calls when the remote destination
801: is ready to accept data. In this callback you get the current request object
802: and a stream into where you can write data. It is very important that you
803: return the value returned by this stream to the Library so that it knows
804: what to do next. The reason is that the outgoing stream might block or an
805: error may occur and in that case the Library must know about it. If you do
2.71 frystyk 806: not want to handle the stream interface yourself then you can use the
2.79 frystyk 807: <CODE>HTUpload_callback</CODE> which is declared below. The source anchor
808: represents the data object in memory and it points to the destination anchor
809: by using the <A HREF="../User/Architecture/PostWeb.html">POSTWeb method</A>.
810: The source anchor contains metainformation about the data object in memory
811: and the destination anchor represents the reponse from the remote server.
812: Returns YES if request accepted, else NO
2.78 frystyk 813: <PRE>extern BOOL HTUploadAnchor (HTAnchor * source_anchor,
2.71 frystyk 814: HTRequest * request,
815: HTPostCallback * callback);
816: </PRE>
2.77 frystyk 817: <H3>
2.87 frystyk 818: POST Callback Handler - not supported
2.77 frystyk 819: </H3>
820: <P>
821: Is you do not want to handle the stream interface on your own, you can use
822: this "middleman" function which does the actual writing to the target stream
823: for the anchor upload and also handles the return value from the stream.
824: Now, your application is called via the callback function that you may associate
825: with a request object. You indicate when you have sent all the data you want
826: by returning HT_LOADED from the callback.
2.43 frystyk 827: <PRE>
2.72 frystyk 828: extern int HTUpload_callback (HTRequest * request, HTStream * target);
2.46 frystyk 829: </PRE>
2.25 luotonen 830: <PRE>
2.90 ! vbancrof 831: #ifdef __cplusplus
! 832: }
! 833: #endif
! 834:
2.63 frystyk 835: #endif /* HTACCESS_H */
2.38 howcome 836: </PRE>
2.77 frystyk 837: <P>
838: <HR>
2.75 frystyk 839: <ADDRESS>
2.90 ! vbancrof 840: @(#) $Id: HTAccess.html,v 2.89 1998/12/17 01:51:01 frystyk Exp $
2.75 frystyk 841: </ADDRESS>
2.77 frystyk 842: </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