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