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