[BACK]Return to HTIOStream.html CVS log [TXT] [DIR] Up to [Public] / libwww / Library / src
File:  [Public] / libwww / Library / src / HTIOStream.html
Revision 2.4: download - view: text, annotated - select for diffs
Sun Feb 16 18:42:25 1997 UTC (27 years, 4 months ago) by frystyk
Branches: MAIN
CVS tags: Release-5-1l, Release-5-1k, Release-5-1j, Release-5-1g, Release-5-1e, Release-5-1d, Release-5-1b, Release-5-1a, Release-5-1, HEAD
Changed name of sample coed library

<HTML>
<HEAD>
  <!-- Changed by: Henrik Frystyk Nielsen,  6-Apr-1996 -->
  <TITLE>W3C Sample Code Library libwww I/O Stream Classes</TITLE>
</HEAD>
<BODY>
<H1>
  I/O Stream Classes
</H1>
<PRE>
/*
**	(c) COPYRIGHT MIT 1995.
**	Please first read the full copyright statement in the file COPYRIGH.
*/
</PRE>
<P>
The I/O Stream class defines objects which accepts a sequence of characters
to and from a <A HREF="HTTrans.html">transport</A> &nbsp;The input and output
stream are mainly derived from the <A HREF="HTStream.html">generic stream
class</A> and contains much of the same functionality. The main difference
is that the I/O streams also contains methods for reading and writing to
a transport.
<P>
This module is a part of the <A HREF="http://www.w3.org/pub/WWW/Library/">W3C
Sample Code Library</A>.
<PRE>
#ifndef HTIOSTREAM_H
#define HTIOSTREAM_H

typedef struct _HTInputStream HTInputStream;
typedef struct _HTOutputStream HTOutputStream;

#include "HTList.h"
#include "HTStream.h"
#include "HTChannl.h"
</PRE>
<H2>
  Input Stream
</H2>
<P>
An input stream is a stream that can read data from a transport and via a
<A HREF="HTChannl.html">channel</A> putting the data down to the application.
<PRE>
typedef struct _HTInputStreamClass {

    char * name;
</PRE>
<P>
This field is for diagnostics only
<PRE>
    int (*flush)	(HTInputStream * me);
</PRE>
<P>
The <B>flush</B> method is introduced in order to allow the stream to put
any buffered data down the stream pipe but without taking the stream pipe
down. It is for the stream to decide whether it has buffered data or not.
In some situations, the stream might not want to send buffered data down
the target as the date might be relevant for this stream only.
<PRE>
    int (*_free)	(HTInputStream * me);
</PRE>
<P>
The <CODE><B>free</B></CODE> method is like the <CODE>flush</CODE> method
but it also frees the current stream object and all stream objects down stream.
When the <CODE>free</CODE> method has been called, the <EM>whole</EM> stream
pipe (not only this object) should not accept any more data. See also the
<CODE>close</CODE> method below
<PRE>
    int (*abort)	(HTInputStream * me, HTList * errorlist);
</PRE>
<P>
The <B>abort</B> method should only be used if a stream is interrupted, for
example by the user, or an error occurs.
<PRE>
    int (*read)		(HTInputStream * me);
</PRE>
<P>
The <B>read</B> method is the method by which we can read data from the
<A HREF="HTTrans.html">transport layer</A>.
<PRE>
    int (*close)	(HTInputStream * me);
</PRE>
<P>
Pipelined transports need to know how many bytes were <B>consumed</B> by 
the net object.
<PRE>
    int (*consumed)	(HTInputStream * me, size_t bytes);
</PRE>
<P>
The <CODE>close</CODE> method closes the transport and deletes the input
stream object. Note that this is different than the free method which doesn't
have to delete the input stream object itself.
<PRE>
} HTInputStreamClass;
</PRE>
<H2>
  Output Stream
</H2>
<P>
The output stream is similar to the <A HREF="HTStream.html">generic stream
definition</A> in that it has a superset of methods. The <CODE>param</CODE>
parameter and the <CODE>mode</CODE> parameter can be used for whatever purpose
suited.
<PRE>
typedef struct _HTOutputStreamClass {

    char * name;

    int (*flush)	(HTOutputStream * me);

    int (*_free)	(HTOutputStream * me);

    int (*abort)	(HTOutputStream * me, HTList * errorlist);

    int (*put_character)(HTOutputStream * me, char ch);

    int (*put_string)	(HTOutputStream * me, const char * str);

    int (*put_block)	(HTOutputStream * me, const char * str, int len);
</PRE>
<P>
See the <A HREF="HTStream.html">generic Stream Definition</A> for an explanation
of these methods. Note that they all have a <CODE>HTOutputStream</CODE> object
a the parameter, not a generic stream. This is to avoid <EM>incompatible
pointer</EM> warnings
<PRE>
    int (*close)	(HTOutputStream * me);
</PRE>
<P>
The <CODE>close</CODE> method closes the transport and deletes the input
stream object. Note that this is different than the free method which doesn't
have to delete the input stream object itself.
<PRE>
} HTOutputStreamClass;
</PRE>
<H2>
  Transport Streams
</H2>
<P>
Transport streams are special streams with creation methods like defined
below. Transport streams can be registered in a
<A HREF="HTTrans.html">transport object</A> as ways of communicating with
the a transport.
<H3>
  Transport Input Stream
</H3>
<P>
We have two modes of the input stream depending on model used for data reading
is <B>PUSH</B> or <B>PULL</B>. The PUSH model is suitable if we are using
pseudo threads based on a <CODE>select()</CODE> call or equivalent and the
<B>PULL</B> is suitable in a real thread environment. In the latter case
it doesn't matter if a read procedure blocks as this only concerns a single
thread.
<PRE>
typedef HTInputStream * HTInput_new	(HTHost *	host,
					 HTChannel *	ch,
					 void *		param,
					 int		mode);
</PRE>
<H3>
  Transport Output Stream
</H3>
<PRE>
typedef HTOutputStream * HTOutput_new	(HTHost *	host,
					 HTChannel *	ch,
					 void *		param,
					 int		mode);
</PRE>
<PRE>
#endif /* HTIOSTREAM_H */
</PRE>
<P>
  <HR>
<ADDRESS>
  @(#) $Id: HTIOStream.html,v 2.4 1997/02/16 18:42:25 frystyk Exp $
</ADDRESS>
</BODY></HTML>
Webmaster