Annotation of libwww/Library/src/HTFormat.html, revision 2.48
2.10 timbl 1: <HTML>
2: <HEAD>
2.45 frystyk 3: <TITLE>Format Negotiation Manager</TITLE>
2.48 ! frystyk 4: <!-- Changed by: Henrik Frystyk Nielsen, 22-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>
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>
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.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.48 ! frystyk 158: </PRE>
! 159:
! 160: We also have some that come from the various protocols
! 161:
! 162: <PRE>
! 163: #define WWW_GOPHER_MENU HTAtom_for("text/x-gopher")
! 164:
! 165: #define WWW_FTP_LNST HTAtom_for("text/x-ftp-lnst")
! 166: #define WWW_FTP_LIST HTAtom_for("text/x-ftp-list")
! 167:
! 168: #define WWW_NNTP_LIST HTAtom_for("text/x-nntp-list")
! 169: #define WWW_NNTP_OVER HTAtom_for("text/x-nntp-over")
! 170: #define WWW_NNTP_HEAD HTAtom_for("text/x-nntp-head")
2.28 frystyk 171: </PRE>
172:
2.42 frystyk 173: <H4>Register a Presenter</H4>
2.31 frystyk 174:
2.1 timbl 175: <DL>
2.31 frystyk 176: <DT>conversions
177: <DD>The list of <CODE>conveters</CODE> and <CODE>presenters</CODE>
178: <DT>representation
2.42 frystyk 179: <DD>the MIME-style format name
2.1 timbl 180: <DT>command
2.31 frystyk 181: <DD>the MAILCAP-style command template
2.1 timbl 182: <DT>quality
2.31 frystyk 183: <DD>A degradation faction [0..1]
2.1 timbl 184: <DT>maxbytes
2.31 frystyk 185: <DD>A limit on the length acceptable as input (0 infinite)
2.1 timbl 186: <DT>maxsecs
2.31 frystyk 187: <DD>A limit on the time user will wait (0 for infinity)
2.1 timbl 188: </DL>
189:
2.31 frystyk 190: <PRE>
191: extern void HTSetPresentation PARAMS((HTList * conversions,
192: CONST char * representation,
193: CONST char * command,
194: CONST char * test_command,
2.37 frystyk 195: double quality,
196: double secs,
197: double secs_per_byte));
2.31 frystyk 198: </PRE>
2.1 timbl 199:
2.42 frystyk 200: <H4>Register a Converter</H4>
2.1 timbl 201:
202: <DL>
2.31 frystyk 203: <DT>conversions
204: <DD>The list of <CODE>conveters</CODE> and <CODE>presenters</CODE>
2.1 timbl 205: <DT>rep_in
2.42 frystyk 206: <DD>the MIME-style format name
2.1 timbl 207: <DT>rep_out
2.31 frystyk 208: <DD>is the resulting content-type after the conversion
2.1 timbl 209: <DT>converter
2.31 frystyk 210: <DD>is the routine to call which actually does the conversion
211: <DT>quality
212: <DD>A degradation faction [0..1]
213: <DT>maxbytes
214: <DD>A limit on the length acceptable as input (0 infinite)
215: <DT>maxsecs
216: <DD>A limit on the time user will wait (0 for infinity)
2.1 timbl 217: </DL>
218:
219: <PRE>
2.31 frystyk 220: extern void HTSetConversion PARAMS((HTList * conversions,
221: CONST char * rep_in,
222: CONST char * rep_out,
223: HTConverter * converter,
2.37 frystyk 224: double quality,
225: double secs,
226: double secs_per_byte));
2.31 frystyk 227: </PRE>
228:
2.42 frystyk 229: <H4>Set up Default Presenters and Converters</H4>
230:
231: The <A HREF="HTInit.c">HTInit module</A> defines a default set of
232: <CODE>converters</CODE> and <CODE>presenters</CODE>. However, no
233: automatic initialization is done in the Library, so this is for the
234: application to do!
235:
236: <PRE>
237: extern void HTFormatInit PARAMS((HTList * conversions));
238: </PRE>
239:
240: <A NAME="Encoding"><H3>Registration of Accepted Content Encodings</H3></A>
241:
242: Encodings are the HTTP extension of transfer encodings. Encodings
243: include compress, gzip etc. These are the data structures:
244:
245: <PRE>
246: typedef struct _HTAcceptNode {
247: HTAtom * atom;
248: double quality;
249: } HTAcceptNode;
250:
251: extern HTList * HTEncodings; /* Global list of encodings */
252: </PRE>
253:
254: <H4>Predefined Encoding Types</H4>
255:
256: <PRE>
257: #define WWW_ENC_7BIT HTAtom_for("7bit")
258: #define WWW_ENC_8BIT HTAtom_for("8bit")
259: #define WWW_ENC_BINARY HTAtom_for("binary")
260: #define WWW_ENC_BASE64 HTAtom_for("base64")
261: #define WWW_ENC_COMPRESS HTAtom_for("compress")
262: #define WWW_ENC_GZIP HTAtom_for("gzip")
263: </PRE>
264:
265: <H4>Register an Encoding</H4>
266:
267: <PRE>
268: extern void HTAcceptEncoding PARAMS((HTList * list,
269: CONST char * enc,
270: double quality));
271: </PRE>
2.31 frystyk 272:
2.42 frystyk 273: <H3><A NAME="charset">Registration of Accepted Charsets</A></H3>
2.31 frystyk 274:
2.42 frystyk 275: We use the same <CODE>HTAcceptNode</CODE> as above.
2.31 frystyk 276:
277: <PRE>
2.42 frystyk 278: extern HTList * HTCharsets; /* Global list of charsets */
279: </PRE>
280:
281: <H4>Register a Charset</H4>
282:
283: <PRE>
284: extern void HTAcceptCharset PARAMS((HTList * list,
285: CONST char * charset,
286: double quality));
287: </PRE>
288:
289: <A NAME="Language"><H3>Registration of Accepted Content Languages</H3></A>
290:
291: We use the same <CODE>HTAcceptNode</CODE> as above.
292:
293: <PRE>
294: extern HTList * HTLanguages; /* Global list of languages */
2.31 frystyk 295: </PRE>
296:
2.42 frystyk 297: <H4>Register a Language</H4>
2.31 frystyk 298:
299: <PRE>
2.42 frystyk 300: extern void HTAcceptLanguage PARAMS((HTList * list,
301: CONST char * lang,
302: double quality));
2.31 frystyk 303: </PRE>
304:
2.42 frystyk 305: <H3>Garbage Collection of User Preferences</H3>
306:
307: This is used for cleaning up the lists of user preferences, both the
308: local and the global lists:
2.1 timbl 309:
2.42 frystyk 310: <H3>Remove Local Preferences</H3>
311:
2.47 frystyk 312: The function is called from <A HREF="HTReq.html#z100">HTRequest_delete</A>.
2.1 timbl 313:
2.31 frystyk 314: <PRE>
315: extern void HTFormatDelete PARAMS((HTRequest * request));
316: </PRE>
317:
2.42 frystyk 318: <H3>Remove Global Preferences</H3>
319:
2.47 frystyk 320: The function is called from <A HREF="HTReq.html#Library">HTLibTerminate</A>.
2.34 frystyk 321:
322: <PRE>
323: extern void HTDisposeConversions NOPARAMS;
324: </PRE>
2.31 frystyk 325:
326: <A NAME="Rank"><H2>Ranking of Accepted Formats</H2></A>
327:
2.36 frystyk 328: This function is used when the best match among several possible
329: documents is to be found as a function of the accept headers sent in
330: the client request.
2.31 frystyk 331:
332: <PRE>
2.42 frystyk 333: typedef struct _HTContentDescription {
334: char * filename;
335: HTAtom * content_type;
336: HTAtom * content_language;
337: HTAtom * content_encoding;
338: int content_length;
339: double quality;
340: } HTContentDescription;
341:
2.32 frystyk 342: extern BOOL HTRank PARAMS((HTList * possibilities,
2.31 frystyk 343: HTList * accepted_content_types,
344: HTList * accepted_content_languages,
345: HTList * accepted_content_encodings));
2.1 timbl 346: </PRE>
2.31 frystyk 347:
2.42 frystyk 348: <H2><A NAME="z3">The Stream Stack</A></H2>
2.31 frystyk 349:
350: This is the routine which actually sets up the conversion. It
351: currently checks only for direct conversions, but multi-stage
352: conversions are forseen. It takes a stream into which the output
353: should be sent in the final format, builds the conversion stack, and
354: returns a stream into which the data in the input format should be
2.42 frystyk 355: fed. If <CODE>guess</CODE> is true and input format is
2.31 frystyk 356: <CODE>www/unknown</CODE>, try to guess the format by looking at the
357: first few bytes of the stream. <P>
2.1 timbl 358:
2.31 frystyk 359: <PRE>
2.32 frystyk 360: extern HTStream * HTStreamStack PARAMS((HTFormat rep_in,
2.31 frystyk 361: HTFormat rep_out,
362: HTStream * output_stream,
363: HTRequest * request,
364: BOOL guess));
2.1 timbl 365: </PRE>
2.31 frystyk 366:
2.42 frystyk 367: <H2>Cost of a Stream Stack</H2>
2.31 frystyk 368:
369: Must return the cost of the same stack which HTStreamStack would set
2.1 timbl 370: up.
371:
2.31 frystyk 372: <PRE>
2.37 frystyk 373: extern double HTStackValue PARAMS((HTList * conversions,
2.31 frystyk 374: HTFormat format_in,
375: HTFormat format_out,
2.37 frystyk 376: double initial_value,
2.31 frystyk 377: long int length));
378:
2.42 frystyk 379: #endif /* HTFORMAT */
2.38 frystyk 380: </PRE>
381:
2.42 frystyk 382: End of declaration module
2.31 frystyk 383:
384: </BODY>
2.10 timbl 385: </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