util_filter.h revision 13bac43a0f21d8c6401debc1baa76be984474074
4e9e95ba35a68f3c767bc0b23ebf9e904e442517Christian Maeder/* ====================================================================
53e76316f409f6b1b57ed3d2e5cb9cfe1cb511e5Thiemo Wiedemeyer * The Apache Software License, Version 1.1
6b26240dca29e026900a83d51c75ca230a072a16Thiemo Wiedemeyer * Copyright (c) 2000-2001 The Apache Software Foundation. All rights
53e76316f409f6b1b57ed3d2e5cb9cfe1cb511e5Thiemo Wiedemeyer * Redistribution and use in source and binary forms, with or without
2eeec5240b424984e3ee26296da1eeab6c6d739eChristian Maeder * modification, are permitted provided that the following conditions
7520452bb30b5abbd471f82352fc4c1c937e02c5Till Mossakowski * 1. Redistributions of source code must retain the above copyright
7520452bb30b5abbd471f82352fc4c1c937e02c5Till Mossakowski * notice, this list of conditions and the following disclaimer.
53e76316f409f6b1b57ed3d2e5cb9cfe1cb511e5Thiemo Wiedemeyer * 2. Redistributions in binary form must reproduce the above copyright
53e76316f409f6b1b57ed3d2e5cb9cfe1cb511e5Thiemo Wiedemeyer * notice, this list of conditions and the following disclaimer in
53e76316f409f6b1b57ed3d2e5cb9cfe1cb511e5Thiemo Wiedemeyer * the documentation and/or other materials provided with the
53e76316f409f6b1b57ed3d2e5cb9cfe1cb511e5Thiemo Wiedemeyer * distribution.
53e76316f409f6b1b57ed3d2e5cb9cfe1cb511e5Thiemo Wiedemeyer * 3. The end-user documentation included with the redistribution,
53e76316f409f6b1b57ed3d2e5cb9cfe1cb511e5Thiemo Wiedemeyer * if any, must include the following acknowledgment:
53e76316f409f6b1b57ed3d2e5cb9cfe1cb511e5Thiemo Wiedemeyer * "This product includes software developed by the
53e76316f409f6b1b57ed3d2e5cb9cfe1cb511e5Thiemo Wiedemeyer * Apache Software Foundation (http://www.apache.org/)."
53e76316f409f6b1b57ed3d2e5cb9cfe1cb511e5Thiemo Wiedemeyer * Alternately, this acknowledgment may appear in the software itself,
53e76316f409f6b1b57ed3d2e5cb9cfe1cb511e5Thiemo Wiedemeyer * if and wherever such third-party acknowledgments normally appear.
53e76316f409f6b1b57ed3d2e5cb9cfe1cb511e5Thiemo Wiedemeyer * 4. The names "Apache" and "Apache Software Foundation" must
53e76316f409f6b1b57ed3d2e5cb9cfe1cb511e5Thiemo Wiedemeyer * not be used to endorse or promote products derived from this
53e76316f409f6b1b57ed3d2e5cb9cfe1cb511e5Thiemo Wiedemeyer * software without prior written permission. For written
53e76316f409f6b1b57ed3d2e5cb9cfe1cb511e5Thiemo Wiedemeyer * permission, please contact apache@apache.org.
53e76316f409f6b1b57ed3d2e5cb9cfe1cb511e5Thiemo Wiedemeyer * 5. Products derived from this software may not be called "Apache",
38122cbf09ad3dcc31a826cc4093f630515a5cfcChristian Maeder * nor may "Apache" appear in their name, without prior written
521045d36343cd17dd217a81d4b9422ad6ab6a07Christian Maeder * permission of the Apache Software Foundation.
66fd8f017efdb8a6c862c3f1856dfaef90865dd5Thiemo Wiedemeyer * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
0193c86704431f83731015a77cb613d67ae4e3c2Thiemo Wiedemeyer * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
109b67ffce2bad83667e2f4a319d2d7f380f91afThiemo Wiedemeyer * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
8836fa284a241af325aa6f41234b5130b26ec4f9Thiemo Wiedemeyer * DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
8836fa284a241af325aa6f41234b5130b26ec4f9Thiemo Wiedemeyer * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
8836fa284a241af325aa6f41234b5130b26ec4f9Thiemo Wiedemeyer * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
8836fa284a241af325aa6f41234b5130b26ec4f9Thiemo Wiedemeyer * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
331603b37dec12e37e2e1df9634ef0f2c5c73ddfThiemo Wiedemeyer * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
7ae38566aaf40710cd83ffa3ba25655c4ad22741Thiemo Wiedemeyer * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
1a389234e68da7c3d087b038307ed8c66fc6dc32Thiemo Wiedemeyer * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
66fd8f017efdb8a6c862c3f1856dfaef90865dd5Thiemo Wiedemeyer * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
38122cbf09ad3dcc31a826cc4093f630515a5cfcChristian Maeder * SUCH DAMAGE.
53e76316f409f6b1b57ed3d2e5cb9cfe1cb511e5Thiemo Wiedemeyer * ====================================================================
53e76316f409f6b1b57ed3d2e5cb9cfe1cb511e5Thiemo Wiedemeyer * This software consists of voluntary contributions made by many
53e76316f409f6b1b57ed3d2e5cb9cfe1cb511e5Thiemo Wiedemeyer * individuals on behalf of the Apache Software Foundation. For more
53e76316f409f6b1b57ed3d2e5cb9cfe1cb511e5Thiemo Wiedemeyer * information on the Apache Software Foundation, please see
4e9e95ba35a68f3c767bc0b23ebf9e904e442517Christian Maeder * @brief Apache filter library
7ae38566aaf40710cd83ffa3ba25655c4ad22741Thiemo Wiedemeyer/** Returned by the bottom-most filter if no data was written.
53e76316f409f6b1b57ed3d2e5cb9cfe1cb511e5Thiemo Wiedemeyer * @see ap_pass_brigade(). */
4e9e95ba35a68f3c767bc0b23ebf9e904e442517Christian Maeder/** Returned by the bottom-most filter if no data was read.
4e9e95ba35a68f3c767bc0b23ebf9e904e442517Christian Maeder * @see ap_get_brigade(). */
79d103748927615310322af6f7806c7cef11a802Christian Maeder/** Returned when?? @bug find out when! */
697e63e30aa3c309a1ef1f9357745111f8dfc5a9Christian Maeder * input filtering modes
ecd98975b8a8ab5a7bc075562bdab51cf47d2a90Christian Maeder * @see apr_read_type_e in apr_buckets.h -- this is a superset of it
4b136ad539bd9f4e115dff4eee4d552a42d4437eChristian Maeder /** The filter shouldn't return until data is received or EOF is hit
f456529a89bfb620d39e5fd5b0a53b24643db96dDominik Luecke * or an error occurs. */
4c8d3c5a9e938633f6147b5a595b9b93bfca99e6Christian Maeder /** The filter should process any available data/status as normal,
53e76316f409f6b1b57ed3d2e5cb9cfe1cb511e5Thiemo Wiedemeyer * but will not wait for additional data. */
53e76316f409f6b1b57ed3d2e5cb9cfe1cb511e5Thiemo Wiedemeyer /** The filter should return ::APR_SUCCESS if data is available or
53e76316f409f6b1b57ed3d2e5cb9cfe1cb511e5Thiemo Wiedemeyer * ::APR_EOF otherwise. The filter must not return any buckets of
53e76316f409f6b1b57ed3d2e5cb9cfe1cb511e5Thiemo Wiedemeyer * data. Data returned on a subsequent call, when mode is
53e76316f409f6b1b57ed3d2e5cb9cfe1cb511e5Thiemo Wiedemeyer * ::AP_MODE_BLOCKING or ::AP_MODE_NONBLOCKING. */
53e76316f409f6b1b57ed3d2e5cb9cfe1cb511e5Thiemo Wiedemeyer * @defgroup filter FILTER CHAIN
16e45483b5ce48f0b92d01c817242a8c9b8bae02Christian Maeder * Filters operate using a "chaining" mechanism. The filters are chained
40b73e7d13a858afeac95321fcdb9ac216bfbf01Thiemo Wiedemeyer * together into a sequence. When output is generated, it is passed through
ddc662fdf0207eae2034d7b68ae5e2225c575207Thiemo Wiedemeyer * each of the filters on this chain, until it reaches the end (or "bottom")
53e76316f409f6b1b57ed3d2e5cb9cfe1cb511e5Thiemo Wiedemeyer * and is placed onto the network.
71654489020a03cf6ce9f2947f3da26a996f9c32Razvan Pascanu * The top of the chain, the code generating the output, is typically called
71654489020a03cf6ce9f2947f3da26a996f9c32Razvan Pascanu * a "content generator." The content generator's output is fed into the
66fd8f017efdb8a6c862c3f1856dfaef90865dd5Thiemo Wiedemeyer * filter chain using the standard Apache output mechanisms: ap_rputs(),
331603b37dec12e37e2e1df9634ef0f2c5c73ddfThiemo Wiedemeyer * ap_rprintf(), ap_rwrite(), etc.
5044e8de9e6fde7a139a5e34324c92a4d08a6e73Thiemo Wiedemeyer * Each filter is defined by a callback. This callback takes the output from
331603b37dec12e37e2e1df9634ef0f2c5c73ddfThiemo Wiedemeyer * the previous filter (or the content generator if there is no previous
331603b37dec12e37e2e1df9634ef0f2c5c73ddfThiemo Wiedemeyer * filter), operates on it, and passes the result to the next filter in the
331603b37dec12e37e2e1df9634ef0f2c5c73ddfThiemo Wiedemeyer * chain. This pass-off is performed using the ap_fc_* functions, such as
331603b37dec12e37e2e1df9634ef0f2c5c73ddfThiemo Wiedemeyer * ap_fc_puts(), ap_fc_printf(), ap_fc_write(), etc.
331603b37dec12e37e2e1df9634ef0f2c5c73ddfThiemo Wiedemeyer * When content generation is complete, the system will pass an "end of
03bbcb1fefdbd8bc4e8329ca2688809d84aff0a9Christian Maeder * stream" marker into the filter chain. The filters will use this to flush
5044e8de9e6fde7a139a5e34324c92a4d08a6e73Thiemo Wiedemeyer * out any internal state and to detect incomplete syntax (for example, an
5044e8de9e6fde7a139a5e34324c92a4d08a6e73Thiemo Wiedemeyer * unterminated SSI directive).
5044e8de9e6fde7a139a5e34324c92a4d08a6e73Thiemo Wiedemeyer/* forward declare the filter type */
c40b7badd217089d8a256dabdf8f7d4e219ca215Thiemo Wiedemeyer * @name Filter callbacks
71654489020a03cf6ce9f2947f3da26a996f9c32Razvan Pascanu * This function type is used for filter callbacks. It will be passed a
71654489020a03cf6ce9f2947f3da26a996f9c32Razvan Pascanu * pointer to "this" filter, and a "bucket" containing the content to be
71654489020a03cf6ce9f2947f3da26a996f9c32Razvan Pascanu * In filter->ctx, the callback will find its context. This context is
c40b7badd217089d8a256dabdf8f7d4e219ca215Thiemo Wiedemeyer * provided here, so that a filter may be installed multiple times, each
53e76316f409f6b1b57ed3d2e5cb9cfe1cb511e5Thiemo Wiedemeyer * receiving its own per-install context pointer.
71654489020a03cf6ce9f2947f3da26a996f9c32Razvan Pascanu * Callbacks are associated with a filter definition, which is specified
1be357403a65d1954fd6b5f38e5cf8a630d8112fThiemo Wiedemeyer * by name. See ap_register_input_filter() and ap_register_output_filter()
ddc662fdf0207eae2034d7b68ae5e2225c575207Thiemo Wiedemeyer * for setting the association between a name for a filter and its
966a6c024c828387023fccb0cd0049f78687e5dcThiemo Wiedemeyer * associated callback (and other information).
a4e6fb26100f53e3b1e9f5b97c2e0a0c129294e5Christian Maeder * The *bucket structure (and all those referenced by ->next and ->prev)
a4e6fb26100f53e3b1e9f5b97c2e0a0c129294e5Christian Maeder * should be considered "const". The filter is allowed to modify the
71654489020a03cf6ce9f2947f3da26a996f9c32Razvan Pascanu * next/prev to insert/remove/replace elements in the bucket list, but
71654489020a03cf6ce9f2947f3da26a996f9c32Razvan Pascanu * the types and values of the individual buckets should not be altered.
71654489020a03cf6ce9f2947f3da26a996f9c32Razvan Pascanu * The return value of a filter should be an APR status value.
1ac36418f204bbe56f4cd951a979180721758999Christian Maeder * @ingroup filter
71654489020a03cf6ce9f2947f3da26a996f9c32Razvan Pascanutypedef apr_status_t (*ap_out_filter_func)(ap_filter_t *f, apr_bucket_brigade *b);
71654489020a03cf6ce9f2947f3da26a996f9c32Razvan Pascanutypedef apr_status_t (*ap_in_filter_func)(ap_filter_t *f, apr_bucket_brigade *b,
109b67ffce2bad83667e2f4a319d2d7f380f91afThiemo Wiedemeyer * Filters have different types/classifications. These are used to group
1842453990fed8a1bd7a5ac792d7982c1d2bfcd5Christian Maeder * and sort the filters to properly sequence their operation.
1ac36418f204bbe56f4cd951a979180721758999Christian Maeder * The types have a particular sort order, which allows us to insert them
1ac36418f204bbe56f4cd951a979180721758999Christian Maeder * into the filter chain in a determistic order. Within a particular grouping,
109b67ffce2bad83667e2f4a319d2d7f380f91afThiemo Wiedemeyer * the ordering is equivalent to the order of calls to ap_add_*_filter().
71654489020a03cf6ce9f2947f3da26a996f9c32Razvan Pascanutypedef enum {
53e76316f409f6b1b57ed3d2e5cb9cfe1cb511e5Thiemo Wiedemeyer /** These filters are used to alter the content that is passed through
71654489020a03cf6ce9f2947f3da26a996f9c32Razvan Pascanu * them. Examples are SSI or PHP. */
a4e6fb26100f53e3b1e9f5b97c2e0a0c129294e5Christian Maeder /** (XXX somebody rename me or get rid of me please)
71654489020a03cf6ce9f2947f3da26a996f9c32Razvan Pascanu * This special type ensures that the HTTP header filter ends up in
71654489020a03cf6ce9f2947f3da26a996f9c32Razvan Pascanu * the proper location in the filter chain. */
53e76316f409f6b1b57ed3d2e5cb9cfe1cb511e5Thiemo Wiedemeyer /** These filters implement transport encodings (e.g., chunking). */
79d103748927615310322af6f7806c7cef11a802Christian Maeder /** These filters will alter the content, but in ways that are
53e76316f409f6b1b57ed3d2e5cb9cfe1cb511e5Thiemo Wiedemeyer * more strongly associated with the connection. Examples are
71654489020a03cf6ce9f2947f3da26a996f9c32Razvan Pascanu * splitting * an HTTP connection into multiple requests and
1be357403a65d1954fd6b5f38e5cf8a630d8112fThiemo Wiedemeyer * buffering HTTP * responses across multiple requests.
1be357403a65d1954fd6b5f38e5cf8a630d8112fThiemo Wiedemeyer * It is important to note that these types of filters are not
53e76316f409f6b1b57ed3d2e5cb9cfe1cb511e5Thiemo Wiedemeyer * allowed in a sub-request. A sub-request's output can certainly
53e76316f409f6b1b57ed3d2e5cb9cfe1cb511e5Thiemo Wiedemeyer * be filtered by ::AP_FTYPE_CONTENT filters, but all of the "final
53e76316f409f6b1b57ed3d2e5cb9cfe1cb511e5Thiemo Wiedemeyer * processing" is determined by the main request. */
53e76316f409f6b1b57ed3d2e5cb9cfe1cb511e5Thiemo Wiedemeyer /** These filters don't alter the content. They are responsible for
53e76316f409f6b1b57ed3d2e5cb9cfe1cb511e5Thiemo Wiedemeyer * sending/receiving data to/from the client. */
d1066b8fb69179973dcab47154858d77e72760a7Thiemo Wiedemeyer * This is the request-time context structure for an installed filter (in
d1066b8fb69179973dcab47154858d77e72760a7Thiemo Wiedemeyer * the output filter chain). It provides the callback to use for filtering,
1be357403a65d1954fd6b5f38e5cf8a630d8112fThiemo Wiedemeyer * the request this filter is associated with (which is important when
a4e6fb26100f53e3b1e9f5b97c2e0a0c129294e5Christian Maeder * an output chain also includes sub-request filters), the context for this
71654489020a03cf6ce9f2947f3da26a996f9c32Razvan Pascanu * installed filter, and the filter ordering/chaining fields.
86b2d79be961f0247a2eed10ed4f86d8d6a7639dChristian Maeder * Filter callbacks are free to use ->ctx as they please, to store context
d1066b8fb69179973dcab47154858d77e72760a7Thiemo Wiedemeyer * during the filter process. Generally, this is superior over associating
53e76316f409f6b1b57ed3d2e5cb9cfe1cb511e5Thiemo Wiedemeyer * the state directly with the request. A callback should not change any of
53e76316f409f6b1b57ed3d2e5cb9cfe1cb511e5Thiemo Wiedemeyer * the other fields.
71654489020a03cf6ce9f2947f3da26a996f9c32Razvan Pascanutypedef struct ap_filter_rec_t ap_filter_rec_t;
71654489020a03cf6ce9f2947f3da26a996f9c32Razvan Pascanu * This structure is used for recording information about the
8f5219469b89a15dc6d4c2c30463775975f5841cRazvan Pascanu * registered filters. It associates a name with the filter's callback
71654489020a03cf6ce9f2947f3da26a996f9c32Razvan Pascanu * and filter type.
53e76316f409f6b1b57ed3d2e5cb9cfe1cb511e5Thiemo Wiedemeyer * At the moment, these are simply linked in a chain, so a ->next pointer
53e76316f409f6b1b57ed3d2e5cb9cfe1cb511e5Thiemo Wiedemeyer * is available.
71654489020a03cf6ce9f2947f3da26a996f9c32Razvan Pascanu /** The registered name for this filter */
1ac36418f204bbe56f4cd951a979180721758999Christian Maeder /** The function to call when this filter is invoked. */
53e76316f409f6b1b57ed3d2e5cb9cfe1cb511e5Thiemo Wiedemeyer /** The type of filter, either AP_FTYPE_CONTENT or AP_FTYPE_CONNECTION.
71654489020a03cf6ce9f2947f3da26a996f9c32Razvan Pascanu * An AP_FTYPE_CONTENT filter modifies the data based on information
53e76316f409f6b1b57ed3d2e5cb9cfe1cb511e5Thiemo Wiedemeyer * found in the content. An AP_FTYPE_CONNECTION filter modifies the
53e76316f409f6b1b57ed3d2e5cb9cfe1cb511e5Thiemo Wiedemeyer * data based on the type of connection.
71654489020a03cf6ce9f2947f3da26a996f9c32Razvan Pascanu /** The next filter_rec in the list */
71654489020a03cf6ce9f2947f3da26a996f9c32Razvan Pascanu * The representation of a filter chain. Each request has a list
71654489020a03cf6ce9f2947f3da26a996f9c32Razvan Pascanu * of these structures which are called in turn to filter the data. Sub
71654489020a03cf6ce9f2947f3da26a996f9c32Razvan Pascanu * requests get an exact copy of the main requests filter chain.
53e76316f409f6b1b57ed3d2e5cb9cfe1cb511e5Thiemo Wiedemeyer /** The internal representation of this filter. This includes
71654489020a03cf6ce9f2947f3da26a996f9c32Razvan Pascanu * the filter's name, type, and the actual function pointer.
53e76316f409f6b1b57ed3d2e5cb9cfe1cb511e5Thiemo Wiedemeyer /** A place to store any data associated with the current filter */
ddc662fdf0207eae2034d7b68ae5e2225c575207Thiemo Wiedemeyer /** The next filter in the chain */
71654489020a03cf6ce9f2947f3da26a996f9c32Razvan Pascanu /** The request_rec associated with the current filter. If a sub-request
a4e6fb26100f53e3b1e9f5b97c2e0a0c129294e5Christian Maeder * adds filters, then the sub-request is the request associated with the
71654489020a03cf6ce9f2947f3da26a996f9c32Razvan Pascanu /** The conn_rec associated with the current filter. This is analogous
71654489020a03cf6ce9f2947f3da26a996f9c32Razvan Pascanu * to the request_rec, except that it is used for input filtering.
aa07f9c4585a94514dcff2979d853d6e04c12fb9Thiemo Wiedemeyer * Get the current bucket brigade from the next filter on the filter
5044e8de9e6fde7a139a5e34324c92a4d08a6e73Thiemo Wiedemeyer * stack. The filter should return an apr_status_t value. If the bottom-most
aa07f9c4585a94514dcff2979d853d6e04c12fb9Thiemo Wiedemeyer * filter doesn't write to the network, then ::AP_NOBODY_READ is returned.
8836fa284a241af325aa6f41234b5130b26ec4f9Thiemo Wiedemeyer * @param filter The next filter in the chain
aa07f9c4585a94514dcff2979d853d6e04c12fb9Thiemo Wiedemeyer * @param bucket The current bucket brigade
8836fa284a241af325aa6f41234b5130b26ec4f9Thiemo Wiedemeyer * @param mode ::AP_MODE_BLOCKING, ::AP_MODE_NONBLOCKING, or ::AP_MODE_PEEK
8836fa284a241af325aa6f41234b5130b26ec4f9Thiemo Wiedemeyer * @param readbytes How many bytes to read from the next filter. 0 means that
8836fa284a241af325aa6f41234b5130b26ec4f9Thiemo Wiedemeyer * a single line should be read.
66fd8f017efdb8a6c862c3f1856dfaef90865dd5Thiemo WiedemeyerAP_DECLARE(apr_status_t) ap_get_brigade(ap_filter_t *filter, apr_bucket_brigade *bucket,
8836fa284a241af325aa6f41234b5130b26ec4f9Thiemo Wiedemeyer ap_input_mode_t mode, apr_off_t *readbytes);
66fd8f017efdb8a6c862c3f1856dfaef90865dd5Thiemo Wiedemeyer * Pass the current bucket brigade down to the next filter on the filter
66fd8f017efdb8a6c862c3f1856dfaef90865dd5Thiemo Wiedemeyer * stack. The filter should return an apr_status_t value. If the bottom-most
66fd8f017efdb8a6c862c3f1856dfaef90865dd5Thiemo Wiedemeyer * filter doesn't write to the network, then ::AP_NOBODY_WROTE is returned.
66fd8f017efdb8a6c862c3f1856dfaef90865dd5Thiemo Wiedemeyer * @param filter The next filter in the chain
66fd8f017efdb8a6c862c3f1856dfaef90865dd5Thiemo Wiedemeyer * @param bucket The current bucket brigade
1ac36418f204bbe56f4cd951a979180721758999Christian MaederAP_DECLARE(apr_status_t) ap_pass_brigade(ap_filter_t *filter, apr_bucket_brigade *bucket);
66fd8f017efdb8a6c862c3f1856dfaef90865dd5Thiemo Wiedemeyer * This function is used to register an input filter with the system.
545d0cd78159cade346b579d06052638b19b0f72Thiemo Wiedemeyer * After this registration is performed, then a filter may be added
71654489020a03cf6ce9f2947f3da26a996f9c32Razvan Pascanu * into the filter chain by using ap_add_input_filter() and simply
545d0cd78159cade346b579d06052638b19b0f72Thiemo Wiedemeyer * specifying the name.
71654489020a03cf6ce9f2947f3da26a996f9c32Razvan Pascanu * @param name The name to attach to the filter function
a4e6fb26100f53e3b1e9f5b97c2e0a0c129294e5Christian Maeder * @param filter_func The filter function to name
71654489020a03cf6ce9f2947f3da26a996f9c32Razvan Pascanu * @param ftype The type of filter function, either ::AP_FTYPE_CONTENT or ::
1ac36418f204bbe56f4cd951a979180721758999Christian Maeder * AP_FTYPE_CONNECTION
71654489020a03cf6ce9f2947f3da26a996f9c32Razvan Pascanu * @see add_input_filter()
71654489020a03cf6ce9f2947f3da26a996f9c32Razvan PascanuAP_DECLARE(void) ap_register_input_filter(const char *name,
71654489020a03cf6ce9f2947f3da26a996f9c32Razvan Pascanu * This function is used to register an output filter with the system.
5b00a9d748d5bea461601ed7ed5198dfd30cf2d2Thiemo Wiedemeyer * After this registration is performed, then a filter may be added
5b00a9d748d5bea461601ed7ed5198dfd30cf2d2Thiemo Wiedemeyer * into the filter chain by using ap_add_output_filter() and simply
5b00a9d748d5bea461601ed7ed5198dfd30cf2d2Thiemo Wiedemeyer * specifying the name.
71654489020a03cf6ce9f2947f3da26a996f9c32Razvan Pascanu * @param name The name to attach to the filter function
71654489020a03cf6ce9f2947f3da26a996f9c32Razvan Pascanu * @param filter_func The filter function to name
66fd8f017efdb8a6c862c3f1856dfaef90865dd5Thiemo Wiedemeyer * @param ftype The type of filter function, either ::AP_FTYPE_CONTENT or
66fd8f017efdb8a6c862c3f1856dfaef90865dd5Thiemo Wiedemeyer * ::AP_FTYPE_CONNECTION
84ba39232a012abf2085c8a421ebce6abc52d56eThiemo Wiedemeyer * @see ap_add_output_filter()
66fd8f017efdb8a6c862c3f1856dfaef90865dd5Thiemo WiedemeyerAP_DECLARE(void) ap_register_output_filter(const char *name,
84ba39232a012abf2085c8a421ebce6abc52d56eThiemo Wiedemeyer * Adds a named filter into the filter chain on the specified request record.
84ba39232a012abf2085c8a421ebce6abc52d56eThiemo Wiedemeyer * The filter will be installed with the specified context pointer.
84ba39232a012abf2085c8a421ebce6abc52d56eThiemo Wiedemeyer * Filters added in this way will always be placed at the end of the filters
84ba39232a012abf2085c8a421ebce6abc52d56eThiemo Wiedemeyer * that have the same type (thus, the filters have the same order as the
66fd8f017efdb8a6c862c3f1856dfaef90865dd5Thiemo Wiedemeyer * calls to ap_add_filter). If the current filter chain contains filters
66fd8f017efdb8a6c862c3f1856dfaef90865dd5Thiemo Wiedemeyer * from another request, then this filter will be added before those other
1ac36418f204bbe56f4cd951a979180721758999Christian Maeder * To re-iterate that last comment. This function is building a FIFO
66fd8f017efdb8a6c862c3f1856dfaef90865dd5Thiemo Wiedemeyer * list of filters. Take note of that when adding your filter to the chain.
1ac36418f204bbe56f4cd951a979180721758999Christian Maeder * @param name The name of the filter to add
66fd8f017efdb8a6c862c3f1856dfaef90865dd5Thiemo Wiedemeyer * @param r The request to add this filter for (or NULL if it isn't associated with a request)
66fd8f017efdb8a6c862c3f1856dfaef90865dd5Thiemo Wiedemeyer * @param c The connection to add the fillter for
66fd8f017efdb8a6c862c3f1856dfaef90865dd5Thiemo WiedemeyerAP_DECLARE(ap_filter_t *) ap_add_input_filter(const char *name, void *ctx,
84ba39232a012abf2085c8a421ebce6abc52d56eThiemo Wiedemeyer * Add a filter to the current request. Filters are added in a FIFO manner.
1ac36418f204bbe56f4cd951a979180721758999Christian Maeder * The first filter added will be the first filter called.
66fd8f017efdb8a6c862c3f1856dfaef90865dd5Thiemo Wiedemeyer * @param name The name of the filter to add
66fd8f017efdb8a6c862c3f1856dfaef90865dd5Thiemo Wiedemeyer * @param ctx Context data to set in the filter
84ba39232a012abf2085c8a421ebce6abc52d56eThiemo Wiedemeyer * @param r The request to add this filter for (or NULL if it isn't associated with a request)
66fd8f017efdb8a6c862c3f1856dfaef90865dd5Thiemo Wiedemeyer * @param c The connection to add this filter for
66fd8f017efdb8a6c862c3f1856dfaef90865dd5Thiemo WiedemeyerAP_DECLARE(ap_filter_t *) ap_add_output_filter(const char *name, void *ctx,
66fd8f017efdb8a6c862c3f1856dfaef90865dd5Thiemo Wiedemeyer * Remove an input filter from either the request or connection stack
66fd8f017efdb8a6c862c3f1856dfaef90865dd5Thiemo Wiedemeyer * it is associated with.
66fd8f017efdb8a6c862c3f1856dfaef90865dd5Thiemo Wiedemeyer * @param f The filter to remove
66fd8f017efdb8a6c862c3f1856dfaef90865dd5Thiemo WiedemeyerAP_DECLARE(void) ap_remove_input_filter(ap_filter_t *f);
84ba39232a012abf2085c8a421ebce6abc52d56eThiemo Wiedemeyer * Remove an output filter from either the request or connection stack
84ba39232a012abf2085c8a421ebce6abc52d56eThiemo Wiedemeyer * it is associated with.
84ba39232a012abf2085c8a421ebce6abc52d56eThiemo Wiedemeyer * @param f The filter to remove
84ba39232a012abf2085c8a421ebce6abc52d56eThiemo WiedemeyerAP_DECLARE(void) ap_remove_output_filter(ap_filter_t *f);
66fd8f017efdb8a6c862c3f1856dfaef90865dd5Thiemo Wiedemeyer/* The next two filters are for abstraction purposes only. They could be
66fd8f017efdb8a6c862c3f1856dfaef90865dd5Thiemo Wiedemeyer * done away with, but that would require that we break modules if we ever
545d0cd78159cade346b579d06052638b19b0f72Thiemo Wiedemeyer * want to change our filter registration method. The basic idea, is that
1a389234e68da7c3d087b038307ed8c66fc6dc32Thiemo Wiedemeyer * all filters have a place to store data, the ctx pointer. These functions
1a389234e68da7c3d087b038307ed8c66fc6dc32Thiemo Wiedemeyer * fill out that pointer with a bucket brigade, and retrieve that data on
71654489020a03cf6ce9f2947f3da26a996f9c32Razvan Pascanu * the next call. The nice thing about these functions, is that they
71654489020a03cf6ce9f2947f3da26a996f9c32Razvan Pascanu * automatically concatenate the bucket brigades together for you. This means
a4e6fb26100f53e3b1e9f5b97c2e0a0c129294e5Christian Maeder * that if you have already stored a brigade in the filters ctx pointer, then
71654489020a03cf6ce9f2947f3da26a996f9c32Razvan Pascanu * when you add more it will be tacked onto the end of that brigade. When
71654489020a03cf6ce9f2947f3da26a996f9c32Razvan Pascanu * you retrieve data, if you pass in a bucket brigade to the get function,
71654489020a03cf6ce9f2947f3da26a996f9c32Razvan Pascanu * it will append the current brigade onto the one that you are retrieving.
71654489020a03cf6ce9f2947f3da26a996f9c32Razvan Pascanu * prepare a bucket brigade to be setaside. If a different brigade was
71654489020a03cf6ce9f2947f3da26a996f9c32Razvan Pascanu * set-aside earlier, then the two brigades are concatenated together.
71654489020a03cf6ce9f2947f3da26a996f9c32Razvan Pascanu * @param f The current filter
8681833aefdae18bfd52607b841373f024bbd99cChristian Maeder * @param save_to The brigade that was previously set-aside. Regardless, the
1a389234e68da7c3d087b038307ed8c66fc6dc32Thiemo Wiedemeyer * new bucket brigade is returned in this location.
1a389234e68da7c3d087b038307ed8c66fc6dc32Thiemo Wiedemeyer * @param b The bucket brigade to save aside. This brigade is always empty
71654489020a03cf6ce9f2947f3da26a996f9c32Razvan Pascanu * @param p Ensure that all data in the brigade lives as long as this pool
71654489020a03cf6ce9f2947f3da26a996f9c32Razvan PascanuAP_DECLARE(apr_status_t) ap_save_brigade(ap_filter_t *f, apr_bucket_brigade **save_to,
71654489020a03cf6ce9f2947f3da26a996f9c32Razvan Pascanu * Flush function for apr_brigade_* calls. This calls ap_pass_brigade
71654489020a03cf6ce9f2947f3da26a996f9c32Razvan Pascanu * to flush the brigade if the brigade buffer overflows.
71654489020a03cf6ce9f2947f3da26a996f9c32Razvan Pascanu * @param bb The brigade to flush
8836fa284a241af325aa6f41234b5130b26ec4f9Thiemo Wiedemeyer * @param ctx The filter to pass the brigade to
8836fa284a241af325aa6f41234b5130b26ec4f9Thiemo WiedemeyerAP_DECLARE_NONSTD(apr_status_t) ap_filter_flush(apr_bucket_brigade *bb, void *ctx);
8836fa284a241af325aa6f41234b5130b26ec4f9Thiemo Wiedemeyer * Flush the current brigade down the filter stack.
37e30366abd83c00a5d5447b45694627fd783de8Cui Jian * @param f The current filter
da955132262baab309a50fdffe228c9efe68251dCui Jian * @param bb The brigade to flush
37e30366abd83c00a5d5447b45694627fd783de8Cui JianAP_DECLARE(apr_status_t) ap_fflush(ap_filter_t *f, apr_bucket_brigade *bb);
8836fa284a241af325aa6f41234b5130b26ec4f9Thiemo Wiedemeyer * Write a buffer for the current filter, buffering if possible.
66fd8f017efdb8a6c862c3f1856dfaef90865dd5Thiemo Wiedemeyer * @param f the filter doing the writing
8836fa284a241af325aa6f41234b5130b26ec4f9Thiemo Wiedemeyer * @param bb The brigade to buffer into
1842453990fed8a1bd7a5ac792d7982c1d2bfcd5Christian Maeder * @param data The data to write
66fd8f017efdb8a6c862c3f1856dfaef90865dd5Thiemo Wiedemeyer * @param nbyte The number of bytes in the data
66fd8f017efdb8a6c862c3f1856dfaef90865dd5Thiemo Wiedemeyer apr_brigade_write(bb, ap_filter_flush, f, data, nbyte)
8836fa284a241af325aa6f41234b5130b26ec4f9Thiemo Wiedemeyer * Write a buffer for the current filter, buffering if possible.
40c18e3f63c23085e5bb36ea35efe141a87df8e4Klaus Luettich * @param f the filter doing the writing
fe1f344573c570949fa4f255c68bb9026c609832Thiemo Wiedemeyer * @param bb The brigade to buffer into
66fd8f017efdb8a6c862c3f1856dfaef90865dd5Thiemo Wiedemeyer * @param str The string to write
1842453990fed8a1bd7a5ac792d7982c1d2bfcd5Christian Maeder apr_brigade_puts(bb, ap_filter_flush, f, str)
53e76316f409f6b1b57ed3d2e5cb9cfe1cb511e5Thiemo Wiedemeyer * Write a character for the current filter, buffering if possible.
71654489020a03cf6ce9f2947f3da26a996f9c32Razvan Pascanu * @param f the filter doing the writing
a4e6fb26100f53e3b1e9f5b97c2e0a0c129294e5Christian Maeder * @param bb The brigade to buffer into
71654489020a03cf6ce9f2947f3da26a996f9c32Razvan Pascanu * @param c The character to write
53e76316f409f6b1b57ed3d2e5cb9cfe1cb511e5Thiemo Wiedemeyer * Write an unspecified number of strings to the current filter
53e76316f409f6b1b57ed3d2e5cb9cfe1cb511e5Thiemo Wiedemeyer * @param f the filter doing the writing
109b67ffce2bad83667e2f4a319d2d7f380f91afThiemo Wiedemeyer * @param bb The brigade to buffer into
66fd8f017efdb8a6c862c3f1856dfaef90865dd5Thiemo Wiedemeyer * @param ... The strings to write
4d3b50fc78a0c99ff2914fb23f3c7fba6e38d790Thiemo WiedemeyerAP_DECLARE_NONSTD(apr_status_t) ap_fputstrs(ap_filter_t *f,
71654489020a03cf6ce9f2947f3da26a996f9c32Razvan Pascanu * Output data to the filter in printf format
53e76316f409f6b1b57ed3d2e5cb9cfe1cb511e5Thiemo Wiedemeyer * @param f the filter doing the writing
53e76316f409f6b1b57ed3d2e5cb9cfe1cb511e5Thiemo Wiedemeyer * @param bb The brigade to buffer into
d1066b8fb69179973dcab47154858d77e72760a7Thiemo Wiedemeyer * @param fmt The format string
d1066b8fb69179973dcab47154858d77e72760a7Thiemo Wiedemeyer * @param ... The argumets to use to fill out the format string
53e76316f409f6b1b57ed3d2e5cb9cfe1cb511e5Thiemo WiedemeyerAP_DECLARE_NONSTD(apr_status_t) ap_fprintf(ap_filter_t *f,
966a6c024c828387023fccb0cd0049f78687e5dcThiemo Wiedemeyer#endif /* !AP_FILTER_H */