Annotation of embedaddon/libpdel/io/filter.h, revision 1.1.1.1
1.1 misho 1:
2: /*
3: * Copyright (c) 2001-2002 Packet Design, LLC.
4: * All rights reserved.
5: *
6: * Subject to the following obligations and disclaimer of warranty,
7: * use and redistribution of this software, in source or object code
8: * forms, with or without modifications are expressly permitted by
9: * Packet Design; provided, however, that:
10: *
11: * (i) Any and all reproductions of the source or object code
12: * must include the copyright notice above and the following
13: * disclaimer of warranties; and
14: * (ii) No rights are granted, in any manner or form, to use
15: * Packet Design trademarks, including the mark "PACKET DESIGN"
16: * on advertising, endorsements, or otherwise except as such
17: * appears in the above copyright notice or in the software.
18: *
19: * THIS SOFTWARE IS BEING PROVIDED BY PACKET DESIGN "AS IS", AND
20: * TO THE MAXIMUM EXTENT PERMITTED BY LAW, PACKET DESIGN MAKES NO
21: * REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, REGARDING
22: * THIS SOFTWARE, INCLUDING WITHOUT LIMITATION, ANY AND ALL IMPLIED
23: * WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE,
24: * OR NON-INFRINGEMENT. PACKET DESIGN DOES NOT WARRANT, GUARANTEE,
25: * OR MAKE ANY REPRESENTATIONS REGARDING THE USE OF, OR THE RESULTS
26: * OF THE USE OF THIS SOFTWARE IN TERMS OF ITS CORRECTNESS, ACCURACY,
27: * RELIABILITY OR OTHERWISE. IN NO EVENT SHALL PACKET DESIGN BE
28: * LIABLE FOR ANY DAMAGES RESULTING FROM OR ARISING OUT OF ANY USE
29: * OF THIS SOFTWARE, INCLUDING WITHOUT LIMITATION, ANY DIRECT,
30: * INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, PUNITIVE, OR CONSEQUENTIAL
31: * DAMAGES, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES, LOSS OF
32: * USE, DATA OR PROFITS, HOWEVER CAUSED AND UNDER ANY THEORY OF
33: * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
34: * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF
35: * THE USE OF THIS SOFTWARE, EVEN IF PACKET DESIGN IS ADVISED OF
36: * THE POSSIBILITY OF SUCH DAMAGE.
37: *
38: * Author: Archie Cobbs <archie@freebsd.org>
39: */
40:
41: #ifndef _PDEL_IO_FILTER_H_
42: #define _PDEL_IO_FILTER_H_
43:
44: /*
45: * Filters
46: *
47: * A filter is an object that has an input side and an output side
48: * and performs some kind of encoding on the data as it passes through.
49: *
50: * Filters are useful because they can be pushed on top of a FILE *
51: * stream in order to encode or decode data.
52: */
53:
54: struct filter;
55:
56: /***********************************************************************
57: FILTER METHODS
58: ***********************************************************************/
59:
60: /*
61: * Read up to 'len' bytes from a filter.
62: *
63: * Returns the number of bytes read, or -1 and sets errno on error.
64: * Returns zero if the filter is empty and needs more data to be written in.
65: */
66: typedef int filter_read_t(struct filter *f, void *buf, int len);
67:
68: /*
69: * Write up to 'len' bytes into a filter.
70: *
71: * Returns the number of bytes written, or -1 and sets errno on error.
72: * Returns zero if the filter is full and needs more data to be read out.
73: */
74: typedef int filter_write_t(struct filter *f, const void *data, int len);
75:
76: /*
77: * Indicate to a filter that no more data is to be written.
78: *
79: * Returns zero if successful, or -1 and sets errno on error.
80: * Once this is called, the write method will return -1 and errno = EPIPE.
81: */
82: typedef int filter_end_t(struct filter *f);
83:
84: /*
85: * Convert the number of bytes of input vs. output.
86: *
87: * If 'forward' is true, this should return an upper bound on the
88: * number of bytes of that 'num' bytes of input will generate.
89: * Otherwise, this should return an upper bound on the number of bytes
90: * of input that would be required to generate 'num' (or more) bytes
91: * of output.
92: */
93: typedef int filter_convert_t(struct filter *f, int num, int forward);
94:
95: /*
96: * Destroy a filter.
97: *
98: * This method must do two things:
99: * (a) Free all resources associated with the filter *fp
100: * (b) Set *fp to NULL
101: *
102: * If *fp is already equal to NULL, this method must do nothing.
103: */
104: typedef void filter_destroy_t(struct filter **fp);
105:
106: /***********************************************************************
107: FILTER STRUCTURE
108: ***********************************************************************/
109:
110: /* Filter object structure */
111: struct filter {
112: filter_read_t *read; /* read data out of filter */
113: filter_write_t *write; /* write data into filter */
114: filter_end_t *end; /* signal end of data */
115: filter_convert_t *convert; /* map # bytes in <-> out */
116: filter_destroy_t *destroy; /* destroy filter */
117: void *private; /* object private data */
118: };
119:
120: /***********************************************************************
121: FILTER LIBRARY ROUTINES
122: ***********************************************************************/
123:
124: __BEGIN_DECLS
125:
126: #ifndef _KERNEL
127:
128: /*
129: * Given a read-only or write-only stream, return another stream
130: * that reads or writes data from the supplied stream using
131: * the filter. In other words, in the returned stream, the filter
132: * is sitting on top of the supplied stream.
133: *
134: * When the stream is closed, the underlying stream is closed unless
135: * the FILTER_NO_CLOSE_STREAM flag was given, and the filter is destroyed
136: * unless the FILTER_NO_DESTROY_FILTER flags was given.
137: *
138: * Returns NULL and sets errno on error.
139: */
140: #define FILTER_NO_CLOSE_STREAM 0x01 /* fclose() doesn't close fp */
141: #define FILTER_NO_DESTROY_FILTER 0x02 /* fclose() doesn't rm filter */
142:
143: extern FILE *filter_fopen(struct filter *filter, int flags,
144: FILE *fp, const char *mode);
145:
146: #endif /* !_KERNEL */
147:
148: /*
149: * Filter data in memory using a filter.
150: *
151: * The filtered data is in *outputp and the length of the data is returned.
152: * *outputp is guaranteed to have one extra byte allocated and set to zero.
153: * If 'final' is non-zero then the write side of the filter is closed.
154: *
155: * Returns -1 and sets errno on error.
156: */
157: extern int filter_process(struct filter *filter, const void *input,
158: int len, int final, u_char **outputp,
159: const char *mtype);
160:
161: /*
162: * Wrappers for the filter methods.
163: */
164: extern filter_read_t filter_read;
165: extern filter_write_t filter_write;
166: extern filter_end_t filter_end;
167: extern filter_convert_t filter_convert;
168: extern filter_destroy_t filter_destroy;
169:
170: __END_DECLS
171:
172: #endif /* _PDEL_IO_FILTER_H_ */
173:
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>