Annotation of libwww/Library/src/HTStream.html, revision 2.25
2.4 timbl 1: <HTML>
2: <HEAD>
2.22 frystyk 3: <!-- Changed by: Henrik Frystyk Nielsen, 25-Mar-1996 -->
2.23 frystyk 4: <TITLE>W3C Sample Code Library libwww Generic Stream Class</TITLE>
2.8 frystyk 5: </HEAD>
2.1 timbl 6: <BODY>
2.22 frystyk 7: <H1>
8: Generic Stream Class
9: </H1>
2.8 frystyk 10: <PRE>
11: /*
2.12 frystyk 12: ** (c) COPYRIGHT MIT 1995.
2.8 frystyk 13: ** Please first read the full copyright statement in the file COPYRIGH.
14: */
15: </PRE>
2.22 frystyk 16: <P>
17: The Stream class defines objects which accepts a sequence of characters.
18: Streams may also have an output in which case multiple stream objects can
19: be cascaded to build a stream pipe where the output of a stream is directed
20: into the input of the next stream object "down the line". Of course, one
21: of the main features of streams is that they can perform a <I>data conversion
22: </I>on the data before piping it to the output. As multiple streams may be
23: cascaded, the complete data conversion is then the sum of each individual
24: data conversion performed by the stream objects being part of the stream
25: pipe.
26: <P>
27: It is not <I>required</I> that a stream has a target, it might as well be
28: a black hole that just accepts data without ever giving it out again. The
29: generic stream class is subclassed multiple places in the Library and a good
30: example is the <A HREF="HTStruct.html">structured stream definition</A> which
31: creates a SGML object.
32: <P>
33: All stream class methods return an integer status code telling whether the
34: operation succeeded or not.. This is the way for a stream to pass control
35: information upstream to the caller which may also be a stream. The general
36: return codes from the methods are:
37: <P>
2.11 frystyk 38: <UL>
2.22 frystyk 39: <LI>
40: <B>HT_WOULD_BLOCK</B>
41: <LI>
42: <B>HT_ERROR</B>
43: <LI>
44: <B>HT_OK</B>
45: <LI>
46: <B>>0</B> - any return greater than 0 will result in that the return code
47: will be parsed through all stream objects. This can be used to pass back
48: information to the <A HREF="HTProt.html">protocol modules</A>, for example
2.11 frystyk 49: </UL>
2.22 frystyk 50: <P>
51: It is in general not relevant to return how much data has been written in
52: the stream, as there often will be a relationship other than 1:1 between
53: indata and outdata. However, it is important that a stream keeps state (either
54: on the incoming data or the outgoing data stream) so that it can accept a
55: <CODE>HT_WOULD_BLOCK</CODE> and continue at a later time when the blocking
2.11 frystyk 56: situation has stopped.
2.22 frystyk 57: <P>
58: This module is implemented by <A HREF="HTStream.c">HTStream.c</A>, and it
2.24 frystyk 59: is a part of the <A HREF="http://www.w3.org/Library/">W3C Sample Code
2.22 frystyk 60: Library</A>.
2.8 frystyk 61: <PRE>
62: #ifndef HTSTREAM_H
2.1 timbl 63: #define HTSTREAM_H
64:
2.18 frystyk 65: #include "HTList.h"
66:
2.25 ! vbancrof 67: #ifdef __cplusplus
! 68: extern "C" {
! 69: #endif
! 70:
2.11 frystyk 71: typedef struct _HTStream HTStream;
72:
73: typedef struct _HTStreamClass {
2.1 timbl 74:
2.11 frystyk 75: char * name;
76: </PRE>
2.22 frystyk 77: <P>
2.11 frystyk 78: This field is for diagnostics only
79: <PRE>
2.17 frystyk 80: int (*flush) (HTStream * me);
2.11 frystyk 81: </PRE>
2.22 frystyk 82: <P>
83: The <B>flush</B> method is introduced in order to allow the stream to put
84: any buffered data down the stream pipe but without taking the stream pipe
85: down. It is for the stream to decide whether it has buffered data or not.
86: In some situations, the stream might not want to send buffered data down
87: the target as the date might be relevant for this stream only.
2.11 frystyk 88: <PRE>
2.17 frystyk 89: int (*_free) (HTStream * me);
2.11 frystyk 90: </PRE>
2.22 frystyk 91: <P>
92: The <B>free</B> method is like the <CODE>flush</CODE> method but it also
93: frees the current stream object and all stream objects down stream. When
94: the <CODE>free</CODE> method has been called, the <EM>whole</EM> stream pipe
95: (not only this obejct) should not accept any more data.
2.11 frystyk 96: <PRE>
2.18 frystyk 97: int (*abort) (HTStream * me, HTList * errorlist);
2.11 frystyk 98: </PRE>
2.22 frystyk 99: <P>
100: The <B>abort</B> method should only be used if a stream is interrupted, for
101: example by the user, or an error occurs.
2.11 frystyk 102: <PRE>
2.17 frystyk 103: int (*put_character)(HTStream * me, char ch);
2.1 timbl 104:
2.19 frystyk 105: int (*put_string) (HTStream * me, const char * str);
2.11 frystyk 106:
2.19 frystyk 107: int (*put_block) (HTStream * me, const char * str, int len);
2.11 frystyk 108: </PRE>
2.22 frystyk 109: <P>
110: These methods are for actually putting data down the stream. It is important
111: that the most efficient method is chosen (often put_block). There is no guarantee
112: that a stream won't change method, for example from
113: <CODE>put_character</CODE> to <CODE>put_block</CODE>
2.11 frystyk 114: <PRE>
2.7 frystyk 115: } HTStreamClass;
2.21 frystyk 116: </PRE>
2.22 frystyk 117: <P>
118: <A NAME="utils"></A>
119: <H2>
120: Basic Utility Streams
121: </H2>
122: <P>
2.21 frystyk 123: These streams can be plugged in everywhere in a stream pipe.
2.22 frystyk 124: <H3>
125: Black Hole Stream
126: </H3>
127: <P>
2.21 frystyk 128: This stream simply absorbs data without doing anything what so ever.
129: <PRE>
130: extern HTStream * HTBlackHole (void);
2.11 frystyk 131: </PRE>
2.22 frystyk 132: <H3>
133: Generic Error Stream
134: </H3>
135: <P>
136: The Error stream simply returns <CODE>HT_ERROR</CODE> on all methods. This
137: can be used to stop a stream as soon as data arrives, for example from the
2.21 frystyk 138: network.
139: <PRE>
140: extern HTStream * HTErrorStream (void);
141: </PRE>
142: <PRE>
2.25 ! vbancrof 143: #ifdef __cplusplus
! 144: }
! 145: #endif
! 146:
2.21 frystyk 147: #endif /* HTSTREAM_H */
148: </PRE>
2.22 frystyk 149: <P>
150: <HR>
2.21 frystyk 151: <ADDRESS>
2.25 ! vbancrof 152: @(#) $Id: HTStream.html,v 2.24 1998/05/14 02:11:05 frystyk Exp $
2.21 frystyk 153: </ADDRESS>
2.22 frystyk 154: </BODY></HTML>
Webmaster
![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to HTStream.html CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [Public] / libwww / Library / src