Annotation of libwww/Library/src/HTFormat.html, revision 2.84

2.10      timbl       1: <HTML>
                      2: <HEAD>
2.71      frystyk     3:   <!-- Changed by: Henrik Frystyk Nielsen, 15-Jul-1996 -->
2.75      frystyk     4:   <TITLE>W3C Sample Code Library libwww Stream Pipe Manager</TITLE>
2.10      timbl       5: </HEAD>
2.1       timbl       6: <BODY>
2.67      frystyk     7: <H1>
2.68      frystyk     8:   The Stream Pipe Manager
2.67      frystyk     9: </H1>
2.33      frystyk    10: <PRE>
                     11: /*
2.41      frystyk    12: **     (c) COPYRIGHT MIT 1995.
2.33      frystyk    13: **     Please first read the full copyright statement in the file COPYRIGH.
                     14: */
                     15: </PRE>
2.67      frystyk    16: <P>
2.68      frystyk    17: The Stream Pipe Manager is responsible for setting up the stream pipe from
                     18: the <A HREF="HTChannl.html">Channel Object</A> to the
                     19: <A HREF="HTReq.html">Request Object</A> when data is arriving, for example
                     20: as a response to s <A HREF="HTTP.html">HTTP</A> <B>Get</B> request. As data
                     21: arrives, we start to parse it and the more we know the more we can build
                     22: up our stream pipe. For example, in the case of HTTP, we first have a stream
                     23: that can parse the HTTP response line containing "<CODE>200 OK</CODE>". Then
                     24: we have a <A HREF="HTMIME.html">MIME parser</A> for handling the MIME headers.
                     25: When the MIME headers have been parsed, we know the content type and any
                     26: encoding of the MIME body. If we need to decode a chunked encoding then we
                     27: set up a chunked decoder, and if we have to parse a HTML object then we set
                     28: up a HTML parser.
2.67      frystyk    29: <P>
                     30: The Format Manager is also responsible for keeping track of the
                     31: "<I>preferences</I>" of the application and/or user. It is an integral part
                     32: of the Web and HTTP, that the client application can express its preferences
                     33: as a set of "accept" headers in a HTTP request. This task is highly related
                     34: to the task mentioned above as we there use the modules that are registered
                     35: and here tell the remote server what we are capable of doing and what we
                     36: would prefer.
                     37: <P>
                     38: <B>Note</B>: The library <B>core</B> does not define any default decoders
                     39: or parsers - they are all considered part of the application. The library
                     40: comes with a default set of parsers including the ones mentioned above which
                     41: can be initiated using the functions in <A HREF="HTInit.html">HTInit
                     42: module</A>. There are different initialization functions for content type
                     43: parsers and content encodings respectively.
                     44: <P>
                     45: <UL>
                     46:   <LI>
                     47:     <A HREF="#type">Content Type Converters and Presenters</A>
                     48:   <LI>
                     49:     <A HREF="#encoding">Content Encoders and Decoders</A>
                     50:   <LI>
                     51:     <A HREF="#charset">Content Charsets</A>
                     52:   <LI>
                     53:     <A HREF="#language">Natural Languages</A>
                     54: </UL>
                     55: <P>
                     56: The application can assign its preferences in two ways: either <I>locally</I>
                     57: to a single request or <I>globally</I> to all requests. The local assignment
                     58: can either <I>add to </I>or <I>override</I> the global settings depending
                     59: on how they are registered. All local registration is handled by the
                     60: <A HREF="HTReq.html">Request Object</A> and the global registration is handled
2.73      frystyk    61: by the Format Manager.
2.67      frystyk    62: <P>
                     63: This module is implemented by <A HREF="HTFormat.c">HTFormat.c</A>, and it
2.80      frystyk    64: is a part of the <A HREF="http://www.w3.org/Library/">W3C Sample Code
2.67      frystyk    65: Library</A>.
2.31      frystyk    66: <PRE>
                     67: #ifndef HTFORMAT_H
2.1       timbl      68: #define HTFORMAT_H
                     69: 
2.63      frystyk    70: #include "<A HREF="HTUtils.html">HTUtils.h</A>"
                     71: #include "<A HREF="HTStream.html">HTStream.h</A>"
                     72: #include "<A HREF="HTAtom.html">HTAtom.h</A>"
                     73: #include "<A HREF="HTList.html">HTList.h</A>"
                     74: #include "<A HREF="HTAnchor.html">HTAnchor.h</A>"
                     75: #include "<A HREF="HTReq.html">HTReq.h</A>"
2.31      frystyk    76: </PRE>
2.67      frystyk    77: <H2>
2.73      frystyk    78:   <A NAME="type">Converters and Presenters</A>
2.67      frystyk    79: </H2>
                     80: <P>
                     81: All content type converters are subclassed from the Generic stream objetc.
                     82: That way, we allow the application to do very fast progressive display of
                     83: incoming data. In other words, the stream model of the Library provides data
                     84: as soon as it arrives from the network, the application does not have to
                     85: wait until the whole document has been down loaded before it starts parsing
                     86: it.
                     87: <H3>
                     88:   Predefined Content Types
                     89: </H3>
                     90: <P>
                     91: These macros (which used to be constants) define some basic internally referenced
                     92: representations. The <CODE>www/xxx</CODE> ones are of course not MIME standard.
                     93: They are internal representations used in the Library but they can't be exported
                     94: to other apps!
2.28      frystyk    95: <PRE>
2.82      frystyk    96: #define WWW_INTERNAL   HTAtom_for("www/*")          /* All internal formats */
                     97: </PRE>
                     98: <P>
                     99: <CODE>WWW_INTERNAL</CODE> represent all internal formats. This can for example
                    100: be used to match using the <A HREF="HTWWWStr.html">HTMIMEMatch(...)</A>.
                    101: <PRE>
2.57      frystyk   102: #define WWW_RAW                HTAtom_for("www/void")   /* Raw output from Protocol */
2.28      frystyk   103: </PRE>
2.67      frystyk   104: <P>
                    105: <CODE>WWW_RAW</CODE> is an output format which leaves the input untouched
                    106: <EM>exactly</EM> as it is received by the protocol module. For example, in
                    107: the case of FTP, this format returns raw ASCII objects for directory listings;
                    108: for HTTP, everything including the header is returned, for Gopher, a raw
                    109: ASCII object is returned for a menu etc.
                    110: <PRE>
                    111: #define WWW_SOURCE     HTAtom_for("*/*")
                    112: </PRE>
                    113: <P>
                    114: <CODE>WWW_SOURCE</CODE> is an output format which leaves the input untouched
                    115: <EM>exactly</EM> as it is received by the protocol module <B>IF</B> not a
                    116: suitable converter has been registered with a quality factor higher than
                    117: 1 (for example 2). In this case the <EM>SUPER CONVERTER</EM> is preferred
                    118: for the raw output. This can be used as a filter effect that allows conversion
                    119: from, for example raw FTPdirectory listings into HTML but passes a MIME body
                    120: untouched.
                    121: <PRE>
                    122: #define WWW_PRESENT    HTAtom_for("www/present")
                    123: </PRE>
                    124: <P>
                    125: <CODE>WWW_PRESENT</CODE> represents the user's perception of the document.
                    126: If you convert to <CODE>WWW_PRESENT</CODE>, you present the material to the
                    127: user.
2.58      frystyk   128: <PRE>
                    129: #define WWW_DEBUG      HTAtom_for("www/debug")
                    130: </PRE>
2.67      frystyk   131: <P>
                    132: <CODE>WWW_DEBUG</CODE> represents the user's perception of debug information,
                    133: for example sent as a HTML document in a HTTP redirection message.
2.28      frystyk   134: <PRE>
2.52      frystyk   135: #define WWW_UNKNOWN     HTAtom_for("www/unknown")
2.28      frystyk   136: </PRE>
2.67      frystyk   137: <P>
                    138: <CODE>WWW_UNKNOWN</CODE> is a really unknown type. It differs from the real
                    139: MIME type <EM>"application/octet-stream"</EM> in that we haven't even tried
                    140: to figure out the content type at this point.
2.71      frystyk   141: <PRE>
2.72      frystyk   142: #define WWW_CACHE         HTAtom_for("www/cache")
                    143: #define WWW_CACHE_APPEND  HTAtom_for("www/cache-append")
2.71      frystyk   144: </PRE>
                    145: <P>
                    146: <CODE>WWW_CACHE</CODE> is the internal content-type designated for a persistent
2.72      frystyk   147: cache module which can store the object to local storage. The cache append
                    148: format is special in that we append information to an already existing cache
                    149: entry. This can happen if we have issued a <CODE>If-Range </CODE>request
                    150: and got back a "206 Partial response".
2.67      frystyk   151: <P>
2.31      frystyk   152: These are regular MIME types defined. Others can be added!
2.28      frystyk   153: <PRE>
2.52      frystyk   154: #define WWW_HTML       HTAtom_for("text/html")
2.28      frystyk   155: #define WWW_PLAINTEXT  HTAtom_for("text/plain")
2.69      frystyk   156: #define WWW_FORM       HTAtom_for("application/x-www-form-urlencoded")
2.52      frystyk   157: 
                    158: #define WWW_MIME       HTAtom_for("message/rfc822")
2.60      frystyk   159: #define WWW_MIME_HEAD  HTAtom_for("message/x-rfc822-head")
2.65      frystyk   160: #define WWW_MIME_FOOT  HTAtom_for("message/x-rfc822-foot")
2.72      frystyk   161: #define WWW_MIME_PART   HTAtom_for("message/x-rfc822-partial")
2.76      frystyk   162: #define WWW_MIME_CONT   HTAtom_for("message/x-rfc822-cont")
2.84    ! frystyk   163: #define WWW_MIME_UPGRADE       HTAtom_for("message/x-rfc822-upgrade")
2.52      frystyk   164: 
2.10      timbl     165: #define WWW_AUDIO       HTAtom_for("audio/basic")
2.52      frystyk   166: 
2.26      frystyk   167: #define WWW_VIDEO      HTAtom_for("video/mpeg")
2.52      frystyk   168: 
2.70      frystyk   169: #define WWW_GIF        HTAtom_for("image/gif")
2.63      frystyk   170: #define WWW_JPEG       HTAtom_for("image/jpeg")
                    171: #define WWW_TIFF       HTAtom_for("image/tiff")
2.52      frystyk   172: #define WWW_PNG        HTAtom_for("image/png")
                    173: 
                    174: #define WWW_BINARY     HTAtom_for("application/octet-stream")
                    175: #define WWW_POSTSCRIPT         HTAtom_for("application/postscript")
                    176: #define WWW_RICHTEXT   HTAtom_for("application/rtf")
2.48      frystyk   177: </PRE>
2.67      frystyk   178: <P>
                    179: We also have some MIME types that come from the various protocols when we
                    180: convert from ASCII to HTML.
2.48      frystyk   181: <PRE>
                    182: #define WWW_GOPHER_MENU HTAtom_for("text/x-gopher")
2.53      frystyk   183: #define WWW_CSO_SEARCH HTAtom_for("text/x-cso")
2.48      frystyk   184: 
                    185: #define WWW_FTP_LNST   HTAtom_for("text/x-ftp-lnst")
                    186: #define WWW_FTP_LIST   HTAtom_for("text/x-ftp-list")
                    187: 
                    188: #define WWW_NNTP_LIST   HTAtom_for("text/x-nntp-list")
                    189: #define WWW_NNTP_OVER  HTAtom_for("text/x-nntp-over")
                    190: #define WWW_NNTP_HEAD  HTAtom_for("text/x-nntp-head")
2.59      frystyk   191: 
                    192: #define WWW_HTTP       HTAtom_for("text/x-http")
2.55      frystyk   193: </PRE>
2.67      frystyk   194: <P>
                    195: Finally we have defined a special format for our RULE files as they can be
                    196: handled by a special converter.
2.73      frystyk   197: <PRE>#define WWW_RULES HTAtom_for("application/x-www-rules")
                    198: </PRE>
                    199: <H3>
                    200:   The Quality Factor
                    201: </H3>
                    202: <P>
                    203: Characteristic for all preferences is that there is a quality factor associated
                    204: with each member. The quality factor is a real number between 0 and 1 with
                    205: 0 meaning "very bad" and 1 means "perfect". By registering a natural language
                    206: or any or other preference in this group together with a quality factor you
                    207: can specify "how well the preference is handled" either by the application
                    208: or by the user. In the case of the user the quality factor of a natural language
                    209: is how well the user understands the language. In my case, the quality factors
                    210: for, for example Greek would be close to zero and 1 for Danish (nothing bad
                    211: said about Greek!).
                    212: <P>
                    213: It is a bit different for converters where it is often the application's
                    214: ability of handling the data format rather than the user's perception. As
                    215: an example it is often faster to use a converter than a presenter as it takes
                    216: time to launch the external application and libwww can not use progressive
                    217: display mechanisms which is often the case for converters. Therefore, as
                    218: an example, if we capable of handling an image in <EM>png</EM> format inline
                    219: but rely on an external viewer for presenting postscript, we might set up
                    220: the following list:
                    221: <P>
                    222: <SAMP>HTConversion_add (converters, "image", "www/present", GifPresenter,
                    223: <B>1.0</B>, 0.0, 0.0);<BR>
                    224: HTPresentation_add (presenters, "application/postscript", "ghostview %s",
                    225: NULL, <B>0.5</B>, 0.0, 0.0);&gt;</SAMP>
                    226: <P>
                    227: where the gif converter is registered with a quality factor of <B>1.0</B>
                    228: and the postscript presenter with a quality factor of <B>0.5</B>.Register
                    229: Presenters
                    230: <H3>
                    231:   The Converter Class
                    232: </H3>
                    233: <P>
                    234: A <CODE>converter</CODE> is a stream with a special set of parameters and
                    235: which is registered as capable of converting from a MIME type to something
                    236: else (maybe another MIME-type). A converter is defined to be a function returning
                    237: a stream and accepting the following parameters. The content type elements
                    238: are atoms for which we have defined a prototype.
2.55      frystyk   239: <PRE>
2.73      frystyk   240: typedef HTStream * HTConverter (HTRequest *    request,
                    241:                                 void *         param,
                    242:                                 HTFormat       input_format,
                    243:                                 HTFormat       output_format,
                    244:                                 HTStream *     output_stream);
                    245: 
                    246: extern void HTConversion_add   (HTList *       conversions,
                    247:                                const char *    rep_in,
                    248:                                const char *    rep_out,
                    249:                                HTConverter *   converter,
                    250:                                double          quality,
                    251:                                double          secs, 
                    252:                                double          secs_per_byte);
                    253: 
                    254: extern void HTConversion_deleteAll     (HTList * list);
2.28      frystyk   255: </PRE>
2.67      frystyk   256: <H3>
2.73      frystyk   257:   The Presenter Class
2.67      frystyk   258: </H3>
                    259: <P>
2.73      frystyk   260: A <CODE>presenter</CODE> is a module (possibly an external program) which
                    261: can present a graphic object of a certain MIME type to the user. That is,
                    262: <CODE>presenters</CODE> are normally used to present objects that the
                    263: <CODE>converters</CODE> are not able to handle. Data is transferred to the
2.83      frystyk   264: external program using a special "presenter stream" which for example can
                    265: use the local disk to transfer the data from libwww to the external program.
                    266: <P>
                    267: Libwww provides a default <A HREF="HTFWrite.html">HTSaveAndExecute</A>
                    268: stream which you may want to use for this purpose. However, any stream
                    269: that is of type <CODE>HTConverter</CODE> will do. You can manage the
                    270: special presenter stream using the following methods:
                    271: <PRE>
                    272: extern void HTPresentation_setConverter (HTConverter * pconv);
                    273: extern HTConverter * HTPresentation_converter (void);
                    274: </PRE>
                    275: Both presenters and converters are of the type
2.73      frystyk   276: <A HREF="#converter">HTConverter</A>.
2.31      frystyk   277: <PRE>
2.49      frystyk   278: extern void HTPresentation_add (HTList *       conversions,
2.83      frystyk   279:                                const char *    representation,
2.61      frystyk   280:                                const char *    command,
                    281:                                const char *    test_command,
2.49      frystyk   282:                                double          quality,
                    283:                                double          secs, 
                    284:                                double          secs_per_byte);
2.1       timbl     285: 
2.50      frystyk   286: extern void HTPresentation_deleteAll   (HTList * list);
                    287: </PRE>
2.67      frystyk   288: <H3>
2.73      frystyk   289:   Basic Converters
2.67      frystyk   290: </H3>
                    291: <P>
2.73      frystyk   292: We have a small set of basic converters that can be hooked in anywhere. They
                    293: don't "convert" anything but are nice to have.
2.79      frystyk   294: <PRE>
                    295: extern HTConverter HTThroughLine;
2.73      frystyk   296: extern HTConverter HTBlackHoleConverter;
2.79      frystyk   297: extern HTConverter HTSaveConverter;
2.42      frystyk   298: </PRE>
2.67      frystyk   299: <H2>
                    300:   <A NAME="encoding">Content and Transfer Encoders and Decoders</A>
                    301: </H2>
                    302: <P>
                    303: Content codins are transformations applied to an entity object after it was
                    304: created in its original form. The Library handles two types of codings:
2.64      frystyk   305: <DL>
2.67      frystyk   306:   <DT>
                    307:     <B>Content Codings</B>
                    308:   <DD>
                    309:     Content codings values indicate an encoding transformation that has been
                    310:     applied to a resource. Content cosings are primarily used to allow a document
                    311:     to be compressed or encrypted without loosing the identity of its underlying
                    312:     media type.
                    313:   <DT>
                    314:     <B>Content Transfer Codings</B>
                    315:   <DD>
                    316:     Content transfer codings values are used to indicate an encoding transformation
                    317:     that has been, can be, or may be need to be applied to an enity body in order
                    318:     to ensure safe transport through the network. This differs from a content
                    319:     coding in that the transfer coding is a property of the message, not the
                    320:     original message.
2.64      frystyk   321: </DL>
2.67      frystyk   322: <P>
                    323: Both types of encodings use the same registration mechanism in the Library
                    324: which we describe below:
                    325: <H3>
                    326:   Encoders and Decoders
                    327: </H3>
                    328: <P>
                    329: <EM>Encoders</EM> and <EM>decoders</EM> are subclassed from the
                    330: <A HREF="HTStream.html">generic stream class</A>. <EM>Encoders</EM> are capable
                    331: of adding a content coding to a data object and <EM>decoders</EM> can remove
                    332: a content coding.
2.50      frystyk   333: <PRE>
2.64      frystyk   334: typedef HTStream * HTCoder     (HTRequest *    request,
                    335:                                 void *         param,
                    336:                                 HTEncoding     coding,
                    337:                                 HTStream *     target);
2.50      frystyk   338: </PRE>
2.67      frystyk   339: <P>
                    340: The <EM>encoding</EM> is the name of the encoding mechanism reporesented
                    341: as an <A HREF="HTAtom.html">atom</A>, for example "zip", "chunked", etc.
                    342: Encodings are registered in lists and content encodings are separated from
                    343: transfer encodings by registering them in different lists.
                    344: <H3>
2.81      frystyk   345:   Basic Encoders
                    346: </H3>
                    347: <P>
                    348: We have a small set of basic coders that can be hooked in anywhere.
                    349: <PRE>
                    350: extern HTCoder HTIdentityCoding;
                    351: </PRE>
                    352: <H3>
2.67      frystyk   353:   The HTCoding Object
                    354: </H3>
                    355: <P>
                    356: The <EM>HTCoding</EM> object represents a registered encoding together with
                    357: a encoder and a decoder.
2.63      frystyk   358: <PRE>
2.64      frystyk   359: typedef struct _HTCoding HTCoding;
2.63      frystyk   360: </PRE>
2.67      frystyk   361: <P>
                    362: Predefined Coding Types We have a set of pre defined atoms for various types
                    363: of content encodings and transfer encodings. "chunked" is not exactly in
                    364: the same group as the other encodings such as "binary" but it really doesn't
                    365: make any difference as it is just a matter of how the words are chosen. The
                    366: first three transfer encodings are actually not encodings - they are just
                    367: left overs from brain dead mail systems.
2.42      frystyk   368: <PRE>
2.79      frystyk   369: #define WWW_CODING_7BIT                HTAtom_for("7bit")
                    370: #define WWW_CODING_8BIT                HTAtom_for("8bit")
                    371: #define WWW_CODING_BINARY      HTAtom_for("binary")
                    372: #define WWW_CODING_IDENTITY     HTAtom_for("identity")
2.64      frystyk   373: 
2.79      frystyk   374: #define WWW_CODING_BASE64      HTAtom_for("base64")
                    375: #define WWW_CODING_MACBINHEX   HTAtom_for("macbinhex")
                    376: #define WWW_CODING_CHUNKED     HTAtom_for("chunked")
2.63      frystyk   377: 
2.79      frystyk   378: #define WWW_CODING_COMPRESS    HTAtom_for("compress")
                    379: #define WWW_CODING_GZIP                HTAtom_for("gzip")
                    380: #define WWW_CODING_DEFLATE      HTAtom_for("deflate")
2.42      frystyk   381: </PRE>
2.67      frystyk   382: <H3>
                    383:   Register Content Coders
                    384: </H3>
                    385: <P>
2.73      frystyk   386: Some documents are not send in their original data obejct but is encoded
                    387: in some way. On the Web this is mostly some kind of compression but other
                    388: encodings for example base 64 can be encountered when talking to NNTP servers
                    389: etc. Just as for the other preferences, an application can register a supported
                    390: encoders or decodes as a list. Encoders and decoders are registered in the
                    391: same way with no differentiation whether it is a encoder or a decoder:
2.42      frystyk   392: <PRE>
2.64      frystyk   393: extern BOOL HTCoding_add (HTList *     list,
                    394:                         const char *   encoding,
                    395:                         HTCoder *      encoder,
                    396:                         HTCoder *      decoder,
                    397:                         double         quality);
2.63      frystyk   398: 
2.64      frystyk   399: extern void HTCoding_deleteAll (HTList * list);
2.42      frystyk   400: 
2.64      frystyk   401: extern const char * HTCoding_name (HTCoding * me);
2.77      frystyk   402: 
                    403: extern double HTCoding_quality (HTCoding * me);
2.42      frystyk   404: </PRE>
2.67      frystyk   405: <H2>
                    406:   <A NAME="charset">Content Charsets</A>
                    407: </H2>
2.73      frystyk   408: <P>
                    409: As the Web reaches all parts of the Internet there are more and more documents
                    410: written in languages which contains characters not included in the ISO-8859-1
                    411: character set. A consequence of this the set of characters sets is often
                    412: tightly connected with the natural language. libwww does not directly support
                    413: other character sets but in case an application is capable of handling
                    414: alternative sets it can register these as preferred character sets along
                    415: with a quality factor just as all the other preferences in this section.
                    416: <PRE>extern void HTCharset_add (HTList * list, const char * charset, double quality);
2.42      frystyk   417: </PRE>
2.73      frystyk   418: <PRE>typedef struct _HTAcceptNode {
2.63      frystyk   419:     HTAtom *   atom;
                    420:     double     quality;
                    421: } HTAcceptNode;
                    422: </PRE>
                    423: <PRE>
2.50      frystyk   424: extern void HTCharset_deleteAll        (HTList * list);
                    425: </PRE>
2.67      frystyk   426: <H2>
                    427:   <A NAME="language">Content Languages</A>
                    428: </H2>
2.73      frystyk   429: <P>
                    430: The preferred natural language or languages is in almost all situations dependent
                    431: on the individual user and an application should therefore give the user
                    432: the opportunity to change the setup. When specifying a natural language
                    433: preference, libwww will send this preference along with all HTTP requests.
                    434: The remote server will then (it if supports this feature) look for a version
                    435: in the language or languages mentioned. If it finds a matching document then
                    436: it returns this one, otherwise it uses the best alternative. If no language
                    437: is specified the remote server may whatever version it finds.
                    438: <PRE>extern void HTLanguage_add (HTList * list, const char * lang, double quality);
2.51      frystyk   439: extern void HTLanguage_deleteAll (HTList * list);
2.50      frystyk   440: </PRE>
2.67      frystyk   441: <H2>
                    442:   <A NAME="global">Global Preferences</A>
                    443: </H2>
                    444: <P>
2.50      frystyk   445: There are two places where these preferences can be registered: in a
2.67      frystyk   446: <EM>global</EM> list valid for <B>all</B> requests and a <EM>local</EM> list
                    447: valid for a particular request only. These are valid for <EM>all</EM> requests.
                    448: See the <A HREF="HTReq.html">Request Manager</A> fro local sets.
                    449: <H3>
2.73      frystyk   450:   Global Converters and Presenters
2.67      frystyk   451: </H3>
                    452: <P>
                    453: The <EM>global</EM> list of specific conversions which the format manager
                    454: can do in order to fulfill the request. There is also a
                    455: <A HREF="HTReq.html"><EM>local</EM></A> list of conversions which contains
                    456: a generic set of possible conversions.
2.73      frystyk   457: <PRE>extern void HTFormat_setConversion        (HTList * list);
2.50      frystyk   458: extern HTList * HTFormat_conversion    (void);
2.69      frystyk   459: 
                    460: extern void HTFormat_addConversion (const char *       input_format,
                    461:                                    const char *        output_format,
                    462:                                    HTConverter *       converter,
                    463:                                    double              quality,
                    464:                                    double              secs, 
                    465:                                    double              secs_per_byte);
2.31      frystyk   466: </PRE>
2.67      frystyk   467: <H3>
2.73      frystyk   468:   Global Content Codings
2.67      frystyk   469: </H3>
2.73      frystyk   470: <PRE>extern void HTFormat_setContentCoding     (HTList * list);
2.64      frystyk   471: extern HTList * HTFormat_contentCoding (void);
2.69      frystyk   472: 
                    473: extern BOOL HTFormat_addCoding ( char *                encoding,
                    474:                                 HTCoder *      encoder,
                    475:                                 HTCoder *      decoder,
                    476:                                 double         quality);
2.50      frystyk   477: </PRE>
2.74      frystyk   478: <P>
2.82      frystyk   479: We also define a macro to find out whether a content encoding is really an
                    480: encoding or whether it is a unity encoder.
2.74      frystyk   481: <PRE>
                    482: #define HTFormat_isUnityContent(me) \
2.79      frystyk   483:        ((me)==NULL || \
                    484:        (me)==WWW_CODING_BINARY || (me)==WWW_CODING_IDENTITY || \
                    485:         (me)==WWW_CODING_7BIT || (me)==WWW_CODING_8BIT)
2.74      frystyk   486: </PRE>
2.67      frystyk   487: <H3>
2.77      frystyk   488:   Global Transfer Codings
2.67      frystyk   489: </H3>
2.73      frystyk   490: <PRE>extern void HTFormat_setTransferCoding    (HTList * list);
2.64      frystyk   491: extern HTList * HTFormat_transferCoding        (void);
2.69      frystyk   492: 
                    493: extern BOOL HTFormat_addTransferCoding ( char *                encoding,
                    494:                                         HTCoder *      encoder,
                    495:                                         HTCoder *      decoder,
                    496:                                         double         quality);
2.64      frystyk   497: </PRE>
2.67      frystyk   498: <P>
                    499: We also define a macro to find out whether a transfer encoding is really
                    500: an encoding or whether it is just a "dummy" as for example 7bit, 8bit, and
                    501: binary.
2.64      frystyk   502: <PRE>
                    503: #define HTFormat_isUnityTransfer(me) \
2.79      frystyk   504:        ((me)==NULL || \
                    505:         (me)==WWW_CODING_BINARY || (me)==WWW_CODING_IDENTITY || \
                    506:          (me)==WWW_CODING_7BIT || (me)==WWW_CODING_8BIT)
2.64      frystyk   507: </PRE>
2.67      frystyk   508: <H3>
2.73      frystyk   509:   Global Content Languages
2.67      frystyk   510: </H3>
2.73      frystyk   511: <PRE>extern void HTFormat_setLanguage  (HTList * list);
2.50      frystyk   512: extern HTList * HTFormat_language      (void);
                    513: </PRE>
2.67      frystyk   514: <H3>
2.73      frystyk   515:   Global Content Charsets
2.67      frystyk   516: </H3>
2.73      frystyk   517: <PRE>extern void HTFormat_setCharset           (HTList * list);
2.50      frystyk   518: extern HTList * HTFormat_charset       (void);
2.31      frystyk   519: </PRE>
2.67      frystyk   520: <H3>
                    521:   Delete All Global Lists
                    522: </H3>
                    523: <P>
2.50      frystyk   524: This is a convenience function that might make life easier.
2.73      frystyk   525: <PRE>extern void HTFormat_deleteAll (void);
2.34      frystyk   526: </PRE>
2.67      frystyk   527: <H2>
                    528:   <A NAME="CTStack">The Content Type Stream Stack</A>
                    529: </H2>
                    530: <P>
                    531: This is the routine which actually sets up the content type conversion. It
                    532: currently checks only for direct conversions, but multi-stage conversions
                    533: are forseen. It takes a stream into which the output should be sent in the
                    534: final format, builds the conversion stack, and returns a stream into which
                    535: the data in the input format should be fed. If <CODE>guess</CODE> is true
                    536: and input format is <CODE>www/unknown</CODE>, try to guess the format by
                    537: looking at the first few bytes of the stream.
2.31      frystyk   538: <PRE>
2.52      frystyk   539: extern HTStream * HTStreamStack (HTFormat      rep_in,
                    540:                                 HTFormat       rep_out,
                    541:                                 HTStream *     output_stream,
                    542:                                 HTRequest *    request,
                    543:                                 BOOL           guess);
2.1       timbl     544: </PRE>
2.67      frystyk   545: <H3>
                    546:   Cost of a Stream Stack
                    547: </H3>
                    548: <P>
                    549: Must return the cost of the same stack which HTStreamStack would set up.
2.31      frystyk   550: <PRE>
2.52      frystyk   551: extern double HTStackValue     (HTList *       conversions,
                    552:                                 HTFormat       format_in,
                    553:                                 HTFormat       format_out,
                    554:                                 double         initial_value,
                    555:                                 long int       length);
2.64      frystyk   556: </PRE>
2.67      frystyk   557: <H2>
                    558:   <A NAME="CEStack">Content Encoding Stream Stack</A>
                    559: </H2>
                    560: <P>
                    561: When creating a coding stream stack, it is important that we keep the right
                    562: order of encoders and decoders. As an example, the HTTP spec specifies that
                    563: the list in the <EM>Content-Encoding</EM> header follows the order in which
                    564: the encodings have been applied to the object. Internally, we represent the
                    565: content encodings as <A HREF="HTAtom.html">atoms</A> in a linked
                    566: <A HREF="HTList.html">list object</A>.
                    567: <P>
                    568: The creation of the content coding stack is not based on quality factors
                    569: as we don't have the freedom as with content types. When using content codings
                    570: we <EM>must</EM> apply the codings specified or fail.
2.64      frystyk   571: <PRE>
                    572: extern HTStream * HTContentCodingStack (HTEncoding     coding,
                    573:                                        HTStream *      target,
                    574:                                        HTRequest *     request,
                    575:                                        void *          param,
                    576:                                        BOOL            encoding);
                    577: </PRE>
2.67      frystyk   578: <P>
                    579: Here you can provide a complete list instead of a single token. The list
                    580: has to be filled up in the order the _encodings_ are to be applied
2.64      frystyk   581: <PRE>
                    582: extern HTStream * HTContentEncodingStack (HTList *     encodings,
                    583:                                          HTStream *    target,
                    584:                                          HTRequest *   request,
                    585:                                          void *        param);
                    586: </PRE>
2.67      frystyk   587: <P>
                    588: Here you can provide a complete list instead of a single token. The list
                    589: has to be in the order the _encodings_ were applied - that is, the same way
                    590: that _encodings_ are to be applied. This is all consistent with the order
                    591: of the Content-Encoding header.
2.64      frystyk   592: <PRE>
                    593: extern HTStream * HTContentDecodingStack (HTList *     encodings,
                    594:                                          HTStream *    target,
                    595:                                          HTRequest *   request,
                    596:                                          void *        param);
                    597: </PRE>
2.67      frystyk   598: <H2>
2.79      frystyk   599:   <A NAME="TEStack">Transfer Encoding Stream Stack</A>
                    600: </H2>
                    601: <P>
                    602: When creating a coding stream stack, it is important that we keep the right
                    603: order of encoders and decoders. As an example, the HTTP spec specifies that
                    604: the list in the <EM>Transfer-Encoding</EM> header follows the order in which
                    605: the encodings have been applied to the object. Internally, we represent the
                    606: content encodings as <A HREF="HTAtom.html">atoms</A> in a linked
                    607: <A HREF="HTList.html">list object</A>.
                    608: <P>
                    609: The creation of the content coding stack is not based on quality factors
                    610: as we don't have the freedom as with content types. When using content codings
                    611: we <EM>must</EM> apply the codings specified or fail.
                    612: <PRE>
                    613: extern HTStream * HTTransferCodingStack (HTEncoding    coding,
                    614:                                         HTStream *     target,
                    615:                                         HTRequest *    request,
                    616:                                         void *         param,
                    617:                                         BOOL           encoding);
                    618: </PRE>
                    619: <P>
                    620: Here you can provide a complete list instead of a single token. The list
                    621: has to be filled up in the order the _encodings_ are to be applied
                    622: <PRE>
                    623: extern HTStream * HTTransferEncodingStack (HTList *    encodings,
                    624:                                           HTStream *   target,
                    625:                                           HTRequest *  request,
                    626:                                           void *       param);
                    627: </PRE>
                    628: <P>
                    629: Here you can provide a complete list instead of a single token. The list
                    630: has to be in the order the _encodings_ were applied - that is, the same way
                    631: that _encodings_ are to be applied. This is all consistent with the order
                    632: of the Transfer-Encoding header.
                    633: <PRE>
                    634: extern HTStream * HTTransferDecodingStack (HTList *    encodings,
                    635:                                          HTStream *    target,
                    636:                                          HTRequest *   request,
                    637:                                          void *        param);
                    638: </PRE>
                    639: <H2>
2.77      frystyk   640:   <A NAME="CTEStack">Transfer Encoding Stream Stack</A>
2.67      frystyk   641: </H2>
                    642: <P>
                    643: Creating the transfer content encoding stream stack is not based on quality
                    644: factors as we don't have the freedom as with content types. Specify whether
                    645: you you want encoding or decoding using the BOOL "encode" flag.
2.64      frystyk   646: <PRE>
2.79      frystyk   647: extern HTStream * HTContentTransferCodingStack (HTEncoding     encoding,
                    648:                                                HTStream *      target,
                    649:                                                HTRequest *     request,
                    650:                                                void *          param,
                    651:                                                BOOL            encode);
2.64      frystyk   652: </PRE>
2.73      frystyk   653: <H3>
                    654:   Presentation Object
                    655: </H3>
                    656: <P>
                    657: This object is not to be used - it should have been hidden&nbsp;
                    658: <PRE>typedef struct _HTPresentation {
                    659:     HTFormat   rep;                         /* representation name atomized */
                    660:     HTFormat   rep_out;                         /* resulting representation */
                    661:     HTConverter *converter;          /* The routine to gen the stream stack */
                    662:     char *     command;                               /* MIME-format string */
                    663:     char *     test_command;                          /* MIME-format string */
                    664:     double     quality;                     /* Between 0 (bad) and 1 (good) */
                    665:     double     secs;
                    666:     double     secs_per_byte;
                    667: } HTPresentation;
                    668: </PRE>
2.64      frystyk   669: <PRE>
2.42      frystyk   670: #endif /* HTFORMAT */
2.38      frystyk   671: </PRE>
2.67      frystyk   672: <P>
                    673:   <HR>
2.63      frystyk   674: <ADDRESS>
2.84    ! frystyk   675:   @(#) $Id: HTFormat.html,v 2.83 1999/02/07 18:27:49 frystyk Exp $
2.63      frystyk   676: </ADDRESS>
2.67      frystyk   677: </BODY></HTML>

Webmaster