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