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