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