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