Annotation of libwww/Library/src/HTAccess.html, revision 2.80
2.9 timbl 1: <HTML>
2: <HEAD>
2.79 frystyk 3: <!-- Changed by: Henrik Frystyk Nielsen, 15-Jul-1996 -->
2.78 frystyk 4: <TITLE>W3C Reference 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
26: is a part of the <A HREF="http://www.w3.org/pub/WWW/Library/"> W3C Reference
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>
! 549: Get Available Options for a Document (Method = OPTIONS)
! 550: </H2>
! 551: <P>
! 552: If you want to get information about a document then you can use the the
! 553: <CODE>OPTIONS</CODE> method in your request. The <CODE>OPTIONS</CODE> method
! 554: represents a request for information about the communication options available
! 555: on the request/response chain identified by the Request-URI. This method
! 556: allows the client to determine the options and/or requirements associated
! 557: with a resource, or the capabilities of a server, without implying a resource
! 558: action or initiating a resource retrieval.
! 559: <H3>
! 560: Options Available for Document from Absolute URL
! 561: </H3>
! 562: <P>
! 563: Request options about a document referencd by an <I>absolute</I> URL.
! 564: <PRE>extern BOOL HTOptionsAbsolute (const char * url, HTRequest * request);
! 565: </PRE>
! 566: <H3>
! 567: Options Available for Document from Relative URL
! 568: </H3>
! 569: <P>
! 570: Request options about a document referenced by a <I>relative</I> URL.
! 571: <PRE>extern BOOL HTOptionsRelative (const char * relative,
! 572: HTParentAnchor * base,
! 573: HTRequest * request);
! 574: </PRE>
! 575: <H3>
! 576: Options Available for Document using an Anchor
! 577: </H3>
! 578: <P>
! 579: Here the URL is represented by an <A HREF="HTAnchor.html">Anchor object</A>.
! 580: You can get an anchor object representing a URL by passing the URL to the
! 581: appropriate method in the <A HREF="HTAnchor.html">Anchor class</A>.
! 582: <PRE>extern BOOL HTOptionsAnchor (HTAnchor * anchor, HTRequest * request);
! 583: </PRE>
! 584: <H2>
! 585: Save a URL To Multiple Destinations
! 586: </H2>
! 587: <P>
! 588: <I><B>Note:</B> This is not as stable as the other functions yet!</I>
! 589: <P>
! 590: These are the generic versions of the <CODE>PUT</CODE> and <CODE>POST</CODE>
! 591: functions. They can be used to send documents to multiple destinations
! 592: simultanously using the PostWeb model.
2.77 frystyk 593: <H3>
594: Copy an anchor
595: </H3>
596: <P>
597: Fetch the URL from either local file store <B>or</B> from a remote HTTP server
598: and send it using either PUT or POST to the remote destination using HTTP.
599: The caller can decide the exact method used and which HTTP header fields
600: to transmit by setting the user fields in the request structure. If posting
601: to NNTP then we can't dispatch at this level but must pass the source anchor
602: to the news module that then takes all the refs to NNTP and puts into the
603: "newsgroups" header Returns YES if request accepted, else NO
2.78 frystyk 604: <PRE>extern BOOL HTCopyAnchor (HTAnchor * src_anchor, HTRequest * main_req);
2.47 frystyk 605: </PRE>
2.77 frystyk 606: <H3>
607: Upload an Anchor
608: </H3>
609: <P>
610: This function can be used to send data along with a request to a remote server.
611: It can for example be used to POST form data to a remote HTTP server - or
612: it can be used to post a newsletter to a NNTP server. In either case, you
613: pass a callback function which the request calls when the remote destination
614: is ready to accept data. In this callback you get the current request object
615: and a stream into where you can write data. It is very important that you
616: return the value returned by this stream to the Library so that it knows
617: what to do next. The reason is that the outgoing stream might block or an
618: error may occur and in that case the Library must know about it. If you do
2.71 frystyk 619: not want to handle the stream interface yourself then you can use the
2.79 frystyk 620: <CODE>HTUpload_callback</CODE> which is declared below. The source anchor
621: represents the data object in memory and it points to the destination anchor
622: by using the <A HREF="../User/Architecture/PostWeb.html">POSTWeb method</A>.
623: The source anchor contains metainformation about the data object in memory
624: and the destination anchor represents the reponse from the remote server.
625: Returns YES if request accepted, else NO
2.78 frystyk 626: <PRE>extern BOOL HTUploadAnchor (HTAnchor * source_anchor,
2.71 frystyk 627: HTRequest * request,
628: HTPostCallback * callback);
629: </PRE>
2.77 frystyk 630: <H3>
631: POST Callback Handler
632: </H3>
633: <P>
634: Is you do not want to handle the stream interface on your own, you can use
635: this "middleman" function which does the actual writing to the target stream
636: for the anchor upload and also handles the return value from the stream.
637: Now, your application is called via the callback function that you may associate
638: with a request object. You indicate when you have sent all the data you want
639: by returning HT_LOADED from the callback.
2.43 frystyk 640: <PRE>
2.72 frystyk 641: extern int HTUpload_callback (HTRequest * request, HTStream * target);
2.46 frystyk 642: </PRE>
2.25 luotonen 643: <PRE>
2.63 frystyk 644: #endif /* HTACCESS_H */
2.38 howcome 645: </PRE>
2.77 frystyk 646: <P>
647: <HR>
2.75 frystyk 648: <ADDRESS>
2.80 ! frystyk 649: @(#) $Id: HTAccess.html,v 2.79 1996/07/16 02:26:37 frystyk Exp $
2.75 frystyk 650: </ADDRESS>
2.77 frystyk 651: </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