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