/******************************************/
/* bytestream.h 0.2.0 (1999-Nov-13-Sat)   */
/* Adam M. Costello <amc@cs.berkeley.edu> */
/******************************************/

/* Interfaces for the source and sink of */
/* a flow-controlled stream of bytes.    */

/* This is ANSI C code. */


#ifndef BYTESTREAM_H
#define BYTESTREAM_H

#include <stddef.h>


typedef void bytestream_go_ahead_method(void *source, void *sink);

    /* A bytestream_go_ahead_method is a function of the form         */
    /* go_ahead(source,sink).  The source and sink parameters must    */
    /* be unique identifiers for the source and sink, and presumably  */
    /* they point to the internal state of the source and sink.       */
    /* The sink calls this function, and the source implements it.    */
    /* Whenever the sink returns from its transfer method without     */
    /* reading the entire buffer, it must later call the source's     */
    /* go-ahead method after it becomes able to accept more data.  It */
    /* is not forbidden from calling the go-ahead method at other     */
    /* times, but doing so is not useful.  The source must not call   */
    /* the sink's transfer method from within the go-ahead method.    */
    /* Although it may be tempting to do so, the source must instead  */
    /* set a timer (to expire right now perhaps), and that timer      */
    /* handler can transfer the data.  This is slightly burdensome    */
    /* for the author of the source, but makes life much simpler for  */
    /* the author of the sink.                                        */


typedef size_t bytestream_transfer_method(
  void *sink,
  void *source,
  const unsigned char *buffer,
  size_t length );

    /* A bytestream_transfer_method is a function of the form         */
    /* transfer(sink,source,buffer,length).  The source and sink      */
    /* parameters must be unique identifiers for the source and       */
    /* sink, and presumably they point to the internal state of the   */
    /* source and sink.  The source calls this function, and the sink */
    /* implements it.  Notice that the order of the source and sink   */
    /* parameters is opposite for the go-ahead and transfer methods.  */
    /* The convention is that the callee comes first.  The transfer   */
    /* method must read between 0 and length bytes (inclusive) from   */
    /* the buffer, then return the number of bytes read.  If the      */
    /* return value is less than length, that means the sink cannot   */
    /* handle any more data right now, so the source will be wasting  */
    /* its time if it calls the function again before its go-ahead    */
    /* method has been called (though it is not forbidden from doing  */
    /* so).  The sink must not call the source's go-ahead method from */
    /* within the transfer method (not that it would have any reason  */
    /* to).                                                           */


#endif /* BYTESTREAM_H */