Annotation of libwww/Library/src/HTFormat.html, revision 2.59
2.10 timbl 1: <HTML>
2: <HEAD>
2.45 frystyk 3: <TITLE>Format Negotiation Manager</TITLE>
2.59 ! frystyk 4: <!-- Changed by: Henrik Frystyk Nielsen, 30-Jan-1996 -->
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.52 frystyk 59: typedef HTStream * HTConverter (HTRequest * request,
60: void * param,
61: HTFormat input_format,
62: HTFormat output_format,
63: HTStream * output_stream);
2.42 frystyk 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
2.52 frystyk 107: course not MIME standard. They are internal representations used in
108: the Library but they can't be exported to other apps!
2.28 frystyk 109:
110: <PRE>
2.57 frystyk 111: #define WWW_RAW HTAtom_for("www/void") /* Raw output from Protocol */
2.28 frystyk 112: </PRE>
113:
2.57 frystyk 114: <CODE>WWW_RAW</CODE> is an output format which leaves the input
2.54 frystyk 115: untouched <EM>exactly</EM> as it is received by the protocol
116: module. For example, in the case of FTP, this format returns raw ASCII
117: objects for directory listings; for HTTP, everything including the
118: header is returned, for Gopher, a raw ASCII object is returned for a
119: menu etc.
2.10 timbl 120:
2.28 frystyk 121: <PRE>
2.57 frystyk 122: #define WWW_SOURCE HTAtom_for("*/*") /* Almost what it was originally */
123: </PRE>
124:
125: <CODE>WWW_SOURCE</CODE> is an output format which leaves the input
126: untouched <EM>exactly</EM> as it is received by the protocol module
127: <B>IF</B> not a suitable converter has been registered with a quality
128: factor higher than 1 (for example 2). In this case the <EM>SUPER
129: CONVERTER</EM> is preferred for the raw output. This can be used as a
130: filter effect that allows conversion from, for example raw
131: FTPdirectory listings into HTML but passes a MIME body untouched.
132:
133: <PRE>
2.28 frystyk 134: #define WWW_PRESENT HTAtom_for("www/present") /* The user's perception */
135: </PRE>
136:
2.52 frystyk 137: <CODE>WWW_PRESENT</CODE> represents the user's perception of the
138: document. If you convert to <CODE>WWW_PRESENT</CODE>, you present the
139: material to the user.
2.58 frystyk 140:
141: <PRE>
142: #define WWW_DEBUG HTAtom_for("www/debug")
143: </PRE>
144:
145: <CODE>WWW_DEBUG</CODE> represents the user's perception of debug
146: information, for example sent as a HTML document in a HTTP redirection
147: message.
2.28 frystyk 148:
149: <PRE>
2.52 frystyk 150: #define WWW_UNKNOWN HTAtom_for("www/unknown")
2.28 frystyk 151: </PRE>
152:
2.52 frystyk 153: <CODE>WWW_UNKNOWN</CODE> is a really unknown type. It differs from the
154: real MIME type <EM>"application/octet-stream"</EM> in that we haven't
155: even tried to figure out the content type at this point.<P>
2.28 frystyk 156:
2.31 frystyk 157: These are regular MIME types defined. Others can be added!
2.28 frystyk 158:
159: <PRE>
2.52 frystyk 160: #define WWW_HTML HTAtom_for("text/html")
2.28 frystyk 161: #define WWW_PLAINTEXT HTAtom_for("text/plain")
2.52 frystyk 162:
163: #define WWW_MIME HTAtom_for("message/rfc822")
164:
2.10 timbl 165: #define WWW_AUDIO HTAtom_for("audio/basic")
2.52 frystyk 166:
2.26 frystyk 167: #define WWW_VIDEO HTAtom_for("video/mpeg")
2.52 frystyk 168:
2.38 frystyk 169: #define WWW_GIF HTAtom_for("image/gif")
2.52 frystyk 170: #define WWW_PNG HTAtom_for("image/png")
171:
172: #define WWW_BINARY HTAtom_for("application/octet-stream")
173: #define WWW_POSTSCRIPT HTAtom_for("application/postscript")
174: #define WWW_RICHTEXT HTAtom_for("application/rtf")
2.48 frystyk 175: </PRE>
176:
2.52 frystyk 177: We also have some MIME types that come from the various protocols when
178: we convert from ASCII to HTML.
2.48 frystyk 179:
180: <PRE>
181: #define WWW_GOPHER_MENU HTAtom_for("text/x-gopher")
2.53 frystyk 182: #define WWW_CSO_SEARCH HTAtom_for("text/x-cso")
2.48 frystyk 183:
184: #define WWW_FTP_LNST HTAtom_for("text/x-ftp-lnst")
185: #define WWW_FTP_LIST HTAtom_for("text/x-ftp-list")
186:
187: #define WWW_NNTP_LIST HTAtom_for("text/x-nntp-list")
188: #define WWW_NNTP_OVER HTAtom_for("text/x-nntp-over")
189: #define WWW_NNTP_HEAD HTAtom_for("text/x-nntp-head")
2.59 ! frystyk 190:
! 191: #define WWW_HTTP HTAtom_for("text/x-http")
2.55 frystyk 192: </PRE>
193:
194: Finally we have defined a special format for our RULE files as they
195: can be handled by a special converter.
196:
197: <PRE>
2.57 frystyk 198: #define WWW_RULES HTAtom_for("application/x-www-rules")
2.28 frystyk 199: </PRE>
200:
2.50 frystyk 201: <H4>Add a Presenter</H4>
202:
203: This function creates a presenter object and adds to the list of
204: conversions.
2.31 frystyk 205:
2.1 timbl 206: <DL>
2.31 frystyk 207: <DT>conversions
208: <DD>The list of <CODE>conveters</CODE> and <CODE>presenters</CODE>
2.50 frystyk 209: <DT>rep_in
2.42 frystyk 210: <DD>the MIME-style format name
2.50 frystyk 211: <DT>rep_out
212: <DD>is the resulting content-type after the conversion
213: <DT>converter
214: <DD>is the routine to call which actually does the conversion
2.1 timbl 215: <DT>quality
2.31 frystyk 216: <DD>A degradation faction [0..1]
2.1 timbl 217: <DT>maxbytes
2.31 frystyk 218: <DD>A limit on the length acceptable as input (0 infinite)
2.1 timbl 219: <DT>maxsecs
2.31 frystyk 220: <DD>A limit on the time user will wait (0 for infinity)
2.1 timbl 221: </DL>
222:
2.31 frystyk 223: <PRE>
2.49 frystyk 224: extern void HTPresentation_add (HTList * conversions,
225: CONST char * representation,
226: CONST char * command,
227: CONST char * test_command,
228: double quality,
229: double secs,
230: double secs_per_byte);
2.31 frystyk 231: </PRE>
2.1 timbl 232:
2.50 frystyk 233: <H4>Delete a list of Presenters</H4>
234:
235: <PRE>
236: extern void HTPresentation_deleteAll (HTList * list);
237: </PRE>
238:
239: <H4>Add a Converter</H4>
240:
241: This function creates a presenter object and adds to the list of
242: conversions.
2.1 timbl 243:
244: <DL>
2.31 frystyk 245: <DT>conversions
246: <DD>The list of <CODE>conveters</CODE> and <CODE>presenters</CODE>
2.1 timbl 247: <DT>rep_in
2.42 frystyk 248: <DD>the MIME-style format name
2.1 timbl 249: <DT>rep_out
2.31 frystyk 250: <DD>is the resulting content-type after the conversion
2.1 timbl 251: <DT>converter
2.31 frystyk 252: <DD>is the routine to call which actually does the conversion
253: <DT>quality
254: <DD>A degradation faction [0..1]
255: <DT>maxbytes
256: <DD>A limit on the length acceptable as input (0 infinite)
257: <DT>maxsecs
258: <DD>A limit on the time user will wait (0 for infinity)
2.1 timbl 259: </DL>
260:
261: <PRE>
2.49 frystyk 262: extern void HTConversion_add (HTList * conversions,
263: CONST char * rep_in,
264: CONST char * rep_out,
265: HTConverter * converter,
266: double quality,
267: double secs,
268: double secs_per_byte);
2.42 frystyk 269: </PRE>
270:
2.50 frystyk 271: <H4>Delete a list of Converters</H4>
272:
273: <PRE>
274: extern void HTConversion_deleteAll (HTList * list);
275: </PRE>
276:
2.42 frystyk 277: <A NAME="Encoding"><H3>Registration of Accepted Content Encodings</H3></A>
278:
279: Encodings are the HTTP extension of transfer encodings. Encodings
2.50 frystyk 280: include compress, gzip etc.
2.42 frystyk 281:
282: <PRE>
283: typedef struct _HTAcceptNode {
284: HTAtom * atom;
285: double quality;
286: } HTAcceptNode;
287: </PRE>
288:
289: <H4>Predefined Encoding Types</H4>
290:
291: <PRE>
292: #define WWW_ENC_7BIT HTAtom_for("7bit")
293: #define WWW_ENC_8BIT HTAtom_for("8bit")
294: #define WWW_ENC_BINARY HTAtom_for("binary")
295: #define WWW_ENC_BASE64 HTAtom_for("base64")
296: #define WWW_ENC_COMPRESS HTAtom_for("compress")
297: #define WWW_ENC_GZIP HTAtom_for("gzip")
298: </PRE>
299:
300: <H4>Register an Encoding</H4>
301:
302: <PRE>
2.50 frystyk 303: extern void HTEncoding_add (HTList * list,
304: CONST char * enc,
305: double quality);
2.42 frystyk 306: </PRE>
2.31 frystyk 307:
2.50 frystyk 308: <H4>Delete a list of Encoders</H4>
2.31 frystyk 309:
2.50 frystyk 310: <PRE>
2.51 frystyk 311: extern void HTEncoding_deleteAll (HTList * list);
2.50 frystyk 312: </PRE>
313:
314: <H3><A NAME="charset">Accepted Charsets</A></H3>
2.31 frystyk 315:
2.42 frystyk 316: <H4>Register a Charset</H4>
317:
318: <PRE>
2.50 frystyk 319: extern void HTCharset_add (HTList * list,
320: CONST char * charset,
321: double quality);
2.42 frystyk 322: </PRE>
323:
2.50 frystyk 324: <H4>Delete a list of Charsets</H4>
2.42 frystyk 325:
2.50 frystyk 326: <PRE>
327: extern void HTCharset_deleteAll (HTList * list);
328: </PRE>
329:
330: <A NAME="Language"><H3>Accepted Content Languages</H3></A>
2.31 frystyk 331:
2.42 frystyk 332: <H4>Register a Language</H4>
2.31 frystyk 333:
334: <PRE>
2.50 frystyk 335: extern void HTLanguage_add (HTList * list,
336: CONST char * lang,
337: double quality);
338: </PRE>
339:
340: <H4>Delete a list of Languages</H4>
341:
342: <PRE>
2.51 frystyk 343: extern void HTLanguage_deleteAll (HTList * list);
2.50 frystyk 344: </PRE>
345:
346: <A NAME="global"><H2>Global Registrations</H2></A>
347:
348: There are two places where these preferences can be registered: in a
349: <EM>global</EM> list valid for <B>all</B> requests and a
350: <EM>local</EM> list valid for a particular request only. These are
351: valid for <EM>all</EM> requests. See the <A HREF="HTReq.html">Request
352: Manager</A> fro local sets.
353:
2.51 frystyk 354: <H3>Converters and Presenters</H3>
2.50 frystyk 355:
356: The <EM>global</EM> list of specific conversions which the format
357: manager can do in order to fulfill the request. There is also a <A
358: HREF="HTReq.html"><EM>local</EM></A> list of conversions which
359: contains a generic set of possible conversions.
360:
361: <PRE>
362: extern void HTFormat_setConversion (HTList *list);
363: extern HTList * HTFormat_conversion (void);
2.31 frystyk 364: </PRE>
365:
2.50 frystyk 366: <H3>Content Encodings</H3>
2.42 frystyk 367:
2.50 frystyk 368: <PRE>
369: extern void HTFormat_setEncoding (HTList *list);
370: extern HTList * HTFormat_encoding (void);
371: </PRE>
2.1 timbl 372:
2.51 frystyk 373: <H3>Content Languages</H3>
2.50 frystyk 374:
375: <PRE>
376: extern void HTFormat_setLanguage (HTList *list);
377: extern HTList * HTFormat_language (void);
378: </PRE>
2.42 frystyk 379:
2.51 frystyk 380: <H3>Content Charsets</H3>
2.1 timbl 381:
2.31 frystyk 382: <PRE>
2.50 frystyk 383: extern void HTFormat_setCharset (HTList *list);
384: extern HTList * HTFormat_charset (void);
2.31 frystyk 385: </PRE>
386:
2.50 frystyk 387: <H3>Delete All Global Lists</H3>
2.42 frystyk 388:
2.50 frystyk 389: This is a convenience function that might make life easier.
2.34 frystyk 390:
391: <PRE>
2.50 frystyk 392: extern void HTFormat_deleteAll (void);
2.34 frystyk 393: </PRE>
2.31 frystyk 394:
395: <A NAME="Rank"><H2>Ranking of Accepted Formats</H2></A>
396:
2.36 frystyk 397: This function is used when the best match among several possible
398: documents is to be found as a function of the accept headers sent in
399: the client request.
2.31 frystyk 400:
401: <PRE>
2.42 frystyk 402: typedef struct _HTContentDescription {
403: char * filename;
404: HTAtom * content_type;
405: HTAtom * content_language;
406: HTAtom * content_encoding;
407: int content_length;
408: double quality;
409: } HTContentDescription;
410:
2.52 frystyk 411: extern BOOL HTRank (HTList * possibilities,
412: HTList * accepted_content_types,
413: HTList * accepted_content_languages,
414: HTList * accepted_content_encodings);
2.1 timbl 415: </PRE>
2.31 frystyk 416:
2.42 frystyk 417: <H2><A NAME="z3">The Stream Stack</A></H2>
2.31 frystyk 418:
419: This is the routine which actually sets up the conversion. It
420: currently checks only for direct conversions, but multi-stage
421: conversions are forseen. It takes a stream into which the output
422: should be sent in the final format, builds the conversion stack, and
423: returns a stream into which the data in the input format should be
2.42 frystyk 424: fed. If <CODE>guess</CODE> is true and input format is
2.31 frystyk 425: <CODE>www/unknown</CODE>, try to guess the format by looking at the
426: first few bytes of the stream. <P>
2.1 timbl 427:
2.31 frystyk 428: <PRE>
2.52 frystyk 429: extern HTStream * HTStreamStack (HTFormat rep_in,
430: HTFormat rep_out,
431: HTStream * output_stream,
432: HTRequest * request,
433: BOOL guess);
2.1 timbl 434: </PRE>
2.31 frystyk 435:
2.42 frystyk 436: <H2>Cost of a Stream Stack</H2>
2.31 frystyk 437:
438: Must return the cost of the same stack which HTStreamStack would set
2.1 timbl 439: up.
440:
2.31 frystyk 441: <PRE>
2.52 frystyk 442: extern double HTStackValue (HTList * conversions,
443: HTFormat format_in,
444: HTFormat format_out,
445: double initial_value,
446: long int length);
2.31 frystyk 447:
2.42 frystyk 448: #endif /* HTFORMAT */
2.38 frystyk 449: </PRE>
450:
2.42 frystyk 451: End of declaration module
2.31 frystyk 452:
453: </BODY>
2.10 timbl 454: </HTML>
Webmaster