Annotation of libwww/Library/src/HTStream.html, revision 2.16
2.4 timbl 1: <HTML>
2: <HEAD>
2.8 frystyk 3: <TITLE>The Generic Stream Class Definition</TITLE>
2.16 ! frystyk 4: <!-- Changed by: Henrik Frystyk Nielsen, 9-Sep-1995 -->
2.8 frystyk 5: </HEAD>
2.1 timbl 6: <BODY>
2.8 frystyk 7:
2.7 frystyk 8: <H1>Stream Object definition</H1>
9:
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>
16:
17: A Stream object is something which accepts a stream of text. See also
2.11 frystyk 18: the <A HREF="HTStruct.html">Structured stream
19: definition.</A>. Generally streams are cascaded into stream pipes
20: where the output of a stream is directed into the input of the down
21: stream object. However, it is not required that a stream has a target,
22: it might as well be a black hole that just swallows data. <P>
2.8 frystyk 23:
24: The creation methods will vary on the type of Stream Object. All
2.11 frystyk 25: creation methods return a pointer to the stream object below.<P>
26:
27: This module is a part of the <A
2.15 frystyk 28: HREF="http://www.w3.org/pub/WWW/Library/">
2.13 frystyk 29: W3C Reference Library</A>.
2.8 frystyk 30:
2.11 frystyk 31: <B>NOTE: </B>All methods in the stream definition do now return an
32: integer. The general return codes from the methods are:
33:
34: <UL>
2.14 frystyk 35: <LI><B>HT_WOULD_BLOCK</B>
36: <LI><B>HT_ERROR</B>
37: <LI><B>HT_OK</B>
38: <LI><B>>0</B> - any return greater than 0 will result in that the
39: return code will be parsed on from the <A
40: HREF="HTSocket.html#Read">HTSocketRead</A>. This can be used by
41: inidividual stream to introduce their own return codes.
2.11 frystyk 42: </UL>
43:
44: As streams now have a return value, it is <B>very</B> important that
45: these return values are passed upstream to all the other streams in
46: the stream pipe. <P>
47:
48: It is not relevant to return how much data has been written in the
49: stream, as there often will be a relationship other than 1:1 between
50: indata and outdata. However, it is important that a stream keeps state
51: (eitheron the indata or the outdata) so that it can accept a
52: HT_WOULD_BLOCK and continue at a later time when the blocking
53: situation has stopped.
54:
2.8 frystyk 55: <PRE>
56: #ifndef HTSTREAM_H
2.1 timbl 57: #define HTSTREAM_H
58:
2.11 frystyk 59: typedef struct _HTStream HTStream;
60:
61: typedef struct _HTStreamClass {
2.1 timbl 62:
2.11 frystyk 63: char * name;
64: </PRE>
65:
66: This field is for diagnostics only
67:
68: <PRE>
69: int (*flush) PARAMS((HTStream * me));
70: </PRE>
2.1 timbl 71:
2.11 frystyk 72: The <CODE>flush</CODE> method is introduced in order to allow the
73: stream to put any buffered data down the stream pipe but without
74: taking the stream pipe down. It is for the stream to decide whether it
75: has buffered data or not. In some situations, the stream might not
76: want to send buffered data down the target as the date might be
77: relevant for this stream only.
2.7 frystyk 78:
2.11 frystyk 79: <PRE>
80: int (*_free) PARAMS((HTStream * me));
81: </PRE>
2.7 frystyk 82:
2.11 frystyk 83: The <CODE>free</CODE> method is like the <CODE>flush</CODE> method but
84: it also frees the current stream object and all stream objects down
85: stream. When the <CODE>free</CODE> method has been called, the
86: <EM>whole</EM> stream pipe (not only this obejct) should not accept
87: any more data.
2.7 frystyk 88:
2.11 frystyk 89: <PRE>
90: int (*abort) PARAMS((HTStream * me, HTError e));
91: </PRE>
2.1 timbl 92:
2.11 frystyk 93: The <CODE>abort</CODE> method should only be used if a stream is
94: interrupted, for example by the user, or an error occurs.
2.1 timbl 95:
2.11 frystyk 96: <PRE>
97: int (*put_character) PARAMS((HTStream * me,
98: char ch));
2.1 timbl 99:
2.11 frystyk 100: int (*put_string) PARAMS((HTStream * me,
101: CONST char * str));
102:
103: int (*put_block) PARAMS((HTStream * me,
104: CONST char * str,
105: int len));
106: </PRE>
107:
108: These methods are for actually putting data down the stream. It is
109: important that the most efficient method is chosen (often
110: put_block). There is no guarantee that a stream won't change method,
111: for example from <CODE>put_character</CODE> to <CODE>put_block</CODE>
112:
113: <PRE>
2.7 frystyk 114: } HTStreamClass;
2.1 timbl 115:
116: #endif /* HTSTREAM_H */
117:
2.11 frystyk 118: </PRE>
119:
120: End of HTStream definition
121: </BODY>
2.4 timbl 122: </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