Back to index

php5  5.3.10
php_stream_filter_api.h
Go to the documentation of this file.
00001 /*
00002    +----------------------------------------------------------------------+
00003    | PHP Version 5                                                        |
00004    +----------------------------------------------------------------------+
00005    | Copyright (c) 1997-2012 The PHP Group                                |
00006    +----------------------------------------------------------------------+
00007    | This source file is subject to version 3.01 of the PHP license,      |
00008    | that is bundled with this package in the file LICENSE, and is        |
00009    | available through the world-wide-web at the following url:           |
00010    | http://www.php.net/license/3_01.txt                                  |
00011    | If you did not receive a copy of the PHP license and are unable to   |
00012    | obtain it through the world-wide-web, please send a note to          |
00013    | license@php.net so we can mail you a copy immediately.               |
00014    +----------------------------------------------------------------------+
00015    | Author: Wez Furlong <wez@thebrainroom.com>                           |
00016    | With suggestions from:                                               |
00017    |      Moriyoshi Koizumi <moriyoshi@at.wakwak.com>                     |
00018    |      Sara Golemon      <pollita@php.net>                             |
00019    +----------------------------------------------------------------------+
00020  */
00021 
00022 /* $Id: php_stream_filter_api.h 321634 2012-01-01 13:15:04Z felipe $ */
00023 
00024 /* The filter API works on the principle of "Bucket-Brigades".  This is
00025  * partially inspired by the Apache 2 method of doing things, although
00026  * it is intentially a light-weight implementation.
00027  *
00028  * Each stream can have a chain of filters for reading and another for writing.
00029  * 
00030  * When data is written to the stream, it is placed into a bucket and placed at
00031  * the start of the input brigade.
00032  *
00033  * The first filter in the chain is invoked on the brigade and (depending on
00034  * it's return value), the next filter is invoked and so on.
00035  * */
00036 
00037 #define PHP_STREAM_FILTER_READ     0x0001
00038 #define PHP_STREAM_FILTER_WRITE    0x0002
00039 #define PHP_STREAM_FILTER_ALL      (PHP_STREAM_FILTER_READ | PHP_STREAM_FILTER_WRITE)
00040 
00041 typedef struct _php_stream_bucket                php_stream_bucket;
00042 typedef struct _php_stream_bucket_brigade php_stream_bucket_brigade;
00043 
00044 struct _php_stream_bucket {
00045        php_stream_bucket *next, *prev;
00046        php_stream_bucket_brigade *brigade;
00047 
00048        char *buf;
00049        size_t buflen;
00050        /* if non-zero, buf should be pefreed when the bucket is destroyed */
00051        int own_buf;
00052        int is_persistent;
00053        
00054        /* destroy this struct when refcount falls to zero */
00055        int refcount;
00056 };
00057 
00058 struct _php_stream_bucket_brigade {
00059        php_stream_bucket *head, *tail;
00060 };
00061 
00062 typedef enum {
00063        PSFS_ERR_FATAL,      /* error in data stream */
00064        PSFS_FEED_ME, /* filter needs more data; stop processing chain until more is available */
00065        PSFS_PASS_ON  /* filter generated output buckets; pass them on to next in chain */
00066 } php_stream_filter_status_t;
00067 
00068 /* Buckets API. */
00069 BEGIN_EXTERN_C()
00070 PHPAPI php_stream_bucket *php_stream_bucket_new(php_stream *stream, char *buf, size_t buflen, int own_buf, int buf_persistent TSRMLS_DC);
00071 PHPAPI int php_stream_bucket_split(php_stream_bucket *in, php_stream_bucket **left, php_stream_bucket **right, size_t length TSRMLS_DC);
00072 PHPAPI void php_stream_bucket_delref(php_stream_bucket *bucket TSRMLS_DC);
00073 #define php_stream_bucket_addref(bucket)  (bucket)->refcount++
00074 PHPAPI void php_stream_bucket_prepend(php_stream_bucket_brigade *brigade, php_stream_bucket *bucket TSRMLS_DC);
00075 PHPAPI void php_stream_bucket_append(php_stream_bucket_brigade *brigade, php_stream_bucket *bucket TSRMLS_DC);
00076 PHPAPI void php_stream_bucket_unlink(php_stream_bucket *bucket TSRMLS_DC);
00077 PHPAPI php_stream_bucket *php_stream_bucket_make_writeable(php_stream_bucket *bucket TSRMLS_DC);
00078 END_EXTERN_C()
00079 
00080 #define PSFS_FLAG_NORMAL           0      /* regular read/write */
00081 #define PSFS_FLAG_FLUSH_INC        1      /* an incremental flush */
00082 #define PSFS_FLAG_FLUSH_CLOSE      2      /* final flush prior to closing */
00083 
00084 typedef struct _php_stream_filter_ops {
00085 
00086        php_stream_filter_status_t (*filter)(
00087                      php_stream *stream,
00088                      php_stream_filter *thisfilter,
00089                      php_stream_bucket_brigade *buckets_in,
00090                      php_stream_bucket_brigade *buckets_out,
00091                      size_t *bytes_consumed,
00092                      int flags
00093                      TSRMLS_DC);
00094        
00095        void (*dtor)(php_stream_filter *thisfilter TSRMLS_DC);
00096        
00097        const char *label;
00098        
00099 } php_stream_filter_ops;
00100 
00101 typedef struct _php_stream_filter_chain {
00102        php_stream_filter *head, *tail;
00103 
00104        /* Owning stream */
00105        php_stream *stream;
00106 } php_stream_filter_chain;
00107 
00108 struct _php_stream_filter {
00109        php_stream_filter_ops *fops;
00110        void *abstract; /* for use by filter implementation */
00111        php_stream_filter *next;
00112        php_stream_filter *prev;
00113        int is_persistent;
00114 
00115        /* link into stream and chain */
00116        php_stream_filter_chain *chain;
00117 
00118        /* buffered buckets */
00119        php_stream_bucket_brigade buffer;
00120 
00121        /* filters are auto_registered when they're applied */
00122        int rsrc_id;
00123 };
00124 
00125 /* stack filter onto a stream */
00126 BEGIN_EXTERN_C()
00127 PHPAPI void _php_stream_filter_prepend(php_stream_filter_chain *chain, php_stream_filter *filter TSRMLS_DC);
00128 PHPAPI int php_stream_filter_prepend_ex(php_stream_filter_chain *chain, php_stream_filter *filter TSRMLS_DC);
00129 PHPAPI void _php_stream_filter_append(php_stream_filter_chain *chain, php_stream_filter *filter TSRMLS_DC);
00130 PHPAPI int php_stream_filter_append_ex(php_stream_filter_chain *chain, php_stream_filter *filter TSRMLS_DC);
00131 PHPAPI int _php_stream_filter_flush(php_stream_filter *filter, int finish TSRMLS_DC);
00132 PHPAPI php_stream_filter *php_stream_filter_remove(php_stream_filter *filter, int call_dtor TSRMLS_DC);
00133 PHPAPI void php_stream_filter_free(php_stream_filter *filter TSRMLS_DC);
00134 PHPAPI php_stream_filter *_php_stream_filter_alloc(php_stream_filter_ops *fops, void *abstract, int persistent STREAMS_DC TSRMLS_DC);
00135 END_EXTERN_C()
00136 #define php_stream_filter_alloc(fops, thisptr, persistent) _php_stream_filter_alloc((fops), (thisptr), (persistent) STREAMS_CC TSRMLS_CC)
00137 #define php_stream_filter_alloc_rel(fops, thisptr, persistent) _php_stream_filter_alloc((fops), (thisptr), (persistent) STREAMS_REL_CC TSRMLS_CC)
00138 #define php_stream_filter_prepend(chain, filter) _php_stream_filter_prepend((chain), (filter) TSRMLS_CC)
00139 #define php_stream_filter_append(chain, filter) _php_stream_filter_append((chain), (filter) TSRMLS_CC)
00140 #define php_stream_filter_flush(filter, finish) _php_stream_filter_flush((filter), (finish) TSRMLS_CC)
00141 
00142 #define php_stream_is_filtered(stream)    ((stream)->readfilters.head || (stream)->writefilters.head)
00143 
00144 typedef struct _php_stream_filter_factory {
00145        php_stream_filter *(*create_filter)(const char *filtername, zval *filterparams, int persistent TSRMLS_DC);
00146 } php_stream_filter_factory;
00147 
00148 BEGIN_EXTERN_C()
00149 PHPAPI int php_stream_filter_register_factory(const char *filterpattern, php_stream_filter_factory *factory TSRMLS_DC);
00150 PHPAPI int php_stream_filter_unregister_factory(const char *filterpattern TSRMLS_DC);
00151 PHPAPI int php_stream_filter_register_factory_volatile(const char *filterpattern, php_stream_filter_factory *factory TSRMLS_DC);
00152 PHPAPI php_stream_filter *php_stream_filter_create(const char *filtername, zval *filterparams, int persistent TSRMLS_DC);
00153 END_EXTERN_C()
00154 
00155 /*
00156  * Local variables:
00157  * tab-width: 4
00158  * c-basic-offset: 4
00159  * End:
00160  * vim600: sw=4 ts=4 fdm=marker
00161  * vim<600: sw=4 ts=4
00162  */