Annotation of libwww/Library/src/HTFormat.html, revision 2.69
2.10 timbl 1: <HTML>
2: <HEAD>
2.69 ! frystyk 3: <!-- Changed by: Henrik Frystyk Nielsen, 15-Jul-1996 -->
2.68 frystyk 4: <TITLE>W3C Reference Library libwww Stream Pipe Manager</TITLE>
2.10 timbl 5: </HEAD>
2.1 timbl 6: <BODY>
2.67 frystyk 7: <H1>
2.68 frystyk 8: The Stream Pipe Manager
2.67 frystyk 9: </H1>
2.33 frystyk 10: <PRE>
11: /*
2.41 frystyk 12: ** (c) COPYRIGHT MIT 1995.
2.33 frystyk 13: ** Please first read the full copyright statement in the file COPYRIGH.
14: */
15: </PRE>
2.67 frystyk 16: <P>
2.68 frystyk 17: The Stream Pipe Manager is responsible for setting up the stream pipe from
18: the <A HREF="HTChannl.html">Channel Object</A> to the
19: <A HREF="HTReq.html">Request Object</A> when data is arriving, for example
20: as a response to s <A HREF="HTTP.html">HTTP</A> <B>Get</B> request. As data
21: arrives, we start to parse it and the more we know the more we can build
22: up our stream pipe. For example, in the case of HTTP, we first have a stream
23: that can parse the HTTP response line containing "<CODE>200 OK</CODE>". Then
24: we have a <A HREF="HTMIME.html">MIME parser</A> for handling the MIME headers.
25: When the MIME headers have been parsed, we know the content type and any
26: encoding of the MIME body. If we need to decode a chunked encoding then we
27: set up a chunked decoder, and if we have to parse a HTML object then we set
28: up a HTML parser.
2.67 frystyk 29: <P>
30: The Format Manager is also responsible for keeping track of the
31: "<I>preferences</I>" of the application and/or user. It is an integral part
32: of the Web and HTTP, that the client application can express its preferences
33: as a set of "accept" headers in a HTTP request. This task is highly related
34: to the task mentioned above as we there use the modules that are registered
35: and here tell the remote server what we are capable of doing and what we
36: would prefer.
37: <P>
38: <B>Note</B>: The library <B>core</B> does not define any default decoders
39: or parsers - they are all considered part of the application. The library
40: comes with a default set of parsers including the ones mentioned above which
41: can be initiated using the functions in <A HREF="HTInit.html">HTInit
42: module</A>. There are different initialization functions for content type
43: parsers and content encodings respectively.
44: <P>
45: Currently there are four dimensions for handling "accept" headers:
46: <P>
47: <UL>
48: <LI>
49: <A HREF="#type">Content Type Converters and Presenters</A>
50: <LI>
51: <A HREF="#encoding">Content Encoders and Decoders</A>
52: <LI>
53: <A HREF="#charset">Content Charsets</A>
54: <LI>
55: <A HREF="#language">Natural Languages</A>
56: </UL>
57: <P>
58: The application can assign its preferences in two ways: either <I>locally</I>
59: to a single request or <I>globally</I> to all requests. The local assignment
60: can either <I>add to </I>or <I>override</I> the global settings depending
61: on how they are registered. All local registration is handled by the
62: <A HREF="HTReq.html">Request Object</A> and the global registration is handled
63: by the Format Manager
64: <P>
65: <UL>
66: <LI>
67: <A HREF="#global">Global Preferences</A>
68: </UL>
69: <P>
70: When data is arriving and the Format Manager is to build a stream pipe from
71: the <A HREF="HTChannl.html">HTChannel Object</A> to the
72: <A HREF="HTReq.html">Request Object</A>, it uses a special set of <I>stream
73: stack algorithms</I>. These algorithms take the complete set of content type
74: converters, for example, and finds the one best suited for the task. We currently
75: have three stream stack algorithms: one for content types, one for content
76: encodings, and one for content transfer encodings:
77: <P>
78: <UL>
79: <LI>
80: <A HREF="#CTStack">The Content Type Stream Stack</A>
81: <LI>
82: <A HREF="#CEStack">The Content Encoding Stream Stack</A>
83: <LI>
84: <A HREF="#CTEStack">The Content Transfer Encoding Stream Stack</A>
85: </UL>
86: <P>
87: This module is implemented by <A HREF="HTFormat.c">HTFormat.c</A>, and it
88: is a part of the <A HREF="http://www.w3.org/pub/WWW/Library/">W3C Reference
89: Library</A>.
2.31 frystyk 90: <PRE>
91: #ifndef HTFORMAT_H
2.1 timbl 92: #define HTFORMAT_H
93:
2.63 frystyk 94: #include "<A HREF="HTUtils.html">HTUtils.h</A>"
95: #include "<A HREF="HTStream.html">HTStream.h</A>"
96: #include "<A HREF="HTAtom.html">HTAtom.h</A>"
97: #include "<A HREF="HTList.html">HTList.h</A>"
98: #include "<A HREF="HTAnchor.html">HTAnchor.h</A>"
99: #include "<A HREF="HTReq.html">HTReq.h</A>"
2.31 frystyk 100: </PRE>
2.67 frystyk 101: <H2>
102: <A NAME="type">Content Type Converters and Presenters</A>
103: </H2>
104: <P>
105: All content type converters are subclassed from the Generic stream objetc.
106: That way, we allow the application to do very fast progressive display of
107: incoming data. In other words, the stream model of the Library provides data
108: as soon as it arrives from the network, the application does not have to
109: wait until the whole document has been down loaded before it starts parsing
110: it.
111: <H3>
112: Content Type Converters
113: </H3>
114: <P>
115: A <CODE>converter</CODE> is a stream with a special set of parameters and
116: which is registered as capable of converting from a MIME type to something
117: else (maybe another MIME-type). A converter is defined to be a function returning
118: a stream and accepting the following parameters. The content type elements
119: are atoms for which we have defined a prototype.
2.31 frystyk 120: <PRE>
2.52 frystyk 121: typedef HTStream * HTConverter (HTRequest * request,
122: void * param,
123: HTFormat input_format,
124: HTFormat output_format,
125: HTStream * output_stream);
2.42 frystyk 126: </PRE>
2.67 frystyk 127: <H3>
128: The HTPresentation Object
129: </H3>
130: <P>
131: A <CODE>presenter</CODE> is a module (possibly an external program) which
132: can present a graphic object of a certain MIME type to the user. That is,
133: <CODE>presenters</CODE> are normally used to present objects that the
134: <CODE>converters</CODE> are not able to handle. Data is transferred to the
135: external program using for example the
136: <A HREF="HTFWrite.html">HTSaveAndExecute</A> stream which writes to a local
137: file. Both presenters and converters are of the type
138: <A HREF="#converter">HTConverter</A>.
2.31 frystyk 139: <PRE>
2.42 frystyk 140: typedef struct _HTPresentation {
141: HTFormat rep; /* representation name atomized */
142: HTFormat rep_out; /* resulting representation */
143: HTConverter *converter; /* The routine to gen the stream stack */
144: char * command; /* MIME-format string */
145: char * test_command; /* MIME-format string */
146: double quality; /* Between 0 (bad) and 1 (good) */
147: double secs;
148: double secs_per_byte;
149: } HTPresentation;
2.28 frystyk 150: </PRE>
2.67 frystyk 151: <H3>
152: Basic Content type Converters
153: </H3>
154: <P>
155: We have a small set of basic converters that can be hooked in anywhere. They
156: don't "convert" anything but are nice to have.
157: <PRE>extern HTConverter HTThroughLine;
2.63 frystyk 158: extern HTConverter HTBlackHoleConverter;
159: </PRE>
2.67 frystyk 160: <H3>
161: Predefined Content Types
162: </H3>
163: <P>
164: These macros (which used to be constants) define some basic internally referenced
165: representations. The <CODE>www/xxx</CODE> ones are of course not MIME standard.
166: They are internal representations used in the Library but they can't be exported
167: to other apps!
2.28 frystyk 168: <PRE>
2.57 frystyk 169: #define WWW_RAW HTAtom_for("www/void") /* Raw output from Protocol */
2.28 frystyk 170: </PRE>
2.67 frystyk 171: <P>
172: <CODE>WWW_RAW</CODE> is an output format which leaves the input untouched
173: <EM>exactly</EM> as it is received by the protocol module. For example, in
174: the case of FTP, this format returns raw ASCII objects for directory listings;
175: for HTTP, everything including the header is returned, for Gopher, a raw
176: ASCII object is returned for a menu etc.
177: <PRE>
178: #define WWW_SOURCE HTAtom_for("*/*")
179: </PRE>
180: <P>
181: <CODE>WWW_SOURCE</CODE> is an output format which leaves the input untouched
182: <EM>exactly</EM> as it is received by the protocol module <B>IF</B> not a
183: suitable converter has been registered with a quality factor higher than
184: 1 (for example 2). In this case the <EM>SUPER CONVERTER</EM> is preferred
185: for the raw output. This can be used as a filter effect that allows conversion
186: from, for example raw FTPdirectory listings into HTML but passes a MIME body
187: untouched.
188: <PRE>
189: #define WWW_PRESENT HTAtom_for("www/present")
190: </PRE>
191: <P>
192: <CODE>WWW_PRESENT</CODE> represents the user's perception of the document.
193: If you convert to <CODE>WWW_PRESENT</CODE>, you present the material to the
194: user.
2.58 frystyk 195: <PRE>
196: #define WWW_DEBUG HTAtom_for("www/debug")
197: </PRE>
2.67 frystyk 198: <P>
199: <CODE>WWW_DEBUG</CODE> represents the user's perception of debug information,
200: for example sent as a HTML document in a HTTP redirection message.
2.28 frystyk 201: <PRE>
2.52 frystyk 202: #define WWW_UNKNOWN HTAtom_for("www/unknown")
2.28 frystyk 203: </PRE>
2.67 frystyk 204: <P>
205: <CODE>WWW_UNKNOWN</CODE> is a really unknown type. It differs from the real
206: MIME type <EM>"application/octet-stream"</EM> in that we haven't even tried
207: to figure out the content type at this point.
208: <P>
2.31 frystyk 209: These are regular MIME types defined. Others can be added!
2.28 frystyk 210: <PRE>
2.52 frystyk 211: #define WWW_HTML HTAtom_for("text/html")
2.28 frystyk 212: #define WWW_PLAINTEXT HTAtom_for("text/plain")
2.69 ! frystyk 213: #define WWW_FORM HTAtom_for("application/x-www-form-urlencoded")
2.52 frystyk 214:
215: #define WWW_MIME HTAtom_for("message/rfc822")
2.60 frystyk 216: #define WWW_MIME_HEAD HTAtom_for("message/x-rfc822-head")
2.65 frystyk 217: #define WWW_MIME_FOOT HTAtom_for("message/x-rfc822-foot")
2.52 frystyk 218:
2.10 timbl 219: #define WWW_AUDIO HTAtom_for("audio/basic")
2.52 frystyk 220:
2.26 frystyk 221: #define WWW_VIDEO HTAtom_for("video/mpeg")
2.52 frystyk 222:
2.66 frystyk 223: #define WWW_GIF HTAtom_for("image")
2.63 frystyk 224: #define WWW_JPEG HTAtom_for("image/jpeg")
225: #define WWW_TIFF HTAtom_for("image/tiff")
2.52 frystyk 226: #define WWW_PNG HTAtom_for("image/png")
227:
228: #define WWW_BINARY HTAtom_for("application/octet-stream")
229: #define WWW_POSTSCRIPT HTAtom_for("application/postscript")
230: #define WWW_RICHTEXT HTAtom_for("application/rtf")
2.48 frystyk 231: </PRE>
2.67 frystyk 232: <P>
233: We also have some MIME types that come from the various protocols when we
234: convert from ASCII to HTML.
2.48 frystyk 235: <PRE>
236: #define WWW_GOPHER_MENU HTAtom_for("text/x-gopher")
2.53 frystyk 237: #define WWW_CSO_SEARCH HTAtom_for("text/x-cso")
2.48 frystyk 238:
239: #define WWW_FTP_LNST HTAtom_for("text/x-ftp-lnst")
240: #define WWW_FTP_LIST HTAtom_for("text/x-ftp-list")
241:
242: #define WWW_NNTP_LIST HTAtom_for("text/x-nntp-list")
243: #define WWW_NNTP_OVER HTAtom_for("text/x-nntp-over")
244: #define WWW_NNTP_HEAD HTAtom_for("text/x-nntp-head")
2.59 frystyk 245:
246: #define WWW_HTTP HTAtom_for("text/x-http")
2.55 frystyk 247: </PRE>
2.67 frystyk 248: <P>
249: Finally we have defined a special format for our RULE files as they can be
250: handled by a special converter.
2.55 frystyk 251: <PRE>
2.57 frystyk 252: #define WWW_RULES HTAtom_for("application/x-www-rules")
2.28 frystyk 253: </PRE>
2.67 frystyk 254: <H3>
255: Register Presenters
256: </H3>
257: <P>
258: This function creates a presenter object and adds to the list of conversions.
259: These are the parameters :
2.1 timbl 260: <DL>
2.67 frystyk 261: <DT>
262: conversions
263: <DD>
264: The list of <CODE>conveters</CODE> and <CODE>presenters</CODE>
265: <DT>
266: rep_in
267: <DD>
268: the MIME-style format name
269: <DT>
270: rep_out
271: <DD>
272: is the resulting content-type after the conversion
273: <DT>
274: converter
275: <DD>
276: is the routine to call which actually does the conversion
277: <DT>
278: quality
279: <DD>
280: A degradation faction [0..1]
281: <DT>
282: maxbytes
283: <DD>
284: A limit on the length acceptable as input (0 infinite)
285: <DT>
286: maxsecs
287: <DD>
288: A limit on the time user will wait (0 for infinity)
2.1 timbl 289: </DL>
2.31 frystyk 290: <PRE>
2.49 frystyk 291: extern void HTPresentation_add (HTList * conversions,
2.61 frystyk 292: const char * representation,
293: const char * command,
294: const char * test_command,
2.49 frystyk 295: double quality,
296: double secs,
297: double secs_per_byte);
2.1 timbl 298:
2.50 frystyk 299: extern void HTPresentation_deleteAll (HTList * list);
300: </PRE>
2.67 frystyk 301: <H3>
302: Register Converters
303: </H3>
304: <P>
305: This function creates a presenter object and adds to the list of conversions.
2.1 timbl 306: <DL>
2.67 frystyk 307: <DT>
308: conversions
309: <DD>
310: The list of <CODE>conveters</CODE> and <CODE>presenters</CODE>
311: <DT>
312: rep_in
313: <DD>
314: the MIME-style format name
315: <DT>
316: rep_out
317: <DD>
318: is the resulting content-type after the conversion
319: <DT>
320: converter
321: <DD>
322: is the routine to call which actually does the conversion
323: <DT>
324: quality
325: <DD>
326: A degradation faction [0..1]
327: <DT>
328: maxbytes
329: <DD>
330: A limit on the length acceptable as input (0 infinite)
331: <DT>
332: maxsecs
333: <DD>
334: A limit on the time user will wait (0 for infinity)
2.1 timbl 335: </DL>
336: <PRE>
2.49 frystyk 337: extern void HTConversion_add (HTList * conversions,
2.61 frystyk 338: const char * rep_in,
339: const char * rep_out,
2.49 frystyk 340: HTConverter * converter,
341: double quality,
342: double secs,
343: double secs_per_byte);
2.63 frystyk 344:
345: extern void HTConversion_deleteAll (HTList * list);
2.42 frystyk 346: </PRE>
2.67 frystyk 347: <H2>
348: <A NAME="encoding">Content and Transfer Encoders and Decoders</A>
349: </H2>
350: <P>
351: Content codins are transformations applied to an entity object after it was
352: created in its original form. The Library handles two types of codings:
2.64 frystyk 353: <DL>
2.67 frystyk 354: <DT>
355: <B>Content Codings</B>
356: <DD>
357: Content codings values indicate an encoding transformation that has been
358: applied to a resource. Content cosings are primarily used to allow a document
359: to be compressed or encrypted without loosing the identity of its underlying
360: media type.
361: <DT>
362: <B>Content Transfer Codings</B>
363: <DD>
364: Content transfer codings values are used to indicate an encoding transformation
365: that has been, can be, or may be need to be applied to an enity body in order
366: to ensure safe transport through the network. This differs from a content
367: coding in that the transfer coding is a property of the message, not the
368: original message.
2.64 frystyk 369: </DL>
2.67 frystyk 370: <P>
371: Both types of encodings use the same registration mechanism in the Library
372: which we describe below:
373: <H3>
374: Encoders and Decoders
375: </H3>
376: <P>
377: <EM>Encoders</EM> and <EM>decoders</EM> are subclassed from the
378: <A HREF="HTStream.html">generic stream class</A>. <EM>Encoders</EM> are capable
379: of adding a content coding to a data object and <EM>decoders</EM> can remove
380: a content coding.
2.50 frystyk 381: <PRE>
2.64 frystyk 382: typedef HTStream * HTCoder (HTRequest * request,
383: void * param,
384: HTEncoding coding,
385: HTStream * target);
2.50 frystyk 386: </PRE>
2.67 frystyk 387: <P>
388: The <EM>encoding</EM> is the name of the encoding mechanism reporesented
389: as an <A HREF="HTAtom.html">atom</A>, for example "zip", "chunked", etc.
390: Encodings are registered in lists and content encodings are separated from
391: transfer encodings by registering them in different lists.
392: <H3>
393: The HTCoding Object
394: </H3>
395: <P>
396: The <EM>HTCoding</EM> object represents a registered encoding together with
397: a encoder and a decoder.
2.63 frystyk 398: <PRE>
2.64 frystyk 399: typedef struct _HTCoding HTCoding;
2.63 frystyk 400: </PRE>
2.67 frystyk 401: <P>
402: Predefined Coding Types We have a set of pre defined atoms for various types
403: of content encodings and transfer encodings. "chunked" is not exactly in
404: the same group as the other encodings such as "binary" but it really doesn't
405: make any difference as it is just a matter of how the words are chosen. The
406: first three transfer encodings are actually not encodings - they are just
407: left overs from brain dead mail systems.
2.42 frystyk 408: <PRE>
2.63 frystyk 409: #define WWW_CTE_7BIT HTAtom_for("7bit")
410: #define WWW_CTE_8BIT HTAtom_for("8bit")
411: #define WWW_CTE_BINARY HTAtom_for("binary")
2.64 frystyk 412:
2.63 frystyk 413: #define WWW_CTE_BASE64 HTAtom_for("base64")
414: #define WWW_CTE_MACBINHEX HTAtom_for("macbinhex")
2.64 frystyk 415: #define WWW_CTE_CHUNKED HTAtom_for("chunked")
2.63 frystyk 416:
417: #define WWW_CE_COMPRESS HTAtom_for("compress")
418: #define WWW_CE_GZIP HTAtom_for("gzip")
2.42 frystyk 419: </PRE>
2.67 frystyk 420: <H3>
421: Register Content Coders
422: </H3>
423: <P>
2.63 frystyk 424: There is no difference in registrering a content encoder or a content decoder,
425: it all depends on how you use the list of encoders/decoders.
2.42 frystyk 426: <PRE>
2.64 frystyk 427: extern BOOL HTCoding_add (HTList * list,
428: const char * encoding,
429: HTCoder * encoder,
430: HTCoder * decoder,
431: double quality);
2.63 frystyk 432:
2.64 frystyk 433: extern void HTCoding_deleteAll (HTList * list);
2.42 frystyk 434:
2.64 frystyk 435: extern const char * HTCoding_name (HTCoding * me);
2.42 frystyk 436: </PRE>
2.67 frystyk 437: <H2>
438: <A NAME="charset">Content Charsets</A>
439: </H2>
440: <H3>
441: Register a Charset
442: </H3>
2.42 frystyk 443: <PRE>
2.50 frystyk 444: extern void HTCharset_add (HTList * list,
2.61 frystyk 445: const char * charset,
2.50 frystyk 446: double quality);
2.42 frystyk 447: </PRE>
2.67 frystyk 448: <H3>
449: Delete a list of Charsets
450: </H3>
2.50 frystyk 451: <PRE>
2.63 frystyk 452: typedef struct _HTAcceptNode {
453: HTAtom * atom;
454: double quality;
455: } HTAcceptNode;
456: </PRE>
457: <PRE>
2.50 frystyk 458: extern void HTCharset_deleteAll (HTList * list);
459: </PRE>
2.67 frystyk 460: <H2>
461: <A NAME="language">Content Languages</A>
462: </H2>
463: <H3>
464: Register a Language
465: </H3>
2.31 frystyk 466: <PRE>
2.50 frystyk 467: extern void HTLanguage_add (HTList * list,
2.61 frystyk 468: const char * lang,
2.50 frystyk 469: double quality);
470: </PRE>
2.67 frystyk 471: <H3>
472: Delete a list of Languages
473: </H3>
2.50 frystyk 474: <PRE>
2.51 frystyk 475: extern void HTLanguage_deleteAll (HTList * list);
2.50 frystyk 476: </PRE>
2.67 frystyk 477: <P>
478: <H2>
479: <A NAME="global">Global Preferences</A>
480: </H2>
481: <P>
2.50 frystyk 482: There are two places where these preferences can be registered: in a
2.67 frystyk 483: <EM>global</EM> list valid for <B>all</B> requests and a <EM>local</EM> list
484: valid for a particular request only. These are valid for <EM>all</EM> requests.
485: See the <A HREF="HTReq.html">Request Manager</A> fro local sets.
486: <H3>
487: Converters and Presenters
488: </H3>
489: <P>
490: The <EM>global</EM> list of specific conversions which the format manager
491: can do in order to fulfill the request. There is also a
492: <A HREF="HTReq.html"><EM>local</EM></A> list of conversions which contains
493: a generic set of possible conversions.
2.50 frystyk 494: <PRE>
2.64 frystyk 495: extern void HTFormat_setConversion (HTList * list);
2.50 frystyk 496: extern HTList * HTFormat_conversion (void);
2.69 ! frystyk 497:
! 498: extern void HTFormat_addConversion (const char * input_format,
! 499: const char * output_format,
! 500: HTConverter * converter,
! 501: double quality,
! 502: double secs,
! 503: double secs_per_byte);
2.31 frystyk 504: </PRE>
2.67 frystyk 505: <H3>
506: Content Codings
507: </H3>
2.50 frystyk 508: <PRE>
2.64 frystyk 509: extern void HTFormat_setContentCoding (HTList * list);
510: extern HTList * HTFormat_contentCoding (void);
2.69 ! frystyk 511:
! 512: extern BOOL HTFormat_addCoding ( char * encoding,
! 513: HTCoder * encoder,
! 514: HTCoder * decoder,
! 515: double quality);
2.50 frystyk 516: </PRE>
2.67 frystyk 517: <H3>
518: Content Transfer Codings
519: </H3>
2.64 frystyk 520: <PRE>
521: extern void HTFormat_setTransferCoding (HTList * list);
522: extern HTList * HTFormat_transferCoding (void);
2.69 ! frystyk 523:
! 524: extern BOOL HTFormat_addTransferCoding ( char * encoding,
! 525: HTCoder * encoder,
! 526: HTCoder * decoder,
! 527: double quality);
2.64 frystyk 528: </PRE>
2.67 frystyk 529: <P>
530: We also define a macro to find out whether a transfer encoding is really
531: an encoding or whether it is just a "dummy" as for example 7bit, 8bit, and
532: binary.
2.64 frystyk 533: <PRE>
534: #define HTFormat_isUnityTransfer(me) \
535: ((me)==NULL \
536: || (me)==WWW_CTE_BINARY || (me)==WWW_CTE_7BIT || (me)==WWW_CTE_8BIT)
537: </PRE>
2.67 frystyk 538: <H3>
539: Content Languages
540: </H3>
2.50 frystyk 541: <PRE>
2.64 frystyk 542: extern void HTFormat_setLanguage (HTList * list);
2.50 frystyk 543: extern HTList * HTFormat_language (void);
544: </PRE>
2.67 frystyk 545: <H3>
546: Content Charsets
547: </H3>
2.31 frystyk 548: <PRE>
2.64 frystyk 549: extern void HTFormat_setCharset (HTList * list);
2.50 frystyk 550: extern HTList * HTFormat_charset (void);
2.31 frystyk 551: </PRE>
2.67 frystyk 552: <H3>
553: Delete All Global Lists
554: </H3>
555: <P>
2.50 frystyk 556: This is a convenience function that might make life easier.
2.34 frystyk 557: <PRE>
2.50 frystyk 558: extern void HTFormat_deleteAll (void);
2.34 frystyk 559: </PRE>
2.67 frystyk 560: <H2>
561: <A NAME="CTStack">The Content Type Stream Stack</A>
562: </H2>
563: <P>
564: This is the routine which actually sets up the content type conversion. It
565: currently checks only for direct conversions, but multi-stage conversions
566: are forseen. It takes a stream into which the output should be sent in the
567: final format, builds the conversion stack, and returns a stream into which
568: the data in the input format should be fed. If <CODE>guess</CODE> is true
569: and input format is <CODE>www/unknown</CODE>, try to guess the format by
570: looking at the first few bytes of the stream.
571: <P>
2.31 frystyk 572: <PRE>
2.52 frystyk 573: extern HTStream * HTStreamStack (HTFormat rep_in,
574: HTFormat rep_out,
575: HTStream * output_stream,
576: HTRequest * request,
577: BOOL guess);
2.1 timbl 578: </PRE>
2.67 frystyk 579: <H3>
580: Cost of a Stream Stack
581: </H3>
582: <P>
583: Must return the cost of the same stack which HTStreamStack would set up.
2.31 frystyk 584: <PRE>
2.52 frystyk 585: extern double HTStackValue (HTList * conversions,
586: HTFormat format_in,
587: HTFormat format_out,
588: double initial_value,
589: long int length);
2.64 frystyk 590: </PRE>
2.67 frystyk 591: <H2>
592: <A NAME="CEStack">Content Encoding Stream Stack</A>
593: </H2>
594: <P>
595: When creating a coding stream stack, it is important that we keep the right
596: order of encoders and decoders. As an example, the HTTP spec specifies that
597: the list in the <EM>Content-Encoding</EM> header follows the order in which
598: the encodings have been applied to the object. Internally, we represent the
599: content encodings as <A HREF="HTAtom.html">atoms</A> in a linked
600: <A HREF="HTList.html">list object</A>.
601: <P>
602: The creation of the content coding stack is not based on quality factors
603: as we don't have the freedom as with content types. When using content codings
604: we <EM>must</EM> apply the codings specified or fail.
2.64 frystyk 605: <PRE>
606: extern HTStream * HTContentCodingStack (HTEncoding coding,
607: HTStream * target,
608: HTRequest * request,
609: void * param,
610: BOOL encoding);
611: </PRE>
2.67 frystyk 612: <P>
613: Here you can provide a complete list instead of a single token. The list
614: has to be filled up in the order the _encodings_ are to be applied
2.64 frystyk 615: <PRE>
616: extern HTStream * HTContentEncodingStack (HTList * encodings,
617: HTStream * target,
618: HTRequest * request,
619: void * param);
620: </PRE>
2.67 frystyk 621: <P>
622: Here you can provide a complete list instead of a single token. The list
623: has to be in the order the _encodings_ were applied - that is, the same way
624: that _encodings_ are to be applied. This is all consistent with the order
625: of the Content-Encoding header.
2.64 frystyk 626: <PRE>
627: extern HTStream * HTContentDecodingStack (HTList * encodings,
628: HTStream * target,
629: HTRequest * request,
630: void * param);
631: </PRE>
2.67 frystyk 632: <P>
633: <H2>
634: <A NAME="CTEStack">Content Transfer Encoding Stream Stack</A>
635: </H2>
636: <P>
637: Creating the transfer content encoding stream stack is not based on quality
638: factors as we don't have the freedom as with content types. Specify whether
639: you you want encoding or decoding using the BOOL "encode" flag.
2.64 frystyk 640: <PRE>
641: extern HTStream * HTTransferCodingStack (HTEncoding encoding,
642: HTStream * target,
643: HTRequest * request,
644: void * param,
645: BOOL encode);
646: </PRE>
647: <PRE>
2.42 frystyk 648: #endif /* HTFORMAT */
2.38 frystyk 649: </PRE>
2.67 frystyk 650: <P>
651: <HR>
2.63 frystyk 652: <ADDRESS>
2.69 ! frystyk 653: @(#) $Id: HTFormat.html,v 2.68 1996/06/08 01:52:13 frystyk Exp $
2.63 frystyk 654: </ADDRESS>
2.67 frystyk 655: </BODY></HTML>
Webmaster
![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to HTFormat.html CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [Public] / libwww / Library / src