/* -*- Mode: C -*- */
/* stream.h --- customizable stream routines
* Copyright (C) 1998, 1999, 2000, 2002 Gary V. Vaughan
* Originally by Gary V. Vaughan, 1998
* This file is part of Snprintfv
*
* Snprintfv is free software; you can redistribute it and/or
* modify it under the terms of the GNU General Public License as
* published by the Free Software Foundation; either version 2 of the
* License, or (at your option) any later version.
*
* Snprintfv program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program. If not, see <http://www.gnu.org/licenses>.
*
* As a special exception to the GNU General Public License, if you
* distribute this file as part of a program that also links with and
* uses the libopts library from AutoGen, you may include it under
* the same distribution terms used by the libopts library.
*/
/* Code: */
#ifndef STREAM_H
#define STREAM_H 1
#define STREAM_READABLE (1 << 0)
#define STREAM_WRITABLE (1 << 1)
/**
* SNV_UNLIMITED:
* Used to denote that there is no upper limit to the number of characters
* that can safely be written to a stream.
**/
#define SNV_UNLIMITED (~0UL)
#ifdef __cplusplus
extern "C"
{
#if 0
/* This brace is so that emacs can still indent properly: */ }
#endif
#endif /* __cplusplus */
/**
* STREAM:
* Data type used to pass details of streams between functions,
* much like stdio's %FILE, but more flexible. A %STREAM can be uni- or
* bi-directional depending on how it is initialised.
**/
typedef struct stream STREAM;
/**
* StreamPut:
* @ch: The character to write to @stream cast to an int.
* @stream: The stream being written to.
*
* Type of the function to put a character in a writeable stream.
*
* Return value:
* The function should return the character written to the
* stream, cast to an int if it was written successfully, or
* else %EOF, if the write failed.
**/
typedef int (*StreamPut) (int ch, STREAM * stream);
/**
* StreamGet:
* @stream: The stream being read from.
*
* Type of the function to get a character from a readable stream.
*
* Return value:
* The function should return the character read from the
* stream, cast to an int if it was read successfully, or
* else %EOF, if the read failed.
**/
typedef int (*StreamGet) (STREAM * stream);
/**
* stream_new: constructor
* @dets: user supplied stream details to be passed into the various funcs.
* @limit: the maximum number of consecutive bytes to fit in @dets.
* @get_func: function to get a character from @dets stream.
* @put_func: function to put a character in @dets stream.
*
* Allocate and initialize a new %STREAM data type. The @get_func
* and @put_func can be NULL if you intend to create a non-readable
* or non-writable stream, respectively.
*
* Return value:
* The address of the newly allocated and initialised stream is returned.
**/
extern STREAM *
stream_new (snv_pointer dets, unsigned long limit, StreamGet get_func, StreamPut put_func);
/**
* stream_delete: destructor
* @stream: The stream pending deletion
*
* The memory associated with @stream is recycled.
* Return value:
* The %dets supplied by the user when the stream was created are
* returned for handling by the calling function.
**/
extern snv_pointer
stream_delete (STREAM *stream);
/**
* stream_details:
* @stream: the stream being queried.
*
* The finalization function specified when @stream was created (if any)
* is called, and then the memory associated with @stream is recycled.
* It is the responsibility of the finalization function to recycle, or
* otherwise manage, any memory associated with the user supplied %dets.
* Return value:
* This function returns the stream details associated with @stream
* when it was originally created.
**/
extern snv_pointer
stream_details (STREAM *stream);
/**
* stream_put:
* @ch: A single character to be placed in @stream.
* @stream: The stream to be written to.
*
* This function will @ch in @stream if that stream's output limit will
* not be exceeded.
*
* Return value:
* If @stream is full, return 1. Otherwise, if any other error occurs,
* that error code is returned unchanged. This is of course dependant
* on what the handler function uses to indicate an error. If the stream
* is not full and the stream's writing function succeeds, 1 (the number of
* characters emitted!) is returned.
**/
extern int
stream_put (int ch, STREAM *stream);
/**
* stream_puts:
* @s: A string to be placed in @stream.
* @stream: The stream to be written to.
*
* This function will @ch in @stream if that stream's output limit will
* not be exceeded.
*
* Return value:
* If any other error occurs, that error code is returned unchanged.
* This is of course dependant on what the handler function uses to
* indicate an error. If the stream becomes full, the remaining
* characters are not printed. If the stream's writing function
* always succeeds, the number of characters emitted or skipped is
* returned.
**/
extern int
stream_puts (char *s, STREAM *stream);
/**
* stream_get:
* @stream: The stream to be read from.
*
* This function will try to read a single character from @stream.
*
* Return value:
* If an error occurs or the end of @stream is reached, -1 is returned.
* Under normal circumstances the value if the character read (cast to
* an int) is returned.
**/
extern int
stream_get (STREAM *stream);
#line 87 "stream.in"
#ifdef __cplusplus
#if 0
/* This brace is so that emacs can still indent properly: */
{
#endif
}
#endif /* __cplusplus */
#endif /* STREAM_H */