/*
* Copyright (c) 2001-2002 Packet Design, LLC.
* All rights reserved.
*
* Subject to the following obligations and disclaimer of warranty,
* use and redistribution of this software, in source or object code
* forms, with or without modifications are expressly permitted by
* Packet Design; provided, however, that:
*
* (i) Any and all reproductions of the source or object code
* must include the copyright notice above and the following
* disclaimer of warranties; and
* (ii) No rights are granted, in any manner or form, to use
* Packet Design trademarks, including the mark "PACKET DESIGN"
* on advertising, endorsements, or otherwise except as such
* appears in the above copyright notice or in the software.
*
* THIS SOFTWARE IS BEING PROVIDED BY PACKET DESIGN "AS IS", AND
* TO THE MAXIMUM EXTENT PERMITTED BY LAW, PACKET DESIGN MAKES NO
* REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, REGARDING
* THIS SOFTWARE, INCLUDING WITHOUT LIMITATION, ANY AND ALL IMPLIED
* WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE,
* OR NON-INFRINGEMENT. PACKET DESIGN DOES NOT WARRANT, GUARANTEE,
* OR MAKE ANY REPRESENTATIONS REGARDING THE USE OF, OR THE RESULTS
* OF THE USE OF THIS SOFTWARE IN TERMS OF ITS CORRECTNESS, ACCURACY,
* RELIABILITY OR OTHERWISE. IN NO EVENT SHALL PACKET DESIGN BE
* LIABLE FOR ANY DAMAGES RESULTING FROM OR ARISING OUT OF ANY USE
* OF THIS SOFTWARE, INCLUDING WITHOUT LIMITATION, ANY DIRECT,
* INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, PUNITIVE, OR CONSEQUENTIAL
* DAMAGES, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES, LOSS OF
* USE, DATA OR PROFITS, HOWEVER CAUSED AND UNDER ANY THEORY OF
* LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
* (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF
* THE USE OF THIS SOFTWARE, EVEN IF PACKET DESIGN IS ADVISED OF
* THE POSSIBILITY OF SUCH DAMAGE.
*
* Author: Archie Cobbs <archie@freebsd.org>
*/
#ifndef _PDEL_IO_FILTER_H_
#define _PDEL_IO_FILTER_H_
/*
* Filters
*
* A filter is an object that has an input side and an output side
* and performs some kind of encoding on the data as it passes through.
*
* Filters are useful because they can be pushed on top of a FILE *
* stream in order to encode or decode data.
*/
struct filter;
/***********************************************************************
FILTER METHODS
***********************************************************************/
/*
* Read up to 'len' bytes from a filter.
*
* Returns the number of bytes read, or -1 and sets errno on error.
* Returns zero if the filter is empty and needs more data to be written in.
*/
typedef int filter_read_t(struct filter *f, void *buf, int len);
/*
* Write up to 'len' bytes into a filter.
*
* Returns the number of bytes written, or -1 and sets errno on error.
* Returns zero if the filter is full and needs more data to be read out.
*/
typedef int filter_write_t(struct filter *f, const void *data, int len);
/*
* Indicate to a filter that no more data is to be written.
*
* Returns zero if successful, or -1 and sets errno on error.
* Once this is called, the write method will return -1 and errno = EPIPE.
*/
typedef int filter_end_t(struct filter *f);
/*
* Convert the number of bytes of input vs. output.
*
* If 'forward' is true, this should return an upper bound on the
* number of bytes of that 'num' bytes of input will generate.
* Otherwise, this should return an upper bound on the number of bytes
* of input that would be required to generate 'num' (or more) bytes
* of output.
*/
typedef int filter_convert_t(struct filter *f, int num, int forward);
/*
* Destroy a filter.
*
* This method must do two things:
* (a) Free all resources associated with the filter *fp
* (b) Set *fp to NULL
*
* If *fp is already equal to NULL, this method must do nothing.
*/
typedef void filter_destroy_t(struct filter **fp);
/***********************************************************************
FILTER STRUCTURE
***********************************************************************/
/* Filter object structure */
struct filter {
filter_read_t *read; /* read data out of filter */
filter_write_t *write; /* write data into filter */
filter_end_t *end; /* signal end of data */
filter_convert_t *convert; /* map # bytes in <-> out */
filter_destroy_t *destroy; /* destroy filter */
void *private; /* object private data */
};
/***********************************************************************
FILTER LIBRARY ROUTINES
***********************************************************************/
__BEGIN_DECLS
#ifndef _KERNEL
/*
* Given a read-only or write-only stream, return another stream
* that reads or writes data from the supplied stream using
* the filter. In other words, in the returned stream, the filter
* is sitting on top of the supplied stream.
*
* When the stream is closed, the underlying stream is closed unless
* the FILTER_NO_CLOSE_STREAM flag was given, and the filter is destroyed
* unless the FILTER_NO_DESTROY_FILTER flags was given.
*
* Returns NULL and sets errno on error.
*/
#define FILTER_NO_CLOSE_STREAM 0x01 /* fclose() doesn't close fp */
#define FILTER_NO_DESTROY_FILTER 0x02 /* fclose() doesn't rm filter */
extern FILE *filter_fopen(struct filter *filter, int flags,
FILE *fp, const char *mode);
#endif /* !_KERNEL */
/*
* Filter data in memory using a filter.
*
* The filtered data is in *outputp and the length of the data is returned.
* *outputp is guaranteed to have one extra byte allocated and set to zero.
* If 'final' is non-zero then the write side of the filter is closed.
*
* Returns -1 and sets errno on error.
*/
extern int filter_process(struct filter *filter, const void *input,
int len, int final, u_char **outputp,
const char *mtype);
/*
* Wrappers for the filter methods.
*/
extern filter_read_t filter_read;
extern filter_write_t filter_write;
extern filter_end_t filter_end;
extern filter_convert_t filter_convert;
extern filter_destroy_t filter_destroy;
__END_DECLS
#endif /* _PDEL_IO_FILTER_H_ */
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>