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