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