Annotation of embedaddon/php/main/streams/php_stream_filter_api.h, revision 1.1.1.4
1.1 misho 1: /*
2: +----------------------------------------------------------------------+
3: | PHP Version 5 |
4: +----------------------------------------------------------------------+
1.1.1.4 ! misho 5: | Copyright (c) 1997-2014 The PHP Group |
1.1 misho 6: +----------------------------------------------------------------------+
7: | This source file is subject to version 3.01 of the PHP license, |
8: | that is bundled with this package in the file LICENSE, and is |
9: | available through the world-wide-web at the following url: |
10: | http://www.php.net/license/3_01.txt |
11: | If you did not receive a copy of the PHP license and are unable to |
12: | obtain it through the world-wide-web, please send a note to |
13: | license@php.net so we can mail you a copy immediately. |
14: +----------------------------------------------------------------------+
15: | Author: Wez Furlong <wez@thebrainroom.com> |
16: | With suggestions from: |
17: | Moriyoshi Koizumi <moriyoshi@at.wakwak.com> |
18: | Sara Golemon <pollita@php.net> |
19: +----------------------------------------------------------------------+
20: */
21:
1.1.1.2 misho 22: /* $Id$ */
1.1 misho 23:
24: /* The filter API works on the principle of "Bucket-Brigades". This is
25: * partially inspired by the Apache 2 method of doing things, although
26: * it is intentially a light-weight implementation.
27: *
28: * Each stream can have a chain of filters for reading and another for writing.
29: *
30: * When data is written to the stream, it is placed into a bucket and placed at
31: * the start of the input brigade.
32: *
33: * The first filter in the chain is invoked on the brigade and (depending on
34: * it's return value), the next filter is invoked and so on.
35: * */
36:
37: #define PHP_STREAM_FILTER_READ 0x0001
38: #define PHP_STREAM_FILTER_WRITE 0x0002
39: #define PHP_STREAM_FILTER_ALL (PHP_STREAM_FILTER_READ | PHP_STREAM_FILTER_WRITE)
40:
41: typedef struct _php_stream_bucket php_stream_bucket;
42: typedef struct _php_stream_bucket_brigade php_stream_bucket_brigade;
43:
44: struct _php_stream_bucket {
45: php_stream_bucket *next, *prev;
46: php_stream_bucket_brigade *brigade;
47:
48: char *buf;
49: size_t buflen;
50: /* if non-zero, buf should be pefreed when the bucket is destroyed */
51: int own_buf;
52: int is_persistent;
53:
54: /* destroy this struct when refcount falls to zero */
55: int refcount;
56: };
57:
58: struct _php_stream_bucket_brigade {
59: php_stream_bucket *head, *tail;
60: };
61:
62: typedef enum {
63: PSFS_ERR_FATAL, /* error in data stream */
64: PSFS_FEED_ME, /* filter needs more data; stop processing chain until more is available */
65: PSFS_PASS_ON /* filter generated output buckets; pass them on to next in chain */
66: } php_stream_filter_status_t;
67:
68: /* Buckets API. */
69: BEGIN_EXTERN_C()
70: PHPAPI php_stream_bucket *php_stream_bucket_new(php_stream *stream, char *buf, size_t buflen, int own_buf, int buf_persistent TSRMLS_DC);
71: PHPAPI int php_stream_bucket_split(php_stream_bucket *in, php_stream_bucket **left, php_stream_bucket **right, size_t length TSRMLS_DC);
72: PHPAPI void php_stream_bucket_delref(php_stream_bucket *bucket TSRMLS_DC);
73: #define php_stream_bucket_addref(bucket) (bucket)->refcount++
74: PHPAPI void php_stream_bucket_prepend(php_stream_bucket_brigade *brigade, php_stream_bucket *bucket TSRMLS_DC);
75: PHPAPI void php_stream_bucket_append(php_stream_bucket_brigade *brigade, php_stream_bucket *bucket TSRMLS_DC);
76: PHPAPI void php_stream_bucket_unlink(php_stream_bucket *bucket TSRMLS_DC);
77: PHPAPI php_stream_bucket *php_stream_bucket_make_writeable(php_stream_bucket *bucket TSRMLS_DC);
78: END_EXTERN_C()
79:
80: #define PSFS_FLAG_NORMAL 0 /* regular read/write */
81: #define PSFS_FLAG_FLUSH_INC 1 /* an incremental flush */
82: #define PSFS_FLAG_FLUSH_CLOSE 2 /* final flush prior to closing */
83:
84: typedef struct _php_stream_filter_ops {
85:
86: php_stream_filter_status_t (*filter)(
87: php_stream *stream,
88: php_stream_filter *thisfilter,
89: php_stream_bucket_brigade *buckets_in,
90: php_stream_bucket_brigade *buckets_out,
91: size_t *bytes_consumed,
92: int flags
93: TSRMLS_DC);
94:
95: void (*dtor)(php_stream_filter *thisfilter TSRMLS_DC);
96:
97: const char *label;
98:
99: } php_stream_filter_ops;
100:
101: typedef struct _php_stream_filter_chain {
102: php_stream_filter *head, *tail;
103:
104: /* Owning stream */
105: php_stream *stream;
106: } php_stream_filter_chain;
107:
108: struct _php_stream_filter {
109: php_stream_filter_ops *fops;
110: void *abstract; /* for use by filter implementation */
111: php_stream_filter *next;
112: php_stream_filter *prev;
113: int is_persistent;
114:
115: /* link into stream and chain */
116: php_stream_filter_chain *chain;
117:
118: /* buffered buckets */
119: php_stream_bucket_brigade buffer;
120:
121: /* filters are auto_registered when they're applied */
122: int rsrc_id;
123: };
124:
125: /* stack filter onto a stream */
126: BEGIN_EXTERN_C()
127: PHPAPI void _php_stream_filter_prepend(php_stream_filter_chain *chain, php_stream_filter *filter TSRMLS_DC);
128: PHPAPI int php_stream_filter_prepend_ex(php_stream_filter_chain *chain, php_stream_filter *filter TSRMLS_DC);
129: PHPAPI void _php_stream_filter_append(php_stream_filter_chain *chain, php_stream_filter *filter TSRMLS_DC);
130: PHPAPI int php_stream_filter_append_ex(php_stream_filter_chain *chain, php_stream_filter *filter TSRMLS_DC);
131: PHPAPI int _php_stream_filter_flush(php_stream_filter *filter, int finish TSRMLS_DC);
132: PHPAPI php_stream_filter *php_stream_filter_remove(php_stream_filter *filter, int call_dtor TSRMLS_DC);
133: PHPAPI void php_stream_filter_free(php_stream_filter *filter TSRMLS_DC);
134: PHPAPI php_stream_filter *_php_stream_filter_alloc(php_stream_filter_ops *fops, void *abstract, int persistent STREAMS_DC TSRMLS_DC);
135: END_EXTERN_C()
136: #define php_stream_filter_alloc(fops, thisptr, persistent) _php_stream_filter_alloc((fops), (thisptr), (persistent) STREAMS_CC TSRMLS_CC)
137: #define php_stream_filter_alloc_rel(fops, thisptr, persistent) _php_stream_filter_alloc((fops), (thisptr), (persistent) STREAMS_REL_CC TSRMLS_CC)
138: #define php_stream_filter_prepend(chain, filter) _php_stream_filter_prepend((chain), (filter) TSRMLS_CC)
139: #define php_stream_filter_append(chain, filter) _php_stream_filter_append((chain), (filter) TSRMLS_CC)
140: #define php_stream_filter_flush(filter, finish) _php_stream_filter_flush((filter), (finish) TSRMLS_CC)
141:
142: #define php_stream_is_filtered(stream) ((stream)->readfilters.head || (stream)->writefilters.head)
143:
144: typedef struct _php_stream_filter_factory {
145: php_stream_filter *(*create_filter)(const char *filtername, zval *filterparams, int persistent TSRMLS_DC);
146: } php_stream_filter_factory;
147:
148: BEGIN_EXTERN_C()
149: PHPAPI int php_stream_filter_register_factory(const char *filterpattern, php_stream_filter_factory *factory TSRMLS_DC);
150: PHPAPI int php_stream_filter_unregister_factory(const char *filterpattern TSRMLS_DC);
151: PHPAPI int php_stream_filter_register_factory_volatile(const char *filterpattern, php_stream_filter_factory *factory TSRMLS_DC);
152: PHPAPI php_stream_filter *php_stream_filter_create(const char *filtername, zval *filterparams, int persistent TSRMLS_DC);
153: END_EXTERN_C()
154:
155: /*
156: * Local variables:
157: * tab-width: 4
158: * c-basic-offset: 4
159: * End:
160: * vim600: sw=4 ts=4 fdm=marker
161: * vim<600: sw=4 ts=4
162: */
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>