Annotation of libwww/Library/src/HTFormat.html, revision 2.43
2.10 timbl 1: <HTML>
2: <HEAD>
2.31 frystyk 3: <TITLE>The Format Manager in the WWW Library</TITLE>
2.15 timbl 4: <NEXTID N="z18">
2.10 timbl 5: </HEAD>
2.1 timbl 6: <BODY>
2.27 frystyk 7:
2.31 frystyk 8: <H1>The Format Manager</H1>
2.33 frystyk 9:
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.31 frystyk 16:
17: Here we describe the functions of the HTFormat module which handles
18: conversion between different data representations. (In MIME parlance,
19: a representation is known as a content-type. In <A
2.38 frystyk 20: HREF="http://www.w3.org/hypertext/WWW/TheProject.html">WWW</A> the
2.31 frystyk 21: term <EM>format</EM> is often used as it is shorter). The content of
22: this module is:
23:
24: <UL>
2.42 frystyk 25: <LI><A HREF="#converter">Converters</A>
26: <LI><A HREF="#user">User Preferences (media type, language, charset etc.)</A>
27: <LI><A HREF="#Rank">Content Negotiation</A>
2.31 frystyk 28: <LI><A HREF="#z3">The Stream Stack</A>
29: </UL>
30:
31: This module is implemented by <A HREF="HTFormat.c">HTFormat.c</A>, and
32: it is a part of the <A NAME="z10"
2.43 ! frystyk 33: HREF="http://www.w3.org/hypertext/WWW/Library/">
! 34: W3C Reference Library</A>.
2.27 frystyk 35:
2.31 frystyk 36: <PRE>
37: #ifndef HTFORMAT_H
2.1 timbl 38: #define HTFORMAT_H
39:
2.31 frystyk 40: #include <A HREF="HTUtils.html">"HTUtils.h"</A>
41: #include <A HREF="HTStream.html">"HTStream.h"</A>
42: #include <A HREF="HTAtom.html">"HTAtom.h"</A>
43: #include <A HREF="HTList.html">"HTList.h"</A>
2.42 frystyk 44: #include <A HREF="HTAnchor.html">"HTAnchor.h"</A>
45: #include <A HREF="HTAccess.html">"HTAccess.h"</A>
2.31 frystyk 46: </PRE>
2.1 timbl 47:
2.42 frystyk 48: <A NAME="converter"><H2>Stream Converters</H2></A>
2.18 luotonen 49:
2.42 frystyk 50: A <CODE><A NAME="z12">converter</A></CODE> is a stream with a special
51: set of parameters and which is registered as capable of converting
52: from a MIME type to something else (maybe another MIME-type). A
53: converter is defined to be a function returning a stream and accepting
54: the following parameters. The content type elements are atoms for
55: which we have defined a prototype.
2.18 luotonen 56:
2.31 frystyk 57: <PRE>
2.42 frystyk 58: typedef HTStream * HTConverter PARAMS((HTRequest * request,
59: void * param,
60: HTFormat input_format,
61: HTFormat output_format,
62: HTStream * output_stream));
63: </PRE>
2.18 luotonen 64:
2.42 frystyk 65: <A NAME="user"><H2>User Preferences</H2></A>
2.31 frystyk 66:
2.42 frystyk 67: The Library contains functionality for letting the application (or
68: user) express the preferences for the rendition of a given data object
69: when issuing a request. The categories supported are:
70:
71: <UL>
72: <LI>Content type (media type)
73: <LI>Encoding
74: <LI>Language
75: <LI>Charset
76: </UL>
2.17 luotonen 77:
2.42 frystyk 78: There are two places where these preferences can be registered: in a
79: <EM>global</EM> list valid for <B>all</B> requests and a
80: <EM>local</EM> list valid for a particular request only. The elements
81: are all <A HREF="HTAtom.html">atoms</A> representations. This allows
82: faster manipulation (comparison and copying) that if we stayed with
83: strings.
2.31 frystyk 84:
2.42 frystyk 85: <A NAME="FormatTypes"><H3>Registration of Accepted Content Types</H3></A>
2.17 luotonen 86:
2.42 frystyk 87: A <CODE>presenter</CODE> is a module (possibly an external program)
88: which can present a graphic object of a certain MIME type to the
89: user. That is, <CODE>presenters</CODE> are normally used to present
90: objects that the <CODE>converters</CODE> are not able to handle. Data
91: is transferred to the external program using for example the <A
92: HREF="HTFWrite.html">HTSaveAndExecute</A> stream which writes to a
93: local file. Both presenters and converters are of the type <A
94: HREF="#converter">HTConverter</A>.
2.31 frystyk 95:
96: <PRE>
2.42 frystyk 97: typedef struct _HTPresentation {
98: HTFormat rep; /* representation name atomized */
99: HTFormat rep_out; /* resulting representation */
100: HTConverter *converter; /* The routine to gen the stream stack */
101: char * command; /* MIME-format string */
102: char * test_command; /* MIME-format string */
103: double quality; /* Between 0 (bad) and 1 (good) */
104: double secs;
105: double secs_per_byte;
106: } HTPresentation;
2.25 luotonen 107:
2.42 frystyk 108: extern HTList * HTConversions; /* Global list of converters and presenters */
2.28 frystyk 109: </PRE>
110:
2.42 frystyk 111: <H4>Predefined Content Types</H4>
2.28 frystyk 112:
2.42 frystyk 113: These macros (which used to be constants) define some basic internally
114: referenced representations. The <CODE>www/xxx</CODE> ones are of
115: course not MIME standard. <CODE>star/star</CODE> is an output format
116: which leaves the input untouched. It is useful for diagnostics, and
117: for users who want to see the original, whatever it is.
2.28 frystyk 118:
119: <PRE>
120: #define WWW_SOURCE HTAtom_for("*/*") /* Whatever it was originally */
121: </PRE>
122:
2.31 frystyk 123: <CODE>www/present</CODE> represents the user's perception of the
124: document. If you convert to www/present, you present the material to
125: the user.
2.10 timbl 126:
2.28 frystyk 127: <PRE>
128: #define WWW_PRESENT HTAtom_for("www/present") /* The user's perception */
129: </PRE>
130:
131: The message/rfc822 format means a MIME message or a plain text message
132: with no MIME header. This is what is returned by an HTTP server.
133:
134: <PRE>
135: #define WWW_MIME HTAtom_for("www/mime") /* A MIME message */
136: </PRE>
137:
2.31 frystyk 138: <CODE>www/unknown</CODE> is a really unknown type. Some default
139: action is appropriate.
2.13 timbl 140:
2.28 frystyk 141: <PRE>
142: #define WWW_UNKNOWN HTAtom_for("www/unknown")
2.13 timbl 143: </PRE>
2.28 frystyk 144:
2.31 frystyk 145: These are regular MIME types defined. Others can be added!
2.28 frystyk 146:
147: <PRE>
148: #define WWW_PLAINTEXT HTAtom_for("text/plain")
2.1 timbl 149: #define WWW_POSTSCRIPT HTAtom_for("application/postscript")
150: #define WWW_RICHTEXT HTAtom_for("application/rtf")
2.10 timbl 151: #define WWW_AUDIO HTAtom_for("audio/basic")
2.1 timbl 152: #define WWW_HTML HTAtom_for("text/html")
2.11 timbl 153: #define WWW_BINARY HTAtom_for("application/octet-stream")
2.26 frystyk 154: #define WWW_VIDEO HTAtom_for("video/mpeg")
2.38 frystyk 155: #define WWW_GIF HTAtom_for("image/gif")
2.28 frystyk 156: </PRE>
157:
2.42 frystyk 158: <H4>Register a Presenter</H4>
2.31 frystyk 159:
2.1 timbl 160: <DL>
2.31 frystyk 161: <DT>conversions
162: <DD>The list of <CODE>conveters</CODE> and <CODE>presenters</CODE>
163: <DT>representation
2.42 frystyk 164: <DD>the MIME-style format name
2.1 timbl 165: <DT>command
2.31 frystyk 166: <DD>the MAILCAP-style command template
2.1 timbl 167: <DT>quality
2.31 frystyk 168: <DD>A degradation faction [0..1]
2.1 timbl 169: <DT>maxbytes
2.31 frystyk 170: <DD>A limit on the length acceptable as input (0 infinite)
2.1 timbl 171: <DT>maxsecs
2.31 frystyk 172: <DD>A limit on the time user will wait (0 for infinity)
2.1 timbl 173: </DL>
174:
2.31 frystyk 175: <PRE>
176: extern void HTSetPresentation PARAMS((HTList * conversions,
177: CONST char * representation,
178: CONST char * command,
179: CONST char * test_command,
2.37 frystyk 180: double quality,
181: double secs,
182: double secs_per_byte));
2.31 frystyk 183: </PRE>
2.1 timbl 184:
2.42 frystyk 185: <H4>Register a Converter</H4>
2.1 timbl 186:
187: <DL>
2.31 frystyk 188: <DT>conversions
189: <DD>The list of <CODE>conveters</CODE> and <CODE>presenters</CODE>
2.1 timbl 190: <DT>rep_in
2.42 frystyk 191: <DD>the MIME-style format name
2.1 timbl 192: <DT>rep_out
2.31 frystyk 193: <DD>is the resulting content-type after the conversion
2.1 timbl 194: <DT>converter
2.31 frystyk 195: <DD>is the routine to call which actually does the conversion
196: <DT>quality
197: <DD>A degradation faction [0..1]
198: <DT>maxbytes
199: <DD>A limit on the length acceptable as input (0 infinite)
200: <DT>maxsecs
201: <DD>A limit on the time user will wait (0 for infinity)
2.1 timbl 202: </DL>
203:
204: <PRE>
2.31 frystyk 205: extern void HTSetConversion PARAMS((HTList * conversions,
206: CONST char * rep_in,
207: CONST char * rep_out,
208: HTConverter * converter,
2.37 frystyk 209: double quality,
210: double secs,
211: double secs_per_byte));
2.31 frystyk 212: </PRE>
213:
2.42 frystyk 214: <H4>Set up Default Presenters and Converters</H4>
215:
216: The <A HREF="HTInit.c">HTInit module</A> defines a default set of
217: <CODE>converters</CODE> and <CODE>presenters</CODE>. However, no
218: automatic initialization is done in the Library, so this is for the
219: application to do!
220:
221: <PRE>
222: extern void HTFormatInit PARAMS((HTList * conversions));
223: </PRE>
224:
225: <A NAME="Encoding"><H3>Registration of Accepted Content Encodings</H3></A>
226:
227: Encodings are the HTTP extension of transfer encodings. Encodings
228: include compress, gzip etc. These are the data structures:
229:
230: <PRE>
231: typedef struct _HTAcceptNode {
232: HTAtom * atom;
233: double quality;
234: } HTAcceptNode;
235:
236: extern HTList * HTEncodings; /* Global list of encodings */
237: </PRE>
238:
239: <H4>Predefined Encoding Types</H4>
240:
241: <PRE>
242: #define WWW_ENC_7BIT HTAtom_for("7bit")
243: #define WWW_ENC_8BIT HTAtom_for("8bit")
244: #define WWW_ENC_BINARY HTAtom_for("binary")
245: #define WWW_ENC_BASE64 HTAtom_for("base64")
246: #define WWW_ENC_COMPRESS HTAtom_for("compress")
247: #define WWW_ENC_GZIP HTAtom_for("gzip")
248: </PRE>
249:
250: <H4>Register an Encoding</H4>
251:
252: <PRE>
253: extern void HTAcceptEncoding PARAMS((HTList * list,
254: CONST char * enc,
255: double quality));
256: </PRE>
2.31 frystyk 257:
2.42 frystyk 258: <H3><A NAME="charset">Registration of Accepted Charsets</A></H3>
2.31 frystyk 259:
2.42 frystyk 260: We use the same <CODE>HTAcceptNode</CODE> as above.
2.31 frystyk 261:
262: <PRE>
2.42 frystyk 263: extern HTList * HTCharsets; /* Global list of charsets */
264: </PRE>
265:
266: <H4>Register a Charset</H4>
267:
268: <PRE>
269: extern void HTAcceptCharset PARAMS((HTList * list,
270: CONST char * charset,
271: double quality));
272: </PRE>
273:
274: <A NAME="Language"><H3>Registration of Accepted Content Languages</H3></A>
275:
276: We use the same <CODE>HTAcceptNode</CODE> as above.
277:
278: <PRE>
279: extern HTList * HTLanguages; /* Global list of languages */
2.31 frystyk 280: </PRE>
281:
2.42 frystyk 282: <H4>Register a Language</H4>
2.31 frystyk 283:
284: <PRE>
2.42 frystyk 285: extern void HTAcceptLanguage PARAMS((HTList * list,
286: CONST char * lang,
287: double quality));
2.31 frystyk 288: </PRE>
289:
2.42 frystyk 290: <H3>Garbage Collection of User Preferences</H3>
291:
292: This is used for cleaning up the lists of user preferences, both the
293: local and the global lists:
2.1 timbl 294:
2.42 frystyk 295: <H3>Remove Local Preferences</H3>
296:
297: The function is called from <A HREF="HTAccess.html#z100">HTRequest_delete</A>.
2.1 timbl 298:
2.31 frystyk 299: <PRE>
300: extern void HTFormatDelete PARAMS((HTRequest * request));
301: </PRE>
302:
2.42 frystyk 303: <H3>Remove Global Preferences</H3>
304:
305: The function is called from <A HREF="HTAccess.html#Library">HTLibTerminate</A>.
2.34 frystyk 306:
307: <PRE>
308: extern void HTDisposeConversions NOPARAMS;
309: </PRE>
2.31 frystyk 310:
311: <A NAME="Rank"><H2>Ranking of Accepted Formats</H2></A>
312:
2.36 frystyk 313: This function is used when the best match among several possible
314: documents is to be found as a function of the accept headers sent in
315: the client request.
2.31 frystyk 316:
317: <PRE>
2.42 frystyk 318: typedef struct _HTContentDescription {
319: char * filename;
320: HTAtom * content_type;
321: HTAtom * content_language;
322: HTAtom * content_encoding;
323: int content_length;
324: double quality;
325: } HTContentDescription;
326:
2.32 frystyk 327: extern BOOL HTRank PARAMS((HTList * possibilities,
2.31 frystyk 328: HTList * accepted_content_types,
329: HTList * accepted_content_languages,
330: HTList * accepted_content_encodings));
2.1 timbl 331: </PRE>
2.31 frystyk 332:
2.42 frystyk 333: <H2><A NAME="z3">The Stream Stack</A></H2>
2.31 frystyk 334:
335: This is the routine which actually sets up the conversion. It
336: currently checks only for direct conversions, but multi-stage
337: conversions are forseen. It takes a stream into which the output
338: should be sent in the final format, builds the conversion stack, and
339: returns a stream into which the data in the input format should be
2.42 frystyk 340: fed. If <CODE>guess</CODE> is true and input format is
2.31 frystyk 341: <CODE>www/unknown</CODE>, try to guess the format by looking at the
342: first few bytes of the stream. <P>
2.1 timbl 343:
2.31 frystyk 344: <PRE>
2.32 frystyk 345: extern HTStream * HTStreamStack PARAMS((HTFormat rep_in,
2.31 frystyk 346: HTFormat rep_out,
347: HTStream * output_stream,
348: HTRequest * request,
349: BOOL guess));
2.1 timbl 350: </PRE>
2.31 frystyk 351:
2.42 frystyk 352: <H2>Cost of a Stream Stack</H2>
2.31 frystyk 353:
354: Must return the cost of the same stack which HTStreamStack would set
2.1 timbl 355: up.
356:
2.31 frystyk 357: <PRE>
2.37 frystyk 358: extern double HTStackValue PARAMS((HTList * conversions,
2.31 frystyk 359: HTFormat format_in,
360: HTFormat format_out,
2.37 frystyk 361: double initial_value,
2.31 frystyk 362: long int length));
363:
2.42 frystyk 364: #endif /* HTFORMAT */
2.38 frystyk 365: </PRE>
366:
2.42 frystyk 367: End of declaration module
2.31 frystyk 368:
369: </BODY>
2.10 timbl 370: </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