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