Annotation of libwww/Library/src/HTFormat.html, revision 2.2
2.1 timbl 1: <HEADER>
2: <TITLE>HTFormat: The format manager in the WWW Library</TITLE>
2.2 ! timbl 3: <NEXTID N="9">
2.1 timbl 4: </HEADER>
5: <BODY>
6: <H1>Manage different document formats</H1>Here we describe the functions of
7: the HTFormat module which handles
8: conversion between different data
9: representations. (In MIME parlance,
10: a representation is known as a content-type.
2.2 ! timbl 11: In WWW the term "format" is often
2.1 timbl 12: used as it is shorter).<P>
13: This module is implemented by <A
2.2 ! timbl 14: NAME=z0 HREF="HTFormat.c">HTFormat.c</A>.
! 15: This hypertext document is used to
! 16: generate the <A
! 17: NAME=z8 HREF="HTFormat.h">HTFormat.h</A> inlude file.
2.1 timbl 18: <H2>Preamble</H2>
19: <PRE>#ifndef HTFORMAT_H
20: #define HTFORMAT_H
21:
22: #include "HTUtils.h"
23: #include <A
24: NAME=z7 HREF="HTStream.html">"HTStream.h"</A>
25: #include "HTAtom.h"
2.2 ! timbl 26: #include "HTList.h"
2.1 timbl 27:
28: #ifdef SHORT_NAMES
29: #define HTOutputSource HTOuSour
30: #define HTOutputBinary HTOuBina
31: #endif
32:
33: </PRE>
34: <H2>The HTFormat type</H2>We use the HTAtom object for holding
35: representations. This allows faster
36: manipulation (comparison and copying)
37: that if we stayed with strings.
38: <PRE>typedef HTAtom * HTFormat;
39:
40: </PRE>These macros (which used to be constants)
41: define some basic internally referenced
2.2 ! timbl 42: representations. The www/xxx ones
2.1 timbl 43: are of course not MIME standard.<P>
44: www/source is an output format which
45: leaves the input untouched. It is
46: useful for diagnostics, and for users
47: who want to see the original, whatever
48: it is.
49: <PRE> /* Internal ones */
50: #define WWW_SOURCE HTAtom_for("www/source") /* Whatever it was originally*/
51:
52: </PRE>www/present represents the user's
53: perception of the document. If you
54: convert to www/present, you present
55: the material to the user.
56: <PRE>#define WWW_PRESENT HTAtom_for("www/present") /* The user's perception */
57:
58: </PRE>The message/rfc822 format means a
59: MIME message or a plain text message
60: with no MIME header. This is what
61: is returned by an HTTP server.
62: <PRE>#define WWW_MIME HTAtom_for("www/mime") /* A MIME message */
63: </PRE>www/print is like www/present except
64: it represents a printed copy.
65: <PRE>#define WWW_PRINT HTAtom_for("www/print") /* A printed copy */
66:
67: #define WWW_PLAINTEXT HTAtom_for("text/plain")
68: #define WWW_POSTSCRIPT HTAtom_for("application/postscript")
69: #define WWW_RICHTEXT HTAtom_for("application/rtf")
70: #define WWW_HTML HTAtom_for("text/html")
71: #define WWW_BINARY HTAtom_for("application/binary")
72: </PRE>We must include the following file
73: after defining HTFormat, to which
74: it makes reference.
75: <PRE>#include "HTAnchor.h"
76:
77: </PRE>
78: <H2>The HTPresentation and HTConverter
79: types</H2>This HTPresentation structure represents
80: a possible conversion algorithm from
81: one format to annother. It includes
82: a pointer to a conversion routine.
83: The conversion routine returns a
84: stream to which data should be fed.
85: See also <A
86: NAME=z5 HREF="#z3">HTStreamStack</A> which scans
87: the list of registered converters
88: and calls one. See the <A
89: NAME=z6 HREF="HTInit.html">initialisation
90: module</A> for a list of conversion routines.
91: <PRE>typedef struct _HTPresentation HTPresentation;
92:
2.2 ! timbl 93: typedef HTStream * HTConverter PARAMS((
2.1 timbl 94: HTPresentation * pres,
95: HTParentAnchor * anchor,
96: HTStream * sink));
97:
98: struct _HTPresentation {
99: HTAtom* rep; /* representation name atmoized */
100: HTAtom* rep_out; /* resulting representation */
2.2 ! timbl 101: HTConverter *converter; /* The routine to gen the stream stack */
2.1 timbl 102: char * command; /* MIME-format string */
103: float quality; /* Between 0 (bad) and 1 (good) */
104: float secs;
105: float secs_per_byte;
106: };
107:
108: </PRE>The list of presentations is kept
109: by this module. It is also scanned
110: by modules which want to know the
111: set of formats supported. for example.
112: <PRE>extern HTList * HTPresentations;
113:
114: </PRE>
115: <H2>HTSetPresentation: Register a system
116: command to present a format</H2>
2.2 ! timbl 117: <H2>On entry,</H2>
2.1 timbl 118: <DL>
119: <DT>rep
120: <DD> is the MIME - style format name
121: <DT>command
122: <DD> is the MAILCAP - style command
123: template
124: <DT>quality
125: <DD> A degradation faction 0..1
126: <DT>maxbytes
127: <DD> A limit on the length acceptable
128: as input (0 infinite)
129: <DT>maxsecs
130: <DD> A limit on the time user
131: will wait (0 for infinity)
132: </DL>
133:
134: <PRE>extern void HTSetPresentation PARAMS((
135: CONST char * representation,
136: CONST char * command,
137: float quality,
138: float secs,
139: float secs_per_byte
140: ));
141:
142:
143: </PRE>
144: <H2>HTSetConversion: Register a converstion
145: routine</H2>
2.2 ! timbl 146: <H2>On entry,</H2>
2.1 timbl 147: <DL>
148: <DT>rep_in
149: <DD> is the content-type input
150: <DT>rep_out
151: <DD> is the resulting content-type
152: <DT>converter
153: <DD> is the routine to make
154: the stream to do it
155: </DL>
156:
157: <PRE>
158: extern void HTSetConversion PARAMS((
159: CONST char * rep_in,
160: CONST char * rep_out,
2.2 ! timbl 161: HTConverter * converter,
2.1 timbl 162: float quality,
163: float secs,
164: float secs_per_byte
165: ));
166:
167:
168: </PRE>
169: <H2><A
170: NAME=z3>HTStreamStack: Create a stack of
171: streams</A></H2>This is the routine which actually
172: sets up the conversion. It currently
173: checks only for direct conversions,
174: but indirect conversions are forseen.
2.2 ! timbl 175: It takes a stream into which the
2.1 timbl 176: output should be sent in the final
177: format, builds the conversion stack,
178: and returns a stream into which the
179: data in the input format should be
180: fed. The anchor is passed because
181: hypertxet objects load information
182: into the anchor object which represents
183: them.
184: <PRE>extern HTStream * HTStreamStack PARAMS((
185: HTFormat format_in,
186: HTFormat format_out,
187: HTStream* stream_out,
188: HTParentAnchor* anchor));
189:
190: </PRE>
191: <H2>HTStackValue: Find the cost of a
192: filter stack</H2>Must return the cost of the same
193: stack which HTStreamStack would set
194: up.
2.2 ! timbl 195: <H2>On entry,</H2>
2.1 timbl 196: <DL>
197: <DT>format_in
198: <DD> The fomat of the data to
199: be converted
200: <DT>format_out
201: <DD> The format required
202: <DT>initial_value
203: <DD> The intrinsic "value"
204: of the data before conversion on
205: a scale from 0 to 1
206: <DT>length
207: <DD> The number of bytes expected
208: in the input format
209: </DL>
210:
211: <PRE>extern float HTStackValue PARAMS((
212: HTFormat format_in,
213: HTFormat rep_out,
214: float initial_value,
215: long int length));
216:
217: #define NO_VALUE_FOUND -1e20 /* returned if none found */
218:
219: </PRE>
220: <H2><A
221: NAME=z1>HTCopy: Copy a socket to a stream</A></H2>This is used by the protocol engines
222: to send data down a stream, typiclly
223: one which has been generated by HTStreamStack.
224: <PRE>extern void HTCopy PARAMS((
225: int file_number,
226: HTStream* sink));
227:
228:
229: </PRE>HTCopyNoCRThis one strips CR characters.
230: It is slower than <A
231: NAME=z2 HREF="#z1">HTCopy</A> .
232: <PRE>
233: extern void HTCopyNoCR PARAMS((
234: int file_number,
235: HTStream* sink));
236:
237:
238: </PRE>
239: <H2>Clear input buffer and set file number</H2>This routine and the one below provide
240: simple character input from sockets.
241: (They are left over from the older
242: architecure and may not be used very
243: much.) The existence of a common
244: routine and buffer saves memory space
245: in small implementations.
246: <PRE>extern void HTInitInput PARAMS((int file_number));
247:
248: </PRE>
249: <H2>Get next character from buffer</H2>
250: <PRE>extern char HTGetChararcter NOPARAMS;
251:
252:
253: </PRE>
254: <H2>HTParseSocket: Parse a socket given
255: its format</H2>This routine is called by protocol
256: modules to load an object. uses<A
257: NAME=z4 HREF="#z3">
258: HTStreamStack</A> and the copy routines
259: above. Returns HT_LOADED if succesful,
260: <0 if not.
261: <PRE>extern int HTParseSocket PARAMS((
262: HTFormat format_in,
263: HTFormat format_out,
264: HTParentAnchor *anchor,
265: int file_number,
266: HTStream* sink));
267:
268: </PRE>
269: <H2>Epilogue</H2>
270: <PRE>extern BOOL HTOutputSource; /* Flag: shortcut parser */
271: #endif
272:
2.2 ! timbl 273: </PRE>end</BODY>
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