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