Annotation of libwww/Library/src/HTFormat.html, revision 2.71
2.10 timbl 1: <HTML>
2: <HEAD>
2.71 ! 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.
2.71 ! frystyk 208: <PRE>
! 209: #define WWW_CACHE HTAtom_for("www/cache")
! 210: </PRE>
! 211: <P>
! 212: <CODE>WWW_CACHE</CODE> is the internal content-type designated for a persistent
! 213: cache module which can store the object to local storage.
2.67 frystyk 214: <P>
2.31 frystyk 215: These are regular MIME types defined. Others can be added!
2.28 frystyk 216: <PRE>
2.52 frystyk 217: #define WWW_HTML HTAtom_for("text/html")
2.28 frystyk 218: #define WWW_PLAINTEXT HTAtom_for("text/plain")
2.69 frystyk 219: #define WWW_FORM HTAtom_for("application/x-www-form-urlencoded")
2.52 frystyk 220:
221: #define WWW_MIME HTAtom_for("message/rfc822")
2.60 frystyk 222: #define WWW_MIME_HEAD HTAtom_for("message/x-rfc822-head")
2.65 frystyk 223: #define WWW_MIME_FOOT HTAtom_for("message/x-rfc822-foot")
2.52 frystyk 224:
2.10 timbl 225: #define WWW_AUDIO HTAtom_for("audio/basic")
2.52 frystyk 226:
2.26 frystyk 227: #define WWW_VIDEO HTAtom_for("video/mpeg")
2.52 frystyk 228:
2.70 frystyk 229: #define WWW_GIF HTAtom_for("image/gif")
2.63 frystyk 230: #define WWW_JPEG HTAtom_for("image/jpeg")
231: #define WWW_TIFF HTAtom_for("image/tiff")
2.52 frystyk 232: #define WWW_PNG HTAtom_for("image/png")
233:
234: #define WWW_BINARY HTAtom_for("application/octet-stream")
235: #define WWW_POSTSCRIPT HTAtom_for("application/postscript")
236: #define WWW_RICHTEXT HTAtom_for("application/rtf")
2.48 frystyk 237: </PRE>
2.67 frystyk 238: <P>
239: We also have some MIME types that come from the various protocols when we
240: convert from ASCII to HTML.
2.48 frystyk 241: <PRE>
242: #define WWW_GOPHER_MENU HTAtom_for("text/x-gopher")
2.53 frystyk 243: #define WWW_CSO_SEARCH HTAtom_for("text/x-cso")
2.48 frystyk 244:
245: #define WWW_FTP_LNST HTAtom_for("text/x-ftp-lnst")
246: #define WWW_FTP_LIST HTAtom_for("text/x-ftp-list")
247:
248: #define WWW_NNTP_LIST HTAtom_for("text/x-nntp-list")
249: #define WWW_NNTP_OVER HTAtom_for("text/x-nntp-over")
250: #define WWW_NNTP_HEAD HTAtom_for("text/x-nntp-head")
2.59 frystyk 251:
252: #define WWW_HTTP HTAtom_for("text/x-http")
2.55 frystyk 253: </PRE>
2.67 frystyk 254: <P>
255: Finally we have defined a special format for our RULE files as they can be
256: handled by a special converter.
2.55 frystyk 257: <PRE>
2.57 frystyk 258: #define WWW_RULES HTAtom_for("application/x-www-rules")
2.28 frystyk 259: </PRE>
2.67 frystyk 260: <H3>
261: Register Presenters
262: </H3>
263: <P>
264: This function creates a presenter object and adds to the list of conversions.
265: These are the parameters :
2.1 timbl 266: <DL>
2.67 frystyk 267: <DT>
268: conversions
269: <DD>
270: The list of <CODE>conveters</CODE> and <CODE>presenters</CODE>
271: <DT>
272: rep_in
273: <DD>
274: the MIME-style format name
275: <DT>
276: rep_out
277: <DD>
278: is the resulting content-type after the conversion
279: <DT>
280: converter
281: <DD>
282: is the routine to call which actually does the conversion
283: <DT>
284: quality
285: <DD>
286: A degradation faction [0..1]
287: <DT>
288: maxbytes
289: <DD>
290: A limit on the length acceptable as input (0 infinite)
291: <DT>
292: maxsecs
293: <DD>
294: A limit on the time user will wait (0 for infinity)
2.1 timbl 295: </DL>
2.31 frystyk 296: <PRE>
2.49 frystyk 297: extern void HTPresentation_add (HTList * conversions,
2.61 frystyk 298: const char * representation,
299: const char * command,
300: const char * test_command,
2.49 frystyk 301: double quality,
302: double secs,
303: double secs_per_byte);
2.1 timbl 304:
2.50 frystyk 305: extern void HTPresentation_deleteAll (HTList * list);
306: </PRE>
2.67 frystyk 307: <H3>
308: Register Converters
309: </H3>
310: <P>
311: This function creates a presenter object and adds to the list of conversions.
2.1 timbl 312: <DL>
2.67 frystyk 313: <DT>
314: conversions
315: <DD>
316: The list of <CODE>conveters</CODE> and <CODE>presenters</CODE>
317: <DT>
318: rep_in
319: <DD>
320: the MIME-style format name
321: <DT>
322: rep_out
323: <DD>
324: is the resulting content-type after the conversion
325: <DT>
326: converter
327: <DD>
328: is the routine to call which actually does the conversion
329: <DT>
330: quality
331: <DD>
332: A degradation faction [0..1]
333: <DT>
334: maxbytes
335: <DD>
336: A limit on the length acceptable as input (0 infinite)
337: <DT>
338: maxsecs
339: <DD>
340: A limit on the time user will wait (0 for infinity)
2.1 timbl 341: </DL>
342: <PRE>
2.49 frystyk 343: extern void HTConversion_add (HTList * conversions,
2.61 frystyk 344: const char * rep_in,
345: const char * rep_out,
2.49 frystyk 346: HTConverter * converter,
347: double quality,
348: double secs,
349: double secs_per_byte);
2.63 frystyk 350:
351: extern void HTConversion_deleteAll (HTList * list);
2.42 frystyk 352: </PRE>
2.67 frystyk 353: <H2>
354: <A NAME="encoding">Content and Transfer Encoders and Decoders</A>
355: </H2>
356: <P>
357: Content codins are transformations applied to an entity object after it was
358: created in its original form. The Library handles two types of codings:
2.64 frystyk 359: <DL>
2.67 frystyk 360: <DT>
361: <B>Content Codings</B>
362: <DD>
363: Content codings values indicate an encoding transformation that has been
364: applied to a resource. Content cosings are primarily used to allow a document
365: to be compressed or encrypted without loosing the identity of its underlying
366: media type.
367: <DT>
368: <B>Content Transfer Codings</B>
369: <DD>
370: Content transfer codings values are used to indicate an encoding transformation
371: that has been, can be, or may be need to be applied to an enity body in order
372: to ensure safe transport through the network. This differs from a content
373: coding in that the transfer coding is a property of the message, not the
374: original message.
2.64 frystyk 375: </DL>
2.67 frystyk 376: <P>
377: Both types of encodings use the same registration mechanism in the Library
378: which we describe below:
379: <H3>
380: Encoders and Decoders
381: </H3>
382: <P>
383: <EM>Encoders</EM> and <EM>decoders</EM> are subclassed from the
384: <A HREF="HTStream.html">generic stream class</A>. <EM>Encoders</EM> are capable
385: of adding a content coding to a data object and <EM>decoders</EM> can remove
386: a content coding.
2.50 frystyk 387: <PRE>
2.64 frystyk 388: typedef HTStream * HTCoder (HTRequest * request,
389: void * param,
390: HTEncoding coding,
391: HTStream * target);
2.50 frystyk 392: </PRE>
2.67 frystyk 393: <P>
394: The <EM>encoding</EM> is the name of the encoding mechanism reporesented
395: as an <A HREF="HTAtom.html">atom</A>, for example "zip", "chunked", etc.
396: Encodings are registered in lists and content encodings are separated from
397: transfer encodings by registering them in different lists.
398: <H3>
399: The HTCoding Object
400: </H3>
401: <P>
402: The <EM>HTCoding</EM> object represents a registered encoding together with
403: a encoder and a decoder.
2.63 frystyk 404: <PRE>
2.64 frystyk 405: typedef struct _HTCoding HTCoding;
2.63 frystyk 406: </PRE>
2.67 frystyk 407: <P>
408: Predefined Coding Types We have a set of pre defined atoms for various types
409: of content encodings and transfer encodings. "chunked" is not exactly in
410: the same group as the other encodings such as "binary" but it really doesn't
411: make any difference as it is just a matter of how the words are chosen. The
412: first three transfer encodings are actually not encodings - they are just
413: left overs from brain dead mail systems.
2.42 frystyk 414: <PRE>
2.63 frystyk 415: #define WWW_CTE_7BIT HTAtom_for("7bit")
416: #define WWW_CTE_8BIT HTAtom_for("8bit")
417: #define WWW_CTE_BINARY HTAtom_for("binary")
2.64 frystyk 418:
2.63 frystyk 419: #define WWW_CTE_BASE64 HTAtom_for("base64")
420: #define WWW_CTE_MACBINHEX HTAtom_for("macbinhex")
2.64 frystyk 421: #define WWW_CTE_CHUNKED HTAtom_for("chunked")
2.63 frystyk 422:
423: #define WWW_CE_COMPRESS HTAtom_for("compress")
424: #define WWW_CE_GZIP HTAtom_for("gzip")
2.42 frystyk 425: </PRE>
2.67 frystyk 426: <H3>
427: Register Content Coders
428: </H3>
429: <P>
2.63 frystyk 430: There is no difference in registrering a content encoder or a content decoder,
431: it all depends on how you use the list of encoders/decoders.
2.42 frystyk 432: <PRE>
2.64 frystyk 433: extern BOOL HTCoding_add (HTList * list,
434: const char * encoding,
435: HTCoder * encoder,
436: HTCoder * decoder,
437: double quality);
2.63 frystyk 438:
2.64 frystyk 439: extern void HTCoding_deleteAll (HTList * list);
2.42 frystyk 440:
2.64 frystyk 441: extern const char * HTCoding_name (HTCoding * me);
2.42 frystyk 442: </PRE>
2.67 frystyk 443: <H2>
444: <A NAME="charset">Content Charsets</A>
445: </H2>
446: <H3>
447: Register a Charset
448: </H3>
2.42 frystyk 449: <PRE>
2.50 frystyk 450: extern void HTCharset_add (HTList * list,
2.61 frystyk 451: const char * charset,
2.50 frystyk 452: double quality);
2.42 frystyk 453: </PRE>
2.67 frystyk 454: <H3>
455: Delete a list of Charsets
456: </H3>
2.50 frystyk 457: <PRE>
2.63 frystyk 458: typedef struct _HTAcceptNode {
459: HTAtom * atom;
460: double quality;
461: } HTAcceptNode;
462: </PRE>
463: <PRE>
2.50 frystyk 464: extern void HTCharset_deleteAll (HTList * list);
465: </PRE>
2.67 frystyk 466: <H2>
467: <A NAME="language">Content Languages</A>
468: </H2>
469: <H3>
470: Register a Language
471: </H3>
2.31 frystyk 472: <PRE>
2.50 frystyk 473: extern void HTLanguage_add (HTList * list,
2.61 frystyk 474: const char * lang,
2.50 frystyk 475: double quality);
476: </PRE>
2.67 frystyk 477: <H3>
478: Delete a list of Languages
479: </H3>
2.50 frystyk 480: <PRE>
2.51 frystyk 481: extern void HTLanguage_deleteAll (HTList * list);
2.50 frystyk 482: </PRE>
2.67 frystyk 483: <P>
484: <H2>
485: <A NAME="global">Global Preferences</A>
486: </H2>
487: <P>
2.50 frystyk 488: There are two places where these preferences can be registered: in a
2.67 frystyk 489: <EM>global</EM> list valid for <B>all</B> requests and a <EM>local</EM> list
490: valid for a particular request only. These are valid for <EM>all</EM> requests.
491: See the <A HREF="HTReq.html">Request Manager</A> fro local sets.
492: <H3>
493: Converters and Presenters
494: </H3>
495: <P>
496: The <EM>global</EM> list of specific conversions which the format manager
497: can do in order to fulfill the request. There is also a
498: <A HREF="HTReq.html"><EM>local</EM></A> list of conversions which contains
499: a generic set of possible conversions.
2.50 frystyk 500: <PRE>
2.64 frystyk 501: extern void HTFormat_setConversion (HTList * list);
2.50 frystyk 502: extern HTList * HTFormat_conversion (void);
2.69 frystyk 503:
504: extern void HTFormat_addConversion (const char * input_format,
505: const char * output_format,
506: HTConverter * converter,
507: double quality,
508: double secs,
509: double secs_per_byte);
2.31 frystyk 510: </PRE>
2.67 frystyk 511: <H3>
512: Content Codings
513: </H3>
2.50 frystyk 514: <PRE>
2.64 frystyk 515: extern void HTFormat_setContentCoding (HTList * list);
516: extern HTList * HTFormat_contentCoding (void);
2.69 frystyk 517:
518: extern BOOL HTFormat_addCoding ( char * encoding,
519: HTCoder * encoder,
520: HTCoder * decoder,
521: double quality);
2.50 frystyk 522: </PRE>
2.67 frystyk 523: <H3>
524: Content Transfer Codings
525: </H3>
2.64 frystyk 526: <PRE>
527: extern void HTFormat_setTransferCoding (HTList * list);
528: extern HTList * HTFormat_transferCoding (void);
2.69 frystyk 529:
530: extern BOOL HTFormat_addTransferCoding ( char * encoding,
531: HTCoder * encoder,
532: HTCoder * decoder,
533: double quality);
2.64 frystyk 534: </PRE>
2.67 frystyk 535: <P>
536: We also define a macro to find out whether a transfer encoding is really
537: an encoding or whether it is just a "dummy" as for example 7bit, 8bit, and
538: binary.
2.64 frystyk 539: <PRE>
540: #define HTFormat_isUnityTransfer(me) \
541: ((me)==NULL \
542: || (me)==WWW_CTE_BINARY || (me)==WWW_CTE_7BIT || (me)==WWW_CTE_8BIT)
543: </PRE>
2.67 frystyk 544: <H3>
545: Content Languages
546: </H3>
2.50 frystyk 547: <PRE>
2.64 frystyk 548: extern void HTFormat_setLanguage (HTList * list);
2.50 frystyk 549: extern HTList * HTFormat_language (void);
550: </PRE>
2.67 frystyk 551: <H3>
552: Content Charsets
553: </H3>
2.31 frystyk 554: <PRE>
2.64 frystyk 555: extern void HTFormat_setCharset (HTList * list);
2.50 frystyk 556: extern HTList * HTFormat_charset (void);
2.31 frystyk 557: </PRE>
2.67 frystyk 558: <H3>
559: Delete All Global Lists
560: </H3>
561: <P>
2.50 frystyk 562: This is a convenience function that might make life easier.
2.34 frystyk 563: <PRE>
2.50 frystyk 564: extern void HTFormat_deleteAll (void);
2.34 frystyk 565: </PRE>
2.67 frystyk 566: <H2>
567: <A NAME="CTStack">The Content Type Stream Stack</A>
568: </H2>
569: <P>
570: This is the routine which actually sets up the content type conversion. It
571: currently checks only for direct conversions, but multi-stage conversions
572: are forseen. It takes a stream into which the output should be sent in the
573: final format, builds the conversion stack, and returns a stream into which
574: the data in the input format should be fed. If <CODE>guess</CODE> is true
575: and input format is <CODE>www/unknown</CODE>, try to guess the format by
576: looking at the first few bytes of the stream.
577: <P>
2.31 frystyk 578: <PRE>
2.52 frystyk 579: extern HTStream * HTStreamStack (HTFormat rep_in,
580: HTFormat rep_out,
581: HTStream * output_stream,
582: HTRequest * request,
583: BOOL guess);
2.1 timbl 584: </PRE>
2.67 frystyk 585: <H3>
586: Cost of a Stream Stack
587: </H3>
588: <P>
589: Must return the cost of the same stack which HTStreamStack would set up.
2.31 frystyk 590: <PRE>
2.52 frystyk 591: extern double HTStackValue (HTList * conversions,
592: HTFormat format_in,
593: HTFormat format_out,
594: double initial_value,
595: long int length);
2.64 frystyk 596: </PRE>
2.67 frystyk 597: <H2>
598: <A NAME="CEStack">Content Encoding Stream Stack</A>
599: </H2>
600: <P>
601: When creating a coding stream stack, it is important that we keep the right
602: order of encoders and decoders. As an example, the HTTP spec specifies that
603: the list in the <EM>Content-Encoding</EM> header follows the order in which
604: the encodings have been applied to the object. Internally, we represent the
605: content encodings as <A HREF="HTAtom.html">atoms</A> in a linked
606: <A HREF="HTList.html">list object</A>.
607: <P>
608: The creation of the content coding stack is not based on quality factors
609: as we don't have the freedom as with content types. When using content codings
610: we <EM>must</EM> apply the codings specified or fail.
2.64 frystyk 611: <PRE>
612: extern HTStream * HTContentCodingStack (HTEncoding coding,
613: HTStream * target,
614: HTRequest * request,
615: void * param,
616: BOOL encoding);
617: </PRE>
2.67 frystyk 618: <P>
619: Here you can provide a complete list instead of a single token. The list
620: has to be filled up in the order the _encodings_ are to be applied
2.64 frystyk 621: <PRE>
622: extern HTStream * HTContentEncodingStack (HTList * encodings,
623: HTStream * target,
624: HTRequest * request,
625: void * param);
626: </PRE>
2.67 frystyk 627: <P>
628: Here you can provide a complete list instead of a single token. The list
629: has to be in the order the _encodings_ were applied - that is, the same way
630: that _encodings_ are to be applied. This is all consistent with the order
631: of the Content-Encoding header.
2.64 frystyk 632: <PRE>
633: extern HTStream * HTContentDecodingStack (HTList * encodings,
634: HTStream * target,
635: HTRequest * request,
636: void * param);
637: </PRE>
2.67 frystyk 638: <P>
639: <H2>
640: <A NAME="CTEStack">Content Transfer Encoding Stream Stack</A>
641: </H2>
642: <P>
643: Creating the transfer content encoding stream stack is not based on quality
644: factors as we don't have the freedom as with content types. Specify whether
645: you you want encoding or decoding using the BOOL "encode" flag.
2.64 frystyk 646: <PRE>
647: extern HTStream * HTTransferCodingStack (HTEncoding encoding,
648: HTStream * target,
649: HTRequest * request,
650: void * param,
651: BOOL encode);
652: </PRE>
653: <PRE>
2.42 frystyk 654: #endif /* HTFORMAT */
2.38 frystyk 655: </PRE>
2.67 frystyk 656: <P>
657: <HR>
2.63 frystyk 658: <ADDRESS>
2.71 ! frystyk 659: @(#) $Id: HTFormat.html,v 2.70 1996/08/08 02:16:49 frystyk Exp $
2.63 frystyk 660: </ADDRESS>
2.67 frystyk 661: </BODY></HTML>
Webmaster