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