Annotation of libwww/Library/src/HTFormat.html, revision 2.49
2.10 timbl 1: <HTML>
2: <HEAD>
2.45 frystyk 3: <TITLE>Format Negotiation Manager</TITLE>
2.49 ! frystyk 4: <!-- Changed by: Henrik Frystyk Nielsen, 28-Oct-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>
2.49 ! frystyk 27: <LI><A HREF="#user">Global Preferences (media type, language, charset etc.)</A>
2.42 frystyk 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
2.49 ! frystyk 33: it is a part of the <A HREF="http://www.w3.org/pub/WWW/Library/"> W3C
! 34: 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>
2.47 frystyk 45: #include <A HREF="HTReq.html">"HTReq.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.49 ! frystyk 85: <H3>Global Registrations</H3>
! 86:
! 87: These are valid for <EM>all</EM> requests
! 88:
! 89: <H4>Content Types</H4>
! 90:
! 91: The <EM>global</EM> list of specific conversions which the format
! 92: manager can do in order to fulfill the request. There is also a <A
! 93: HREF="HTReq.html"><EM>local</EM></A> list of conversions which
! 94: contains a generic set of possible conversions.
! 95:
! 96: <PRE>
! 97: extern void HTFormat_setConversion (HTList *list);
! 98: extern HTList * HTFormat_conversion (void);
! 99: </PRE>
! 100:
! 101: <H4>Content Encodings</H4>
! 102:
! 103: <PRE>
! 104: extern void HTFormat_setEncoding (HTList *list);
! 105: extern HTList * HTFormat_encoding (void);
! 106: </PRE>
! 107:
! 108: <H4>Content Encodings</H4>
! 109:
! 110: <PRE>
! 111: extern void HTFormat_setLanguage (HTList *list);
! 112: extern HTList * HTFormat_language (void);
! 113: </PRE>
! 114:
! 115: <H4>Content Encodings</H4>
! 116:
! 117: <PRE>
! 118: extern void HTFormat_setCharset (HTList *list);
! 119: extern HTList * HTFormat_charset (void);
! 120: </PRE>
! 121:
2.42 frystyk 122: <A NAME="FormatTypes"><H3>Registration of Accepted Content Types</H3></A>
2.17 luotonen 123:
2.42 frystyk 124: A <CODE>presenter</CODE> is a module (possibly an external program)
125: which can present a graphic object of a certain MIME type to the
126: user. That is, <CODE>presenters</CODE> are normally used to present
127: objects that the <CODE>converters</CODE> are not able to handle. Data
128: is transferred to the external program using for example the <A
129: HREF="HTFWrite.html">HTSaveAndExecute</A> stream which writes to a
130: local file. Both presenters and converters are of the type <A
131: HREF="#converter">HTConverter</A>.
2.31 frystyk 132:
133: <PRE>
2.42 frystyk 134: typedef struct _HTPresentation {
135: HTFormat rep; /* representation name atomized */
136: HTFormat rep_out; /* resulting representation */
137: HTConverter *converter; /* The routine to gen the stream stack */
138: char * command; /* MIME-format string */
139: char * test_command; /* MIME-format string */
140: double quality; /* Between 0 (bad) and 1 (good) */
141: double secs;
142: double secs_per_byte;
143: } HTPresentation;
2.28 frystyk 144: </PRE>
145:
2.42 frystyk 146: <H4>Predefined Content Types</H4>
2.28 frystyk 147:
2.42 frystyk 148: These macros (which used to be constants) define some basic internally
149: referenced representations. The <CODE>www/xxx</CODE> ones are of
150: course not MIME standard. <CODE>star/star</CODE> is an output format
151: which leaves the input untouched. It is useful for diagnostics, and
152: for users who want to see the original, whatever it is.
2.28 frystyk 153:
154: <PRE>
155: #define WWW_SOURCE HTAtom_for("*/*") /* Whatever it was originally */
156: </PRE>
157:
2.31 frystyk 158: <CODE>www/present</CODE> represents the user's perception of the
159: document. If you convert to www/present, you present the material to
160: the user.
2.10 timbl 161:
2.28 frystyk 162: <PRE>
163: #define WWW_PRESENT HTAtom_for("www/present") /* The user's perception */
164: </PRE>
165:
166: The message/rfc822 format means a MIME message or a plain text message
167: with no MIME header. This is what is returned by an HTTP server.
168:
169: <PRE>
170: #define WWW_MIME HTAtom_for("www/mime") /* A MIME message */
171: </PRE>
172:
2.31 frystyk 173: <CODE>www/unknown</CODE> is a really unknown type. Some default
174: action is appropriate.
2.13 timbl 175:
2.28 frystyk 176: <PRE>
177: #define WWW_UNKNOWN HTAtom_for("www/unknown")
2.13 timbl 178: </PRE>
2.28 frystyk 179:
2.31 frystyk 180: These are regular MIME types defined. Others can be added!
2.28 frystyk 181:
182: <PRE>
183: #define WWW_PLAINTEXT HTAtom_for("text/plain")
2.1 timbl 184: #define WWW_POSTSCRIPT HTAtom_for("application/postscript")
185: #define WWW_RICHTEXT HTAtom_for("application/rtf")
2.10 timbl 186: #define WWW_AUDIO HTAtom_for("audio/basic")
2.1 timbl 187: #define WWW_HTML HTAtom_for("text/html")
2.11 timbl 188: #define WWW_BINARY HTAtom_for("application/octet-stream")
2.26 frystyk 189: #define WWW_VIDEO HTAtom_for("video/mpeg")
2.38 frystyk 190: #define WWW_GIF HTAtom_for("image/gif")
2.44 frystyk 191: #define WWW_PNG HTAtom_for("image/x-png") /* @@@ soon image/png @@@ */
2.48 frystyk 192: </PRE>
193:
194: We also have some that come from the various protocols
195:
196: <PRE>
197: #define WWW_GOPHER_MENU HTAtom_for("text/x-gopher")
198:
199: #define WWW_FTP_LNST HTAtom_for("text/x-ftp-lnst")
200: #define WWW_FTP_LIST HTAtom_for("text/x-ftp-list")
201:
202: #define WWW_NNTP_LIST HTAtom_for("text/x-nntp-list")
203: #define WWW_NNTP_OVER HTAtom_for("text/x-nntp-over")
204: #define WWW_NNTP_HEAD HTAtom_for("text/x-nntp-head")
2.28 frystyk 205: </PRE>
206:
2.42 frystyk 207: <H4>Register a Presenter</H4>
2.31 frystyk 208:
2.1 timbl 209: <DL>
2.31 frystyk 210: <DT>conversions
211: <DD>The list of <CODE>conveters</CODE> and <CODE>presenters</CODE>
212: <DT>representation
2.42 frystyk 213: <DD>the MIME-style format name
2.1 timbl 214: <DT>command
2.31 frystyk 215: <DD>the MAILCAP-style command template
2.1 timbl 216: <DT>quality
2.31 frystyk 217: <DD>A degradation faction [0..1]
2.1 timbl 218: <DT>maxbytes
2.31 frystyk 219: <DD>A limit on the length acceptable as input (0 infinite)
2.1 timbl 220: <DT>maxsecs
2.31 frystyk 221: <DD>A limit on the time user will wait (0 for infinity)
2.1 timbl 222: </DL>
223:
2.31 frystyk 224: <PRE>
2.49 ! frystyk 225: extern void HTPresentation_add (HTList * conversions,
! 226: CONST char * representation,
! 227: CONST char * command,
! 228: CONST char * test_command,
! 229: double quality,
! 230: double secs,
! 231: double secs_per_byte);
2.31 frystyk 232: </PRE>
2.1 timbl 233:
2.42 frystyk 234: <H4>Register a Converter</H4>
2.1 timbl 235:
236: <DL>
2.31 frystyk 237: <DT>conversions
238: <DD>The list of <CODE>conveters</CODE> and <CODE>presenters</CODE>
2.1 timbl 239: <DT>rep_in
2.42 frystyk 240: <DD>the MIME-style format name
2.1 timbl 241: <DT>rep_out
2.31 frystyk 242: <DD>is the resulting content-type after the conversion
2.1 timbl 243: <DT>converter
2.31 frystyk 244: <DD>is the routine to call which actually does the conversion
245: <DT>quality
246: <DD>A degradation faction [0..1]
247: <DT>maxbytes
248: <DD>A limit on the length acceptable as input (0 infinite)
249: <DT>maxsecs
250: <DD>A limit on the time user will wait (0 for infinity)
2.1 timbl 251: </DL>
252:
253: <PRE>
2.49 ! frystyk 254: extern void HTConversion_add (HTList * conversions,
! 255: CONST char * rep_in,
! 256: CONST char * rep_out,
! 257: HTConverter * converter,
! 258: double quality,
! 259: double secs,
! 260: double secs_per_byte);
2.42 frystyk 261: </PRE>
262:
263: <A NAME="Encoding"><H3>Registration of Accepted Content Encodings</H3></A>
264:
265: Encodings are the HTTP extension of transfer encodings. Encodings
266: include compress, gzip etc. These are the data structures:
267:
268: <PRE>
269: typedef struct _HTAcceptNode {
270: HTAtom * atom;
271: double quality;
272: } HTAcceptNode;
273: </PRE>
274:
275: <H4>Predefined Encoding Types</H4>
276:
277: <PRE>
278: #define WWW_ENC_7BIT HTAtom_for("7bit")
279: #define WWW_ENC_8BIT HTAtom_for("8bit")
280: #define WWW_ENC_BINARY HTAtom_for("binary")
281: #define WWW_ENC_BASE64 HTAtom_for("base64")
282: #define WWW_ENC_COMPRESS HTAtom_for("compress")
283: #define WWW_ENC_GZIP HTAtom_for("gzip")
284: </PRE>
285:
286: <H4>Register an Encoding</H4>
287:
288: <PRE>
289: extern void HTAcceptEncoding PARAMS((HTList * list,
290: CONST char * enc,
291: double quality));
292: </PRE>
2.31 frystyk 293:
2.42 frystyk 294: <H3><A NAME="charset">Registration of Accepted Charsets</A></H3>
2.31 frystyk 295:
2.42 frystyk 296: We use the same <CODE>HTAcceptNode</CODE> as above.
2.31 frystyk 297:
2.42 frystyk 298: <H4>Register a Charset</H4>
299:
300: <PRE>
301: extern void HTAcceptCharset PARAMS((HTList * list,
302: CONST char * charset,
303: double quality));
304: </PRE>
305:
306: <A NAME="Language"><H3>Registration of Accepted Content Languages</H3></A>
307:
308: We use the same <CODE>HTAcceptNode</CODE> as above.
2.31 frystyk 309:
2.42 frystyk 310: <H4>Register a Language</H4>
2.31 frystyk 311:
312: <PRE>
2.42 frystyk 313: extern void HTAcceptLanguage PARAMS((HTList * list,
314: CONST char * lang,
315: double quality));
2.31 frystyk 316: </PRE>
317:
2.42 frystyk 318: <H3>Garbage Collection of User Preferences</H3>
319:
320: This is used for cleaning up the lists of user preferences, both the
321: local and the global lists:
2.1 timbl 322:
2.42 frystyk 323: <H3>Remove Local Preferences</H3>
324:
2.47 frystyk 325: The function is called from <A HREF="HTReq.html#z100">HTRequest_delete</A>.
2.1 timbl 326:
2.31 frystyk 327: <PRE>
328: extern void HTFormatDelete PARAMS((HTRequest * request));
329: </PRE>
330:
2.42 frystyk 331: <H3>Remove Global Preferences</H3>
332:
2.47 frystyk 333: The function is called from <A HREF="HTReq.html#Library">HTLibTerminate</A>.
2.34 frystyk 334:
335: <PRE>
336: extern void HTDisposeConversions NOPARAMS;
337: </PRE>
2.31 frystyk 338:
339: <A NAME="Rank"><H2>Ranking of Accepted Formats</H2></A>
340:
2.36 frystyk 341: This function is used when the best match among several possible
342: documents is to be found as a function of the accept headers sent in
343: the client request.
2.31 frystyk 344:
345: <PRE>
2.42 frystyk 346: typedef struct _HTContentDescription {
347: char * filename;
348: HTAtom * content_type;
349: HTAtom * content_language;
350: HTAtom * content_encoding;
351: int content_length;
352: double quality;
353: } HTContentDescription;
354:
2.32 frystyk 355: extern BOOL HTRank PARAMS((HTList * possibilities,
2.31 frystyk 356: HTList * accepted_content_types,
357: HTList * accepted_content_languages,
358: HTList * accepted_content_encodings));
2.1 timbl 359: </PRE>
2.31 frystyk 360:
2.42 frystyk 361: <H2><A NAME="z3">The Stream Stack</A></H2>
2.31 frystyk 362:
363: This is the routine which actually sets up the conversion. It
364: currently checks only for direct conversions, but multi-stage
365: conversions are forseen. It takes a stream into which the output
366: should be sent in the final format, builds the conversion stack, and
367: returns a stream into which the data in the input format should be
2.42 frystyk 368: fed. If <CODE>guess</CODE> is true and input format is
2.31 frystyk 369: <CODE>www/unknown</CODE>, try to guess the format by looking at the
370: first few bytes of the stream. <P>
2.1 timbl 371:
2.31 frystyk 372: <PRE>
2.32 frystyk 373: extern HTStream * HTStreamStack PARAMS((HTFormat rep_in,
2.31 frystyk 374: HTFormat rep_out,
375: HTStream * output_stream,
376: HTRequest * request,
377: BOOL guess));
2.1 timbl 378: </PRE>
2.31 frystyk 379:
2.42 frystyk 380: <H2>Cost of a Stream Stack</H2>
2.31 frystyk 381:
382: Must return the cost of the same stack which HTStreamStack would set
2.1 timbl 383: up.
384:
2.31 frystyk 385: <PRE>
2.37 frystyk 386: extern double HTStackValue PARAMS((HTList * conversions,
2.31 frystyk 387: HTFormat format_in,
388: HTFormat format_out,
2.37 frystyk 389: double initial_value,
2.31 frystyk 390: long int length));
391:
2.42 frystyk 392: #endif /* HTFORMAT */
2.38 frystyk 393: </PRE>
394:
2.42 frystyk 395: End of declaration module
2.31 frystyk 396:
397: </BODY>
2.10 timbl 398: </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