Annotation of libwww/Library/src/HTFormat.html, revision 2.73
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: <UL>
46: <LI>
47: <A HREF="#type">Content Type Converters and Presenters</A>
48: <LI>
49: <A HREF="#encoding">Content Encoders and Decoders</A>
50: <LI>
51: <A HREF="#charset">Content Charsets</A>
52: <LI>
53: <A HREF="#language">Natural Languages</A>
54: </UL>
55: <P>
56: The application can assign its preferences in two ways: either <I>locally</I>
57: to a single request or <I>globally</I> to all requests. The local assignment
58: can either <I>add to </I>or <I>override</I> the global settings depending
59: on how they are registered. All local registration is handled by the
60: <A HREF="HTReq.html">Request Object</A> and the global registration is handled
2.73 ! frystyk 61: by the Format Manager.
2.67 frystyk 62: <P>
63: This module is implemented by <A HREF="HTFormat.c">HTFormat.c</A>, and it
64: is a part of the <A HREF="http://www.w3.org/pub/WWW/Library/">W3C Reference
65: Library</A>.
2.31 frystyk 66: <PRE>
67: #ifndef HTFORMAT_H
2.1 timbl 68: #define HTFORMAT_H
69:
2.63 frystyk 70: #include "<A HREF="HTUtils.html">HTUtils.h</A>"
71: #include "<A HREF="HTStream.html">HTStream.h</A>"
72: #include "<A HREF="HTAtom.html">HTAtom.h</A>"
73: #include "<A HREF="HTList.html">HTList.h</A>"
74: #include "<A HREF="HTAnchor.html">HTAnchor.h</A>"
75: #include "<A HREF="HTReq.html">HTReq.h</A>"
2.31 frystyk 76: </PRE>
2.67 frystyk 77: <H2>
2.73 ! frystyk 78: <A NAME="type">Converters and Presenters</A>
2.67 frystyk 79: </H2>
80: <P>
81: All content type converters are subclassed from the Generic stream objetc.
82: That way, we allow the application to do very fast progressive display of
83: incoming data. In other words, the stream model of the Library provides data
84: as soon as it arrives from the network, the application does not have to
85: wait until the whole document has been down loaded before it starts parsing
86: it.
87: <H3>
88: Predefined Content Types
89: </H3>
90: <P>
91: These macros (which used to be constants) define some basic internally referenced
92: representations. The <CODE>www/xxx</CODE> ones are of course not MIME standard.
93: They are internal representations used in the Library but they can't be exported
94: to other apps!
2.28 frystyk 95: <PRE>
2.57 frystyk 96: #define WWW_RAW HTAtom_for("www/void") /* Raw output from Protocol */
2.28 frystyk 97: </PRE>
2.67 frystyk 98: <P>
99: <CODE>WWW_RAW</CODE> is an output format which leaves the input untouched
100: <EM>exactly</EM> as it is received by the protocol module. For example, in
101: the case of FTP, this format returns raw ASCII objects for directory listings;
102: for HTTP, everything including the header is returned, for Gopher, a raw
103: ASCII object is returned for a menu etc.
104: <PRE>
105: #define WWW_SOURCE HTAtom_for("*/*")
106: </PRE>
107: <P>
108: <CODE>WWW_SOURCE</CODE> is an output format which leaves the input untouched
109: <EM>exactly</EM> as it is received by the protocol module <B>IF</B> not a
110: suitable converter has been registered with a quality factor higher than
111: 1 (for example 2). In this case the <EM>SUPER CONVERTER</EM> is preferred
112: for the raw output. This can be used as a filter effect that allows conversion
113: from, for example raw FTPdirectory listings into HTML but passes a MIME body
114: untouched.
115: <PRE>
116: #define WWW_PRESENT HTAtom_for("www/present")
117: </PRE>
118: <P>
119: <CODE>WWW_PRESENT</CODE> represents the user's perception of the document.
120: If you convert to <CODE>WWW_PRESENT</CODE>, you present the material to the
121: user.
2.58 frystyk 122: <PRE>
123: #define WWW_DEBUG HTAtom_for("www/debug")
124: </PRE>
2.67 frystyk 125: <P>
126: <CODE>WWW_DEBUG</CODE> represents the user's perception of debug information,
127: for example sent as a HTML document in a HTTP redirection message.
2.28 frystyk 128: <PRE>
2.52 frystyk 129: #define WWW_UNKNOWN HTAtom_for("www/unknown")
2.28 frystyk 130: </PRE>
2.67 frystyk 131: <P>
132: <CODE>WWW_UNKNOWN</CODE> is a really unknown type. It differs from the real
133: MIME type <EM>"application/octet-stream"</EM> in that we haven't even tried
134: to figure out the content type at this point.
2.71 frystyk 135: <PRE>
2.72 frystyk 136: #define WWW_CACHE HTAtom_for("www/cache")
137: #define WWW_CACHE_APPEND HTAtom_for("www/cache-append")
2.71 frystyk 138: </PRE>
139: <P>
140: <CODE>WWW_CACHE</CODE> is the internal content-type designated for a persistent
2.72 frystyk 141: cache module which can store the object to local storage. The cache append
142: format is special in that we append information to an already existing cache
143: entry. This can happen if we have issued a <CODE>If-Range </CODE>request
144: and got back a "206 Partial response".
2.67 frystyk 145: <P>
2.31 frystyk 146: These are regular MIME types defined. Others can be added!
2.28 frystyk 147: <PRE>
2.52 frystyk 148: #define WWW_HTML HTAtom_for("text/html")
2.28 frystyk 149: #define WWW_PLAINTEXT HTAtom_for("text/plain")
2.69 frystyk 150: #define WWW_FORM HTAtom_for("application/x-www-form-urlencoded")
2.52 frystyk 151:
152: #define WWW_MIME HTAtom_for("message/rfc822")
2.60 frystyk 153: #define WWW_MIME_HEAD HTAtom_for("message/x-rfc822-head")
2.65 frystyk 154: #define WWW_MIME_FOOT HTAtom_for("message/x-rfc822-foot")
2.72 frystyk 155: #define WWW_MIME_PART HTAtom_for("message/x-rfc822-partial")
2.52 frystyk 156:
2.10 timbl 157: #define WWW_AUDIO HTAtom_for("audio/basic")
2.52 frystyk 158:
2.26 frystyk 159: #define WWW_VIDEO HTAtom_for("video/mpeg")
2.52 frystyk 160:
2.70 frystyk 161: #define WWW_GIF HTAtom_for("image/gif")
2.63 frystyk 162: #define WWW_JPEG HTAtom_for("image/jpeg")
163: #define WWW_TIFF HTAtom_for("image/tiff")
2.52 frystyk 164: #define WWW_PNG HTAtom_for("image/png")
165:
166: #define WWW_BINARY HTAtom_for("application/octet-stream")
167: #define WWW_POSTSCRIPT HTAtom_for("application/postscript")
168: #define WWW_RICHTEXT HTAtom_for("application/rtf")
2.48 frystyk 169: </PRE>
2.67 frystyk 170: <P>
171: We also have some MIME types that come from the various protocols when we
172: convert from ASCII to HTML.
2.48 frystyk 173: <PRE>
174: #define WWW_GOPHER_MENU HTAtom_for("text/x-gopher")
2.53 frystyk 175: #define WWW_CSO_SEARCH HTAtom_for("text/x-cso")
2.48 frystyk 176:
177: #define WWW_FTP_LNST HTAtom_for("text/x-ftp-lnst")
178: #define WWW_FTP_LIST HTAtom_for("text/x-ftp-list")
179:
180: #define WWW_NNTP_LIST HTAtom_for("text/x-nntp-list")
181: #define WWW_NNTP_OVER HTAtom_for("text/x-nntp-over")
182: #define WWW_NNTP_HEAD HTAtom_for("text/x-nntp-head")
2.59 frystyk 183:
184: #define WWW_HTTP HTAtom_for("text/x-http")
2.55 frystyk 185: </PRE>
2.67 frystyk 186: <P>
187: Finally we have defined a special format for our RULE files as they can be
188: handled by a special converter.
2.73 ! frystyk 189: <PRE>#define WWW_RULES HTAtom_for("application/x-www-rules")
! 190: </PRE>
! 191: <H3>
! 192: The Quality Factor
! 193: </H3>
! 194: <P>
! 195: Characteristic for all preferences is that there is a quality factor associated
! 196: with each member. The quality factor is a real number between 0 and 1 with
! 197: 0 meaning "very bad" and 1 means "perfect". By registering a natural language
! 198: or any or other preference in this group together with a quality factor you
! 199: can specify "how well the preference is handled" either by the application
! 200: or by the user. In the case of the user the quality factor of a natural language
! 201: is how well the user understands the language. In my case, the quality factors
! 202: for, for example Greek would be close to zero and 1 for Danish (nothing bad
! 203: said about Greek!).
! 204: <P>
! 205: It is a bit different for converters where it is often the application's
! 206: ability of handling the data format rather than the user's perception. As
! 207: an example it is often faster to use a converter than a presenter as it takes
! 208: time to launch the external application and libwww can not use progressive
! 209: display mechanisms which is often the case for converters. Therefore, as
! 210: an example, if we capable of handling an image in <EM>png</EM> format inline
! 211: but rely on an external viewer for presenting postscript, we might set up
! 212: the following list:
! 213: <P>
! 214: <SAMP>HTConversion_add (converters, "image", "www/present", GifPresenter,
! 215: <B>1.0</B>, 0.0, 0.0);<BR>
! 216: HTPresentation_add (presenters, "application/postscript", "ghostview %s",
! 217: NULL, <B>0.5</B>, 0.0, 0.0);></SAMP>
! 218: <P>
! 219: where the gif converter is registered with a quality factor of <B>1.0</B>
! 220: and the postscript presenter with a quality factor of <B>0.5</B>.Register
! 221: Presenters
! 222: <H3>
! 223: The Converter Class
! 224: </H3>
! 225: <P>
! 226: A <CODE>converter</CODE> is a stream with a special set of parameters and
! 227: which is registered as capable of converting from a MIME type to something
! 228: else (maybe another MIME-type). A converter is defined to be a function returning
! 229: a stream and accepting the following parameters. The content type elements
! 230: are atoms for which we have defined a prototype.
2.55 frystyk 231: <PRE>
2.73 ! frystyk 232: typedef HTStream * HTConverter (HTRequest * request,
! 233: void * param,
! 234: HTFormat input_format,
! 235: HTFormat output_format,
! 236: HTStream * output_stream);
! 237:
! 238: extern void HTConversion_add (HTList * conversions,
! 239: const char * rep_in,
! 240: const char * rep_out,
! 241: HTConverter * converter,
! 242: double quality,
! 243: double secs,
! 244: double secs_per_byte);
! 245:
! 246: extern void HTConversion_deleteAll (HTList * list);
2.28 frystyk 247: </PRE>
2.67 frystyk 248: <H3>
2.73 ! frystyk 249: The Presenter Class
2.67 frystyk 250: </H3>
251: <P>
2.73 ! frystyk 252: A <CODE>presenter</CODE> is a module (possibly an external program) which
! 253: can present a graphic object of a certain MIME type to the user. That is,
! 254: <CODE>presenters</CODE> are normally used to present objects that the
! 255: <CODE>converters</CODE> are not able to handle. Data is transferred to the
! 256: external program using for example the
! 257: <A HREF="HTFWrite.html">HTSaveAndExecute</A> stream which writes to a local
! 258: file. Both presenters and converters are of the type
! 259: <A HREF="#converter">HTConverter</A>.
2.31 frystyk 260: <PRE>
2.49 frystyk 261: extern void HTPresentation_add (HTList * conversions,
2.73 ! frystyk 262: </PRE>
! 263: <PRE> const char * representation,
2.61 frystyk 264: const char * command,
265: const char * test_command,
2.49 frystyk 266: double quality,
267: double secs,
268: double secs_per_byte);
2.1 timbl 269:
2.50 frystyk 270: extern void HTPresentation_deleteAll (HTList * list);
271: </PRE>
2.67 frystyk 272: <H3>
2.73 ! frystyk 273: Basic Converters
2.67 frystyk 274: </H3>
275: <P>
2.73 ! frystyk 276: We have a small set of basic converters that can be hooked in anywhere. They
! 277: don't "convert" anything but are nice to have.
! 278: <PRE>extern HTConverter HTThroughLine;
! 279: extern HTConverter HTBlackHoleConverter;
2.42 frystyk 280: </PRE>
2.67 frystyk 281: <H2>
282: <A NAME="encoding">Content and Transfer Encoders and Decoders</A>
283: </H2>
284: <P>
285: Content codins are transformations applied to an entity object after it was
286: created in its original form. The Library handles two types of codings:
2.64 frystyk 287: <DL>
2.67 frystyk 288: <DT>
289: <B>Content Codings</B>
290: <DD>
291: Content codings values indicate an encoding transformation that has been
292: applied to a resource. Content cosings are primarily used to allow a document
293: to be compressed or encrypted without loosing the identity of its underlying
294: media type.
295: <DT>
296: <B>Content Transfer Codings</B>
297: <DD>
298: Content transfer codings values are used to indicate an encoding transformation
299: that has been, can be, or may be need to be applied to an enity body in order
300: to ensure safe transport through the network. This differs from a content
301: coding in that the transfer coding is a property of the message, not the
302: original message.
2.64 frystyk 303: </DL>
2.67 frystyk 304: <P>
305: Both types of encodings use the same registration mechanism in the Library
306: which we describe below:
307: <H3>
308: Encoders and Decoders
309: </H3>
310: <P>
311: <EM>Encoders</EM> and <EM>decoders</EM> are subclassed from the
312: <A HREF="HTStream.html">generic stream class</A>. <EM>Encoders</EM> are capable
313: of adding a content coding to a data object and <EM>decoders</EM> can remove
314: a content coding.
2.50 frystyk 315: <PRE>
2.64 frystyk 316: typedef HTStream * HTCoder (HTRequest * request,
317: void * param,
318: HTEncoding coding,
319: HTStream * target);
2.50 frystyk 320: </PRE>
2.67 frystyk 321: <P>
322: The <EM>encoding</EM> is the name of the encoding mechanism reporesented
323: as an <A HREF="HTAtom.html">atom</A>, for example "zip", "chunked", etc.
324: Encodings are registered in lists and content encodings are separated from
325: transfer encodings by registering them in different lists.
326: <H3>
327: The HTCoding Object
328: </H3>
329: <P>
330: The <EM>HTCoding</EM> object represents a registered encoding together with
331: a encoder and a decoder.
2.63 frystyk 332: <PRE>
2.64 frystyk 333: typedef struct _HTCoding HTCoding;
2.63 frystyk 334: </PRE>
2.67 frystyk 335: <P>
336: Predefined Coding Types We have a set of pre defined atoms for various types
337: of content encodings and transfer encodings. "chunked" is not exactly in
338: the same group as the other encodings such as "binary" but it really doesn't
339: make any difference as it is just a matter of how the words are chosen. The
340: first three transfer encodings are actually not encodings - they are just
341: left overs from brain dead mail systems.
2.42 frystyk 342: <PRE>
2.63 frystyk 343: #define WWW_CTE_7BIT HTAtom_for("7bit")
344: #define WWW_CTE_8BIT HTAtom_for("8bit")
345: #define WWW_CTE_BINARY HTAtom_for("binary")
2.64 frystyk 346:
2.63 frystyk 347: #define WWW_CTE_BASE64 HTAtom_for("base64")
348: #define WWW_CTE_MACBINHEX HTAtom_for("macbinhex")
2.64 frystyk 349: #define WWW_CTE_CHUNKED HTAtom_for("chunked")
2.63 frystyk 350:
351: #define WWW_CE_COMPRESS HTAtom_for("compress")
352: #define WWW_CE_GZIP HTAtom_for("gzip")
2.42 frystyk 353: </PRE>
2.67 frystyk 354: <H3>
355: Register Content Coders
356: </H3>
357: <P>
2.73 ! frystyk 358: Some documents are not send in their original data obejct but is encoded
! 359: in some way. On the Web this is mostly some kind of compression but other
! 360: encodings for example base 64 can be encountered when talking to NNTP servers
! 361: etc. Just as for the other preferences, an application can register a supported
! 362: encoders or decodes as a list. Encoders and decoders are registered in the
! 363: same way with no differentiation whether it is a encoder or a decoder:
2.42 frystyk 364: <PRE>
2.64 frystyk 365: extern BOOL HTCoding_add (HTList * list,
366: const char * encoding,
367: HTCoder * encoder,
368: HTCoder * decoder,
369: double quality);
2.63 frystyk 370:
2.64 frystyk 371: extern void HTCoding_deleteAll (HTList * list);
2.42 frystyk 372:
2.64 frystyk 373: extern const char * HTCoding_name (HTCoding * me);
2.42 frystyk 374: </PRE>
2.67 frystyk 375: <H2>
376: <A NAME="charset">Content Charsets</A>
377: </H2>
2.73 ! frystyk 378: <P>
! 379: As the Web reaches all parts of the Internet there are more and more documents
! 380: written in languages which contains characters not included in the ISO-8859-1
! 381: character set. A consequence of this the set of characters sets is often
! 382: tightly connected with the natural language. libwww does not directly support
! 383: other character sets but in case an application is capable of handling
! 384: alternative sets it can register these as preferred character sets along
! 385: with a quality factor just as all the other preferences in this section.
! 386: <PRE>extern void HTCharset_add (HTList * list, const char * charset, double quality);
2.42 frystyk 387: </PRE>
2.73 ! frystyk 388: <PRE>typedef struct _HTAcceptNode {
2.63 frystyk 389: HTAtom * atom;
390: double quality;
391: } HTAcceptNode;
392: </PRE>
393: <PRE>
2.50 frystyk 394: extern void HTCharset_deleteAll (HTList * list);
395: </PRE>
2.67 frystyk 396: <H2>
397: <A NAME="language">Content Languages</A>
398: </H2>
2.73 ! frystyk 399: <P>
! 400: The preferred natural language or languages is in almost all situations dependent
! 401: on the individual user and an application should therefore give the user
! 402: the opportunity to change the setup. When specifying a natural language
! 403: preference, libwww will send this preference along with all HTTP requests.
! 404: The remote server will then (it if supports this feature) look for a version
! 405: in the language or languages mentioned. If it finds a matching document then
! 406: it returns this one, otherwise it uses the best alternative. If no language
! 407: is specified the remote server may whatever version it finds.
! 408: <PRE>extern void HTLanguage_add (HTList * list, const char * lang, double quality);
2.51 frystyk 409: extern void HTLanguage_deleteAll (HTList * list);
2.50 frystyk 410: </PRE>
2.67 frystyk 411: <H2>
412: <A NAME="global">Global Preferences</A>
413: </H2>
414: <P>
2.50 frystyk 415: There are two places where these preferences can be registered: in a
2.67 frystyk 416: <EM>global</EM> list valid for <B>all</B> requests and a <EM>local</EM> list
417: valid for a particular request only. These are valid for <EM>all</EM> requests.
418: See the <A HREF="HTReq.html">Request Manager</A> fro local sets.
419: <H3>
2.73 ! frystyk 420: Global Converters and Presenters
2.67 frystyk 421: </H3>
422: <P>
423: The <EM>global</EM> list of specific conversions which the format manager
424: can do in order to fulfill the request. There is also a
425: <A HREF="HTReq.html"><EM>local</EM></A> list of conversions which contains
426: a generic set of possible conversions.
2.73 ! frystyk 427: <PRE>extern void HTFormat_setConversion (HTList * list);
2.50 frystyk 428: extern HTList * HTFormat_conversion (void);
2.69 frystyk 429:
430: extern void HTFormat_addConversion (const char * input_format,
431: const char * output_format,
432: HTConverter * converter,
433: double quality,
434: double secs,
435: double secs_per_byte);
2.31 frystyk 436: </PRE>
2.67 frystyk 437: <H3>
2.73 ! frystyk 438: Global Content Codings
2.67 frystyk 439: </H3>
2.73 ! frystyk 440: <PRE>extern void HTFormat_setContentCoding (HTList * list);
2.64 frystyk 441: extern HTList * HTFormat_contentCoding (void);
2.69 frystyk 442:
443: extern BOOL HTFormat_addCoding ( char * encoding,
444: HTCoder * encoder,
445: HTCoder * decoder,
446: double quality);
2.50 frystyk 447: </PRE>
2.67 frystyk 448: <H3>
2.73 ! frystyk 449: Global Content Transfer Codings
2.67 frystyk 450: </H3>
2.73 ! frystyk 451: <PRE>extern void HTFormat_setTransferCoding (HTList * list);
2.64 frystyk 452: extern HTList * HTFormat_transferCoding (void);
2.69 frystyk 453:
454: extern BOOL HTFormat_addTransferCoding ( char * encoding,
455: HTCoder * encoder,
456: HTCoder * decoder,
457: double quality);
2.64 frystyk 458: </PRE>
2.67 frystyk 459: <P>
460: We also define a macro to find out whether a transfer encoding is really
461: an encoding or whether it is just a "dummy" as for example 7bit, 8bit, and
462: binary.
2.64 frystyk 463: <PRE>
464: #define HTFormat_isUnityTransfer(me) \
465: ((me)==NULL \
466: || (me)==WWW_CTE_BINARY || (me)==WWW_CTE_7BIT || (me)==WWW_CTE_8BIT)
467: </PRE>
2.67 frystyk 468: <H3>
2.73 ! frystyk 469: Global Content Languages
2.67 frystyk 470: </H3>
2.73 ! frystyk 471: <PRE>extern void HTFormat_setLanguage (HTList * list);
2.50 frystyk 472: extern HTList * HTFormat_language (void);
473: </PRE>
2.67 frystyk 474: <H3>
2.73 ! frystyk 475: Global Content Charsets
2.67 frystyk 476: </H3>
2.73 ! frystyk 477: <PRE>extern void HTFormat_setCharset (HTList * list);
2.50 frystyk 478: extern HTList * HTFormat_charset (void);
2.31 frystyk 479: </PRE>
2.67 frystyk 480: <H3>
481: Delete All Global Lists
482: </H3>
483: <P>
2.50 frystyk 484: This is a convenience function that might make life easier.
2.73 ! frystyk 485: <PRE>extern void HTFormat_deleteAll (void);
2.34 frystyk 486: </PRE>
2.67 frystyk 487: <H2>
488: <A NAME="CTStack">The Content Type Stream Stack</A>
489: </H2>
490: <P>
491: This is the routine which actually sets up the content type conversion. It
492: currently checks only for direct conversions, but multi-stage conversions
493: are forseen. It takes a stream into which the output should be sent in the
494: final format, builds the conversion stack, and returns a stream into which
495: the data in the input format should be fed. If <CODE>guess</CODE> is true
496: and input format is <CODE>www/unknown</CODE>, try to guess the format by
497: looking at the first few bytes of the stream.
2.31 frystyk 498: <PRE>
2.52 frystyk 499: extern HTStream * HTStreamStack (HTFormat rep_in,
500: HTFormat rep_out,
501: HTStream * output_stream,
502: HTRequest * request,
503: BOOL guess);
2.1 timbl 504: </PRE>
2.67 frystyk 505: <H3>
506: Cost of a Stream Stack
507: </H3>
508: <P>
509: Must return the cost of the same stack which HTStreamStack would set up.
2.31 frystyk 510: <PRE>
2.52 frystyk 511: extern double HTStackValue (HTList * conversions,
512: HTFormat format_in,
513: HTFormat format_out,
514: double initial_value,
515: long int length);
2.64 frystyk 516: </PRE>
2.67 frystyk 517: <H2>
518: <A NAME="CEStack">Content Encoding Stream Stack</A>
519: </H2>
520: <P>
521: When creating a coding stream stack, it is important that we keep the right
522: order of encoders and decoders. As an example, the HTTP spec specifies that
523: the list in the <EM>Content-Encoding</EM> header follows the order in which
524: the encodings have been applied to the object. Internally, we represent the
525: content encodings as <A HREF="HTAtom.html">atoms</A> in a linked
526: <A HREF="HTList.html">list object</A>.
527: <P>
528: The creation of the content coding stack is not based on quality factors
529: as we don't have the freedom as with content types. When using content codings
530: we <EM>must</EM> apply the codings specified or fail.
2.64 frystyk 531: <PRE>
532: extern HTStream * HTContentCodingStack (HTEncoding coding,
533: HTStream * target,
534: HTRequest * request,
535: void * param,
536: BOOL encoding);
537: </PRE>
2.67 frystyk 538: <P>
539: Here you can provide a complete list instead of a single token. The list
540: has to be filled up in the order the _encodings_ are to be applied
2.64 frystyk 541: <PRE>
542: extern HTStream * HTContentEncodingStack (HTList * encodings,
543: HTStream * target,
544: HTRequest * request,
545: void * param);
546: </PRE>
2.67 frystyk 547: <P>
548: Here you can provide a complete list instead of a single token. The list
549: has to be in the order the _encodings_ were applied - that is, the same way
550: that _encodings_ are to be applied. This is all consistent with the order
551: of the Content-Encoding header.
2.64 frystyk 552: <PRE>
553: extern HTStream * HTContentDecodingStack (HTList * encodings,
554: HTStream * target,
555: HTRequest * request,
556: void * param);
557: </PRE>
2.67 frystyk 558: <H2>
559: <A NAME="CTEStack">Content Transfer Encoding Stream Stack</A>
560: </H2>
561: <P>
562: Creating the transfer content encoding stream stack is not based on quality
563: factors as we don't have the freedom as with content types. Specify whether
564: you you want encoding or decoding using the BOOL "encode" flag.
2.64 frystyk 565: <PRE>
566: extern HTStream * HTTransferCodingStack (HTEncoding encoding,
567: HTStream * target,
568: HTRequest * request,
569: void * param,
570: BOOL encode);
571: </PRE>
2.73 ! frystyk 572: <H3>
! 573: Presentation Object
! 574: </H3>
! 575: <P>
! 576: This object is not to be used - it should have been hidden
! 577: <PRE>typedef struct _HTPresentation {
! 578: HTFormat rep; /* representation name atomized */
! 579: HTFormat rep_out; /* resulting representation */
! 580: HTConverter *converter; /* The routine to gen the stream stack */
! 581: char * command; /* MIME-format string */
! 582: char * test_command; /* MIME-format string */
! 583: double quality; /* Between 0 (bad) and 1 (good) */
! 584: double secs;
! 585: double secs_per_byte;
! 586: } HTPresentation;
! 587: </PRE>
2.64 frystyk 588: <PRE>
2.42 frystyk 589: #endif /* HTFORMAT */
2.38 frystyk 590: </PRE>
2.67 frystyk 591: <P>
592: <HR>
2.63 frystyk 593: <ADDRESS>
2.73 ! frystyk 594: @(#) $Id: HTFormat.html,v 2.72 1996/10/07 02:04:41 frystyk Exp $
2.63 frystyk 595: </ADDRESS>
2.67 frystyk 596: </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