Annotation of libwww/Library/src/HTFormat.html, revision 2.21
2.10 timbl 1: <HTML>
2: <HEAD>
2.1 timbl 3: <TITLE>HTFormat: 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>
7: <H1>Manage different document formats</H1>Here we describe the functions of
8: the HTFormat module which handles
9: conversion between different data
10: representations. (In MIME parlance,
11: a representation is known as a content-type.
2.2 timbl 12: In WWW the term "format" is often
2.1 timbl 13: used as it is shorter).<P>
14: This module is implemented by <A
2.10 timbl 15: NAME="z0" HREF="HTFormat.c">HTFormat.c</A>
2.7 timbl 16: . This hypertext document is used
17: to generate the <A
2.11 timbl 18: NAME="z8" HREF="HTFormat.h">HTFormat.h</A> include
2.9 timbl 19: file. Part of the <A
2.10 timbl 20: NAME="z10" HREF="Overview.html">WWW library</A> .
2.1 timbl 21: <H2>Preamble</H2>
22: <PRE>#ifndef HTFORMAT_H
23: #define HTFORMAT_H
24:
25: #include "HTUtils.h"
26: #include <A
2.10 timbl 27: NAME="z7" HREF="HTStream.html">"HTStream.h"</A>
2.1 timbl 28: #include "HTAtom.h"
2.2 timbl 29: #include "HTList.h"
2.1 timbl 30:
31: #ifdef SHORT_NAMES
32: #define HTOutputSource HTOuSour
33: #define HTOutputBinary HTOuBina
34: #endif
35:
2.18 luotonen 36:
37: typedef struct _HTContentDescription {
38: char * filename;
39: HTAtom * content_type;
40: HTAtom * content_language;
41: HTAtom * content_encoding;
42: int content_length;
43: float quality;
44: } HTContentDescription;
45:
46: PUBLIC void HTAcceptEncoding PARAMS((HTList * list,
47: char * enc,
48: float quality));
49:
50: PUBLIC void HTAcceptLanguage PARAMS((HTList * list,
51: char * lang,
52: float quality));
53:
54: PUBLIC BOOL HTRank PARAMS((HTList * possibilities,
55: HTList * accepted_content_types,
56: HTList * accepted_content_languages,
57: HTList * accepted_content_encodings));
58:
59:
2.1 timbl 60: </PRE>
2.17 luotonen 61: <H2>HT<A
62: NAME="z15"> Input Socket: Buffering for network
63: in</A></H2>This routines provide simple character
64: input from sockets. These are used
65: for parsing input in arbitrary IP
66: protocols (Gopher, NNTP, FTP).
67: <PRE>#define INPUT_BUFFER_SIZE 4096 /* Tradeoff spped vs memory*/
68: typedef struct _socket_buffer {
69: char input_buffer[INPUT_BUFFER_SIZE];
70: char * input_pointer;
71: char * input_limit;
72: int input_file_number;
73: } HTInputSocket;
74:
75: </PRE>
76: <H3>Create input buffer and set file
77: number</H3>
78: <PRE>extern HTInputSocket* HTInputSocket_new PARAMS((int file_number));
79:
80: </PRE>
81: <H3>Get next character from buffer</H3>
82: <PRE>extern char HTInputSocket_getCharacter PARAMS((HTInputSocket* isoc));
83:
84: </PRE>
85: <H3>Read block from input socket</H3>
86: Read <CODE>*len</CODE> characters and return a buffer (don't free)
87: containing <CODE>*len</CODE> characters (<CODE>*len</CODE> may have
88: changed). Buffer is not NULL-terminated.
89: <PRE>extern char * HTInputSocket_getBlock PARAMS((HTInputSocket * isoc,
90: int * len));
91:
92: </PRE>
93:
94: <H3>Free input socket buffer</H3>
95: <PRE>extern void HTInputSocket_free PARAMS((HTInputSocket * isoc));
96:
97: </PRE>
98: <PRE>
99: PUBLIC char * HTInputSocket_getLine PARAMS((HTInputSocket * isoc));
100: PUBLIC char * HTInputSocket_getUnfoldedLine PARAMS((HTInputSocket * isoc));
101: PUBLIC char * HTInputSocket_getStatusLine PARAMS((HTInputSocket * isoc));
102: PUBLIC BOOL HTInputSocket_seemsBinary PARAMS((HTInputSocket * isoc));
103:
104: </PRE>
2.1 timbl 105: <H2>The HTFormat type</H2>We use the HTAtom object for holding
106: representations. This allows faster
107: manipulation (comparison and copying)
2.14 timbl 108: that if we stayed with strings.<P>
109: The following have to be defined
110: in advance of the other include files
111: because of circular references.
2.1 timbl 112: <PRE>typedef HTAtom * HTFormat;
2.13 timbl 113:
2.14 timbl 114: #include <A
115: NAME="z14" HREF="HTAccess.html">"HTAccess.h"</A> /* Required for HTRequest definition */
116:
2.1 timbl 117: </PRE>These macros (which used to be constants)
118: define some basic internally referenced
2.13 timbl 119: representations.
120: <H3>Internal ones</H3>The www/xxx ones are of course not
121: MIME standard.<P>
2.20 frystyk 122: star/star is an output format which
2.1 timbl 123: leaves the input untouched. It is
124: useful for diagnostics, and for users
125: who want to see the original, whatever
126: it is.
2.13 timbl 127: <H3></H3>
2.20 frystyk 128: <PRE>#define WWW_SOURCE HTAtom_for("*/*") /* Whatever it was originally*/
2.1 timbl 129:
130: </PRE>www/present represents the user's
131: perception of the document. If you
132: convert to www/present, you present
133: the material to the user.
134: <PRE>#define WWW_PRESENT HTAtom_for("www/present") /* The user's perception */
135:
136: </PRE>The message/rfc822 format means a
137: MIME message or a plain text message
138: with no MIME header. This is what
139: is returned by an HTTP server.
140: <PRE>#define WWW_MIME HTAtom_for("www/mime") /* A MIME message */
2.10 timbl 141:
2.1 timbl 142: </PRE>www/print is like www/present except
143: it represents a printed copy.
144: <PRE>#define WWW_PRINT HTAtom_for("www/print") /* A printed copy */
145:
2.10 timbl 146: </PRE>www/unknown is a really unknown type.
2.11 timbl 147: Some default action is appropriate.
2.10 timbl 148: <PRE>#define WWW_UNKNOWN HTAtom_for("www/unknown")
149:
2.13 timbl 150:
151:
152: </PRE>
153: <H3>MIME ones (a few)</H3>These are regular MIME types. HTML
2.11 timbl 154: is assumed to be added by the W3
155: code. application/octet-stream was
156: mistakenly application/binary in
157: earlier libwww versions (pre 2.11).
2.10 timbl 158: <PRE>#define WWW_PLAINTEXT HTAtom_for("text/plain")
2.1 timbl 159: #define WWW_POSTSCRIPT HTAtom_for("application/postscript")
160: #define WWW_RICHTEXT HTAtom_for("application/rtf")
2.10 timbl 161: #define WWW_AUDIO HTAtom_for("audio/basic")
2.1 timbl 162: #define WWW_HTML HTAtom_for("text/html")
2.11 timbl 163: #define WWW_BINARY HTAtom_for("application/octet-stream")
2.7 timbl 164:
2.1 timbl 165: </PRE>We must include the following file
166: after defining HTFormat, to which
2.10 timbl 167: it makes reference.
168: <H2>The HTEncoding type</H2>
169: <PRE>typedef HTAtom* HTEncoding;
170:
171: </PRE>The following are values for the
172: MIME types:
173: <PRE>#define WWW_ENC_7BIT HTAtom_for("7bit")
174: #define WWW_ENC_8BIT HTAtom_for("8bit")
175: #define WWW_ENC_BINARY HTAtom_for("binary")
176:
177: </PRE>We also add
178: <PRE>#define WWW_ENC_COMPRESS HTAtom_for("compress")
179:
180: #include "HTAnchor.h"
2.1 timbl 181:
182: </PRE>
183: <H2>The HTPresentation and HTConverter
184: types</H2>This HTPresentation structure represents
185: a possible conversion algorithm from
186: one format to annother. It includes
187: a pointer to a conversion routine.
188: The conversion routine returns a
189: stream to which data should be fed.
190: See also <A
2.12 timbl 191: NAME="z5" HREF="#z3">HTStreamStack</A> which scans
2.1 timbl 192: the list of registered converters
193: and calls one. See the <A
2.10 timbl 194: NAME="z6" HREF="HTInit.html">initialisation
2.1 timbl 195: module</A> for a list of conversion routines.
196: <PRE>typedef struct _HTPresentation HTPresentation;
197:
2.13 timbl 198: typedef HTStream * <A
199: NAME="z12">HTConverter</A> PARAMS((
200: HTRequest * request,
201: void * param,
202: HTFormat input_format,
203: HTFormat output_format,
204: HTStream * output_stream));
2.1 timbl 205:
206: struct _HTPresentation {
2.13 timbl 207: HTAtom* rep; /* representation name atomized */
2.1 timbl 208: HTAtom* rep_out; /* resulting representation */
2.2 timbl 209: HTConverter *converter; /* The routine to gen the stream stack */
2.1 timbl 210: char * command; /* MIME-format string */
211: float quality; /* Between 0 (bad) and 1 (good) */
212: float secs;
213: float secs_per_byte;
214: };
215:
2.15 timbl 216: </PRE>A global list of converters is kept
2.1 timbl 217: by this module. It is also scanned
218: by modules which want to know the
219: set of formats supported. for example.
2.15 timbl 220: Note there is also an additional
221: list associated with each <A
222: NAME="z16" HREF="HTAccess.html#z5">request</A>.
223: <PRE>extern HTList * <A
224: NAME="z17">HTConversions</A> ;
2.1 timbl 225:
2.12 timbl 226:
2.1 timbl 227: </PRE>
228: <H2>HTSetPresentation: Register a system
229: command to present a format</H2>
2.8 timbl 230: <H3>On entry,</H3>
2.1 timbl 231: <DL>
232: <DT>rep
233: <DD> is the MIME - style format name
234: <DT>command
235: <DD> is the MAILCAP - style command
236: template
237: <DT>quality
238: <DD> A degradation faction 0..1
239: <DT>maxbytes
240: <DD> A limit on the length acceptable
241: as input (0 infinite)
242: <DT>maxsecs
243: <DD> A limit on the time user
244: will wait (0 for infinity)
245: </DL>
246:
247: <PRE>extern void HTSetPresentation PARAMS((
2.13 timbl 248: HTList * conversions,
249: CONST char * representation,
250: CONST char * command,
251: float quality,
252: float secs,
253: float secs_per_byte
2.1 timbl 254: ));
255:
256:
257: </PRE>
258: <H2>HTSetConversion: Register a converstion
259: routine</H2>
2.8 timbl 260: <H3>On entry,</H3>
2.1 timbl 261: <DL>
262: <DT>rep_in
263: <DD> is the content-type input
264: <DT>rep_out
265: <DD> is the resulting content-type
266: <DT>converter
267: <DD> is the routine to make
268: the stream to do it
269: </DL>
270:
271: <PRE>
272: extern void HTSetConversion PARAMS((
2.13 timbl 273: HTList * conversions,
2.1 timbl 274: CONST char * rep_in,
275: CONST char * rep_out,
2.2 timbl 276: HTConverter * converter,
2.1 timbl 277: float quality,
278: float secs,
279: float secs_per_byte
280: ));
281:
282:
283: </PRE>
284: <H2><A
2.10 timbl 285: NAME="z3">HTStreamStack: Create a stack of
2.1 timbl 286: streams</A></H2>This is the routine which actually
287: sets up the conversion. It currently
288: checks only for direct conversions,
2.8 timbl 289: but multi-stage conversions are forseen.
2.2 timbl 290: It takes a stream into which the
2.1 timbl 291: output should be sent in the final
292: format, builds the conversion stack,
293: and returns a stream into which the
294: data in the input format should be
295: fed. The anchor is passed because
296: hypertxet objects load information
297: into the anchor object which represents
298: them.
299: <PRE>extern HTStream * HTStreamStack PARAMS((
300: HTFormat format_in,
2.13 timbl 301: HTRequest * request));
2.1 timbl 302:
303: </PRE>
304: <H2>HTStackValue: Find the cost of a
305: filter stack</H2>Must return the cost of the same
306: stack which HTStreamStack would set
307: up.
2.8 timbl 308: <H3>On entry,</H3>
2.1 timbl 309: <DL>
310: <DT>format_in
311: <DD> The fomat of the data to
312: be converted
313: <DT>format_out
314: <DD> The format required
315: <DT>initial_value
316: <DD> The intrinsic "value"
317: of the data before conversion on
318: a scale from 0 to 1
319: <DT>length
320: <DD> The number of bytes expected
321: in the input format
322: </DL>
323:
324: <PRE>extern float HTStackValue PARAMS((
2.13 timbl 325: HTList * conversions,
2.1 timbl 326: HTFormat format_in,
2.13 timbl 327: HTFormat format_out,
2.1 timbl 328: float initial_value,
329: long int length));
330:
331: #define NO_VALUE_FOUND -1e20 /* returned if none found */
332:
333: </PRE>
334: <H2><A
2.10 timbl 335: NAME="z1">HTCopy: Copy a socket to a stream</A></H2>This is used by the protocol engines
2.6 secret 336: to send data down a stream, typically
2.19 luotonen 337: one which has been generated by HTStreamStack. <B>Returns</B> the number
338: of bytes transferred.
339: <PRE>extern int HTCopy PARAMS((
2.1 timbl 340: int file_number,
341: HTStream* sink));
342:
343:
2.6 secret 344: </PRE>
345: <H2><A
2.10 timbl 346: NAME="c6">HTFileCopy: Copy a file to a stream</A></H2>This is used by the protocol engines
2.6 secret 347: to send data down a stream, typically
2.7 timbl 348: one which has been generated by HTStreamStack.
349: It is currently called by <A
2.12 timbl 350: NAME="z9" HREF="#c7">HTParseFile</A>
2.6 secret 351: <PRE>extern void HTFileCopy PARAMS((
352: FILE* fp,
353: HTStream* sink));
354:
355:
2.7 timbl 356: </PRE>
357: <H2><A
2.10 timbl 358: NAME="c2">HTCopyNoCR: Copy a socket to a stream,
2.7 timbl 359: stripping CR characters.</A></H2>It is slower than <A
2.12 timbl 360: NAME="z2" HREF="#z1">HTCopy</A> .
2.1 timbl 361: <PRE>
362: extern void HTCopyNoCR PARAMS((
363: int file_number,
364: HTStream* sink));
365:
2.16 luotonen 366:
367: </PRE>
2.1 timbl 368: <H2>HTParseSocket: Parse a socket given
369: its format</H2>This routine is called by protocol
370: modules to load an object. uses<A
2.12 timbl 371: NAME="z4" HREF="#z3">
2.1 timbl 372: HTStreamStack</A> and the copy routines
373: above. Returns HT_LOADED if succesful,
374: <0 if not.
375: <PRE>extern int HTParseSocket PARAMS((
376: HTFormat format_in,
377: int file_number,
2.13 timbl 378: HTRequest * request));
2.6 secret 379:
380: </PRE>
381: <H2><A
2.10 timbl 382: NAME="c1">HTParseFile: Parse a File through
2.7 timbl 383: a file pointer</A></H2>This routine is called by protocols
384: modules to load an object. uses<A
2.12 timbl 385: NAME="z4" HREF="#z3"> HTStreamStack</A>
2.7 timbl 386: and <A
2.12 timbl 387: NAME="c7" HREF="#c6">HTFileCopy</A> . Returns HT_LOADED
2.7 timbl 388: if succesful, <0 if not.
2.6 secret 389: <PRE>extern int HTParseFile PARAMS((
390: HTFormat format_in,
391: FILE *fp,
2.13 timbl 392: HTRequest * request));
2.8 timbl 393:
394: </PRE>
2.11 timbl 395: <H2><A
396: NAME="z11">HTNetToText: Convert Net ASCII to
397: local representation</A></H2>This is a filter stream suitable
398: for taking text from a socket and
399: passing it into a stream which expects
400: text in the local C representation.
401: It does ASCII and newline conversion.
402: As usual, pass its output stream
403: to it when creating it.
404: <PRE>extern HTStream * HTNetToText PARAMS ((HTStream * sink));
405:
406: </PRE>
2.8 timbl 407: <H2>HTFormatInit: Set up default presentations
408: and conversions</H2>These are defined in HTInit.c or
409: HTSInit.c if these have been replaced.
410: If you don't call this routine, and
411: you don't define any presentations,
412: then this routine will automatically
413: be called the first time a conversion
414: is needed. However, if you explicitly
415: add some conversions (eg using HTLoadRules)
416: then you may want also to explicitly
417: call this to get the defaults as
418: well.
2.20 frystyk 419: <PRE>
420: extern void HTFormatInit PARAMS((HTList * conversions));
2.21 ! frystyk 421: </PRE>
! 422:
! 423: <H2>HTFormatInitNIM: Set up default presentations and conversions</H2>
! 424: Basicly the same as HTFormatInit but without any calls to third party programs
! 425: that might pop up on the screen. This is, e.g., for Non-Interactive Mode
! 426: execution of a browser.
! 427: <PRE>
2.20 frystyk 428: extern void HTFormatInitNIM PARAMS((HTList * conversions));
2.1 timbl 429: </PRE>
2.21 ! frystyk 430:
! 431: <H2>HTFormatDelete: Remove presentations and conversions</H2>
! 432: This function cleans up the list of presentations and conversions.
! 433: <PRE>
! 434: extern void HTFormatDelete PARAMS((HTList * conversions));
! 435: </PRE>
! 436:
2.1 timbl 437: <H2>Epilogue</H2>
438: <PRE>extern BOOL HTOutputSource; /* Flag: shortcut parser */
439: #endif
440:
2.15 timbl 441: </PRE>end</A></BODY>
2.10 timbl 442: </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