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