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