Annotation of libwww/Library/src/HTStream.html, revision 2.19
2.4 timbl 1: <HTML>
2: <HEAD>
2.8 frystyk 3: <TITLE>The Generic Stream Class Definition</TITLE>
2.18 frystyk 4: <!-- Changed by: Henrik Frystyk Nielsen, 7-Nov-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.18 frystyk 59: #include "HTList.h"
60:
2.11 frystyk 61: typedef struct _HTStream HTStream;
62:
63: typedef struct _HTStreamClass {
2.1 timbl 64:
2.11 frystyk 65: char * name;
66: </PRE>
67:
68: This field is for diagnostics only
69:
70: <PRE>
2.17 frystyk 71: int (*flush) (HTStream * me);
2.11 frystyk 72: </PRE>
2.1 timbl 73:
2.11 frystyk 74: The <CODE>flush</CODE> method is introduced in order to allow the
75: stream to put any buffered data down the stream pipe but without
76: taking the stream pipe down. It is for the stream to decide whether it
77: has buffered data or not. In some situations, the stream might not
78: want to send buffered data down the target as the date might be
79: relevant for this stream only.
2.7 frystyk 80:
2.11 frystyk 81: <PRE>
2.17 frystyk 82: int (*_free) (HTStream * me);
2.11 frystyk 83: </PRE>
2.7 frystyk 84:
2.11 frystyk 85: The <CODE>free</CODE> method is like the <CODE>flush</CODE> method but
86: it also frees the current stream object and all stream objects down
87: stream. When the <CODE>free</CODE> method has been called, the
88: <EM>whole</EM> stream pipe (not only this obejct) should not accept
89: any more data.
2.7 frystyk 90:
2.11 frystyk 91: <PRE>
2.18 frystyk 92: int (*abort) (HTStream * me, HTList * errorlist);
2.11 frystyk 93: </PRE>
2.1 timbl 94:
2.11 frystyk 95: The <CODE>abort</CODE> method should only be used if a stream is
96: interrupted, for example by the user, or an error occurs.
2.1 timbl 97:
2.11 frystyk 98: <PRE>
2.17 frystyk 99: int (*put_character)(HTStream * me, char ch);
2.1 timbl 100:
2.19 ! frystyk 101: int (*put_string) (HTStream * me, const char * str);
2.11 frystyk 102:
2.19 ! frystyk 103: int (*put_block) (HTStream * me, const char * str, int len);
2.11 frystyk 104: </PRE>
105:
106: These methods are for actually putting data down the stream. It is
107: important that the most efficient method is chosen (often
108: put_block). There is no guarantee that a stream won't change method,
109: for example from <CODE>put_character</CODE> to <CODE>put_block</CODE>
110:
111: <PRE>
2.7 frystyk 112: } HTStreamClass;
2.1 timbl 113:
114: #endif /* HTSTREAM_H */
115:
2.11 frystyk 116: </PRE>
117:
118: End of HTStream definition
119: </BODY>
2.4 timbl 120: </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