Annotation of libwww/Library/src/HTIOStream.html, revision 2.7

2.1       frystyk     1: <HTML>
                      2: <HEAD>
2.2       frystyk     3:   <!-- Changed by: Henrik Frystyk Nielsen,  6-Apr-1996 -->
2.4       frystyk     4:   <TITLE>W3C Sample Code Library libwww I/O Stream Classes</TITLE>
2.1       frystyk     5: </HEAD>
                      6: <BODY>
2.2       frystyk     7: <H1>
                      8:   I/O Stream Classes
                      9: </H1>
2.1       frystyk    10: <PRE>
                     11: /*
                     12: **     (c) COPYRIGHT MIT 1995.
                     13: **     Please first read the full copyright statement in the file COPYRIGH.
                     14: */
                     15: </PRE>
2.2       frystyk    16: <P>
                     17: The I/O Stream class defines objects which accepts a sequence of characters
                     18: to and from a <A HREF="HTTrans.html">transport</A> &nbsp;The input and output
                     19: stream are mainly derived from the <A HREF="HTStream.html">generic stream
                     20: class</A> and contains much of the same functionality. The main difference
                     21: is that the I/O streams also contains methods for reading and writing to
                     22: a transport.
                     23: <P>
2.5       frystyk    24: This module is a part of the <A HREF="http://www.w3.org/Library/">W3C
2.4       frystyk    25: Sample Code Library</A>.
2.1       frystyk    26: <PRE>
                     27: #ifndef HTIOSTREAM_H
                     28: #define HTIOSTREAM_H
                     29: 
2.7     ! vbancrof   30: #ifdef __cplusplus
        !            31: extern "C" { 
        !            32: #endif 
        !            33: 
2.1       frystyk    34: typedef struct _HTInputStream HTInputStream;
                     35: typedef struct _HTOutputStream HTOutputStream;
                     36: 
                     37: #include "HTList.h"
                     38: #include "HTStream.h"
                     39: #include "HTChannl.h"
2.7     ! vbancrof   40: 
2.1       frystyk    41: </PRE>
2.2       frystyk    42: <H2>
                     43:   Input Stream
                     44: </H2>
                     45: <P>
                     46: An input stream is a stream that can read data from a transport and via a
                     47: <A HREF="HTChannl.html">channel</A> putting the data down to the application.
2.1       frystyk    48: <PRE>
                     49: typedef struct _HTInputStreamClass {
                     50: 
                     51:     char * name;
                     52: </PRE>
2.2       frystyk    53: <P>
2.1       frystyk    54: This field is for diagnostics only
                     55: <PRE>
                     56:     int (*flush)       (HTInputStream * me);
                     57: </PRE>
2.2       frystyk    58: <P>
                     59: The <B>flush</B> method is introduced in order to allow the stream to put
                     60: any buffered data down the stream pipe but without taking the stream pipe
                     61: down. It is for the stream to decide whether it has buffered data or not.
                     62: In some situations, the stream might not want to send buffered data down
                     63: the target as the date might be relevant for this stream only.
2.1       frystyk    64: <PRE>
                     65:     int (*_free)       (HTInputStream * me);
                     66: </PRE>
2.2       frystyk    67: <P>
                     68: The <CODE><B>free</B></CODE> method is like the <CODE>flush</CODE> method
                     69: but it also frees the current stream object and all stream objects down stream.
                     70: When the <CODE>free</CODE> method has been called, the <EM>whole</EM> stream
                     71: pipe (not only this object) should not accept any more data. See also the
                     72: <CODE>close</CODE> method below
2.1       frystyk    73: <PRE>
                     74:     int (*abort)       (HTInputStream * me, HTList * errorlist);
                     75: </PRE>
2.2       frystyk    76: <P>
                     77: The <B>abort</B> method should only be used if a stream is interrupted, for
                     78: example by the user, or an error occurs.
2.1       frystyk    79: <PRE>
                     80:     int (*read)                (HTInputStream * me);
                     81: </PRE>
2.2       frystyk    82: <P>
                     83: The <B>read</B> method is the method by which we can read data from the
                     84: <A HREF="HTTrans.html">transport layer</A>.
2.1       frystyk    85: <PRE>
                     86:     int (*close)       (HTInputStream * me);
                     87: </PRE>
2.2       frystyk    88: <P>
2.3       frystyk    89: Pipelined transports need to know how many bytes were <B>consumed</B> by 
                     90: the net object.
                     91: <PRE>
                     92:     int (*consumed)    (HTInputStream * me, size_t bytes);
                     93: </PRE>
                     94: <P>
2.2       frystyk    95: The <CODE>close</CODE> method closes the transport and deletes the input
                     96: stream object. Note that this is different than the free method which doesn't
                     97: have to delete the input stream object itself.
2.1       frystyk    98: <PRE>
                     99: } HTInputStreamClass;
                    100: </PRE>
2.2       frystyk   101: <H2>
                    102:   Output Stream
                    103: </H2>
                    104: <P>
                    105: The output stream is similar to the <A HREF="HTStream.html">generic stream
                    106: definition</A> in that it has a superset of methods. The <CODE>param</CODE>
                    107: parameter and the <CODE>mode</CODE> parameter can be used for whatever purpose
                    108: suited.
2.1       frystyk   109: <PRE>
                    110: typedef struct _HTOutputStreamClass {
                    111: 
                    112:     char * name;
                    113: 
                    114:     int (*flush)       (HTOutputStream * me);
                    115: 
                    116:     int (*_free)       (HTOutputStream * me);
                    117: 
                    118:     int (*abort)       (HTOutputStream * me, HTList * errorlist);
                    119: 
                    120:     int (*put_character)(HTOutputStream * me, char ch);
                    121: 
                    122:     int (*put_string)  (HTOutputStream * me, const char * str);
                    123: 
                    124:     int (*put_block)   (HTOutputStream * me, const char * str, int len);
                    125: </PRE>
2.2       frystyk   126: <P>
                    127: See the <A HREF="HTStream.html">generic Stream Definition</A> for an explanation
                    128: of these methods. Note that they all have a <CODE>HTOutputStream</CODE> object
                    129: a the parameter, not a generic stream. This is to avoid <EM>incompatible
                    130: pointer</EM> warnings
2.1       frystyk   131: <PRE>
                    132:     int (*close)       (HTOutputStream * me);
                    133: </PRE>
2.2       frystyk   134: <P>
                    135: The <CODE>close</CODE> method closes the transport and deletes the input
                    136: stream object. Note that this is different than the free method which doesn't
                    137: have to delete the input stream object itself.
2.1       frystyk   138: <PRE>
                    139: } HTOutputStreamClass;
                    140: </PRE>
2.2       frystyk   141: <H2>
                    142:   Transport Streams
                    143: </H2>
                    144: <P>
                    145: Transport streams are special streams with creation methods like defined
                    146: below. Transport streams can be registered in a
                    147: <A HREF="HTTrans.html">transport object</A> as ways of communicating with
                    148: the a transport.
                    149: <H3>
                    150:   Transport Input Stream
                    151: </H3>
                    152: <P>
                    153: We have two modes of the input stream depending on model used for data reading
                    154: is <B>PUSH</B> or <B>PULL</B>. The PUSH model is suitable if we are using
                    155: pseudo threads based on a <CODE>select()</CODE> call or equivalent and the
                    156: <B>PULL</B> is suitable in a real thread environment. In the latter case
                    157: it doesn't matter if a read procedure blocks as this only concerns a single
                    158: thread.
2.1       frystyk   159: <PRE>
2.3       frystyk   160: typedef HTInputStream * HTInput_new    (HTHost *       host,
2.1       frystyk   161:                                         HTChannel *    ch,
                    162:                                         void *         param,
                    163:                                         int            mode);
                    164: </PRE>
2.2       frystyk   165: <H3>
                    166:   Transport Output Stream
                    167: </H3>
2.1       frystyk   168: <PRE>
2.3       frystyk   169: typedef HTOutputStream * HTOutput_new  (HTHost *       host,
2.1       frystyk   170:                                         HTChannel *    ch,
                    171:                                         void *         param,
                    172:                                         int            mode);
                    173: </PRE>
2.6       frystyk   174: <H3>
                    175:   Transport Output Stream Converter
                    176: </H3>
                    177: <PRE>
                    178: typedef HTOutputStream * HTOutputConverter_new(
                    179:        HTHost *                host,
                    180:        HTChannel *             ch,
                    181:        void *                  param,
                    182:        int                     mode,
                    183:        HTOutputStream *        target);
                    184: </PRE>
2.1       frystyk   185: <PRE>
2.7     ! vbancrof  186: #ifdef __cplusplus
        !           187: }
        !           188: #endif
        !           189: 
2.1       frystyk   190: #endif /* HTIOSTREAM_H */
                    191: </PRE>
2.2       frystyk   192: <P>
                    193:   <HR>
2.1       frystyk   194: <ADDRESS>
2.7     ! vbancrof  195:   @(#) $Id: HTIOStream.html,v 2.6 1999/04/04 00:12:00 frystyk Exp $
2.1       frystyk   196: </ADDRESS>
2.2       frystyk   197: </BODY></HTML>

Webmaster