Annotation of libwww/Library/src/HTFormat.html, revision 2.6
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
2.6 ! secret 222: to send data down a stream, typically
2.1 timbl 223: one which has been generated by HTStreamStack.
224: <PRE>extern void HTCopy PARAMS((
225: int file_number,
226: HTStream* sink));
227:
228:
2.6 ! secret 229: </PRE>
! 230: <H2><A
! 231: NAME=c6>HTFileCopy: Copy a file to a stream</A></H2>This is used by the protocol engines
! 232: to send data down a stream, typically
! 233: one which has been generated by HTStreamStack. It is currently called by <A
! 234: HREF="#c7">HTParseFile</A>
! 235: <PRE>extern void HTFileCopy PARAMS((
! 236: FILE* fp,
! 237: HTStream* sink));
! 238:
! 239:
! 240: </PRE><H2><A
! 241: NAME=c2>HTCopyNoCR: Copy a socket to a stream, stripping CR characters.</A></H2>
2.1 timbl 242: It is slower than <A
243: NAME=z2 HREF="#z1">HTCopy</A> .
244: <PRE>
245: extern void HTCopyNoCR PARAMS((
246: int file_number,
247: HTStream* sink));
248:
249:
250: </PRE>
251: <H2>Clear input buffer and set file number</H2>This routine and the one below provide
252: simple character input from sockets.
253: (They are left over from the older
254: architecure and may not be used very
255: much.) The existence of a common
256: routine and buffer saves memory space
257: in small implementations.
258: <PRE>extern void HTInitInput PARAMS((int file_number));
259:
260: </PRE>
261: <H2>Get next character from buffer</H2>
262: <PRE>extern char HTGetChararcter NOPARAMS;
263:
264:
265: </PRE>
266: <H2>HTParseSocket: Parse a socket given
267: its format</H2>This routine is called by protocol
268: modules to load an object. uses<A
269: NAME=z4 HREF="#z3">
270: HTStreamStack</A> and the copy routines
271: above. Returns HT_LOADED if succesful,
272: <0 if not.
273: <PRE>extern int HTParseSocket PARAMS((
274: HTFormat format_in,
275: HTFormat format_out,
276: HTParentAnchor *anchor,
277: int file_number,
2.6 ! secret 278: HTStream* sink));
! 279:
! 280: </PRE>
! 281: <H2><A
! 282: NAME=c1>HTParseFile: Parse a File through a file pointer</A></H2>
! 283: This routine is called by protocols modules to load an object. uses
! 284: <A
! 285: NAME=z4 HREF="#z3">HTStreamStack</A> and <A
! 286: NAME=c7 HREF="#c6">HTFileCopy</A>. Returns HT_LOADED if succesful,
! 287: <0 if not.
! 288: <PRE>extern int HTParseFile PARAMS((
! 289: HTFormat format_in,
! 290: HTFormat format_out,
! 291: HTParentAnchor *anchor,
! 292: FILE *fp,
2.1 timbl 293: HTStream* sink));
294:
295: </PRE>
296: <H2>Epilogue</H2>
297: <PRE>extern BOOL HTOutputSource; /* Flag: shortcut parser */
298: #endif
299:
2.2 timbl 300: </PRE>end</BODY>
Webmaster