[BACK]Return to HTStream.html CVS log [TXT] [DIR] Up to [Public] / libwww / Library / src
File:  [Public] / libwww / Library / src / HTStream.html
Revision 2.24: download - view: text, annotated - select for diffs
Thu May 14 02:11:05 1998 UTC (26 years ago) by frystyk
Branches: MAIN
CVS tags: repeat-requests, before_webdav, Release-5-4-0, Release-5-3-1, Release-5-2-8, Release-5-2-6, Release-5-2, Release-5-1m, HEAD, Before-New-Trace-Messages, Amaya_2_4, Amaya-6-3, Amaya-6-1, Amaya-5-2, Amaya-4-3-2, Amaya-4-3-1, Amaya-4-3, Amaya-4-1-2, Amaya-4-1-0, Amaya-4-0-0, Amaya-3-2-1, Amaya-3-2, Amaya
Changing old pub/WWW links

<HTML>
<HEAD>
  <!-- Changed by: Henrik Frystyk Nielsen, 25-Mar-1996 -->
  <TITLE>W3C Sample Code Library libwww Generic Stream Class</TITLE>
</HEAD>
<BODY>
<H1>
  Generic Stream Class
</H1>
<PRE>
/*
**	(c) COPYRIGHT MIT 1995.
**	Please first read the full copyright statement in the file COPYRIGH.
*/
</PRE>
<P>
The Stream class defines objects which accepts a sequence of characters.
Streams may also have an output in which case multiple stream objects can
be cascaded to build a stream pipe where the output of a stream is directed
into the input of the next stream object "down the line". Of course, one
of the main features of streams is that they can perform a <I>data conversion
</I>on the data before piping it to the output. As multiple streams may be
cascaded, the complete data conversion is then the sum of each individual
data conversion performed by the stream objects being part of the stream
pipe.
<P>
It is not <I>required</I> that a stream has a target, it might as well be
a black hole that just accepts data without ever giving it out again. The
generic stream class is subclassed multiple places in the Library and a good
example is the <A HREF="HTStruct.html">structured stream definition</A> which
creates a SGML object.
<P>
All stream class methods return an integer status code telling whether the
operation succeeded or not.. This is the way for a stream to pass control
information upstream to the caller which may also be a stream. The general
return codes from the methods are:
<P>
<UL>
  <LI>
    <B>HT_WOULD_BLOCK</B>
  <LI>
    <B>HT_ERROR</B>
  <LI>
    <B>HT_OK</B>
  <LI>
    <B>&gt;0</B> - any return greater than 0 will result in that the return code
    will be parsed through all stream objects. This can be used to pass back
    information to the <A HREF="HTProt.html">protocol modules</A>, for example
</UL>
<P>
It is in general not relevant to return how much data has been written in
the stream, as there often will be a relationship other than 1:1 between
indata and outdata. However, it is important that a stream keeps state (either
on the incoming data or the outgoing data stream) so that it can accept a
<CODE>HT_WOULD_BLOCK</CODE> and continue at a later time when the blocking
situation has stopped.
<P>
This module is implemented by <A HREF="HTStream.c">HTStream.c</A>, and it
is a part of the <A HREF="http://www.w3.org/Library/">W3C Sample Code
Library</A>.
<PRE>
#ifndef HTSTREAM_H
#define HTSTREAM_H

#include "HTList.h"

typedef struct _HTStream HTStream;

typedef struct _HTStreamClass {

    char * name;
</PRE>
<P>
This field is for diagnostics only
<PRE>
    int (*flush)	(HTStream * 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)	(HTStream * me);
</PRE>
<P>
The <B>free</B> 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 obejct) should not accept any more data.
<PRE>
    int (*abort)	(HTStream * 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 (*put_character)(HTStream * me, char ch);
				
    int (*put_string)	(HTStream * me, const char * str);

    int (*put_block)	(HTStream * me, const char * str, int len);
</PRE>
<P>
These methods are for actually putting data down the stream. It is important
that the most efficient method is chosen (often put_block). There is no guarantee
that a stream won't change method, for example from
<CODE>put_character</CODE> to <CODE>put_block</CODE>
<PRE>
} HTStreamClass;
</PRE>
<P>
<A NAME="utils"></A>
<H2>
  Basic Utility Streams
</H2>
<P>
These streams can be plugged in everywhere in a stream pipe.
<H3>
  Black Hole Stream
</H3>
<P>
This stream simply absorbs data without doing anything what so ever.
<PRE>
extern HTStream * HTBlackHole (void);
</PRE>
<H3>
  Generic Error Stream
</H3>
<P>
The Error stream simply returns <CODE>HT_ERROR</CODE> on all methods. This
can be used to stop a stream as soon as data arrives, for example from the
network.
<PRE>
extern HTStream * HTErrorStream (void);
</PRE>
<PRE>
#endif /* HTSTREAM_H */
</PRE>
<P>
  <HR>
<ADDRESS>
  @(#) $Id: HTStream.html,v 2.24 1998/05/14 02:11:05 frystyk Exp $
</ADDRESS>
</BODY></HTML>
Webmaster