util_filter.h revision a3a9ceac1bc30598c594c89e1382609496b7752b
264N/A/* ==================================================================== 264N/A * The Apache Software License, Version 1.1 264N/A * Copyright (c) 2000-2001 The Apache Software Foundation. All rights 264N/A * Redistribution and use in source and binary forms, with or without 264N/A * modification, are permitted provided that the following conditions 264N/A * 1. Redistributions of source code must retain the above copyright 264N/A * notice, this list of conditions and the following disclaimer. 264N/A * 2. Redistributions in binary form must reproduce the above copyright 264N/A * notice, this list of conditions and the following disclaimer in 264N/A * the documentation and/or other materials provided with the 264N/A * 3. The end-user documentation included with the redistribution, 264N/A * if any, must include the following acknowledgment: 264N/A * "This product includes software developed by the 5396N/A * Alternately, this acknowledgment may appear in the software itself, 264N/A * if and wherever such third-party acknowledgments normally appear. 5220N/A * 4. The names "Apache" and "Apache Software Foundation" must 5135N/A * not be used to endorse or promote products derived from this 4431N/A * software without prior written permission. For written 4431N/A * permission, please contact apache@apache.org. 3817N/A * 5. Products derived from this software may not be called "Apache", 4431N/A * nor may "Apache" appear in their name, without prior written 4431N/A * permission of the Apache Software Foundation. 4431N/A * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED 4431N/A * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 4431N/A * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 3817N/A * DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR 3817N/A * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 6094N/A * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 6094N/A * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF 6094N/A * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND 264N/A * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 6475N/A * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT 6475N/A * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 264N/A * ==================================================================== 264N/A * This software consists of voluntary contributions made by many 5396N/A * individuals on behalf of the Apache Software Foundation. For more 1258N/A * information on the Apache Software Foundation, please see 6094N/A * @brief Apache filter library 4431N/A/** Returned by the bottom-most filter if no data was written. 5135N/A * @see ap_pass_brigade(). */ 5135N/A/** Returned by the bottom-most filter if no data was read. 4431N/A * @see ap_get_brigade(). */ 4375N/A/** Returned when?? @bug find out when! */ 264N/A /** The filter shouldn't return until data is received or EOF is hit 972N/A * or an error occurs. */ 4431N/A * but will not wait for additional data. */ 7243N/A /** The filter should return ::APR_SUCCESS if data is available or 7243N/A * ::APR_EOF otherwise. The filter must not return any buckets of 7243N/A * data. Data returned on a subsequent call, when mode is 7243N/A * ::AP_MODE_BLOCKING or ::AP_MODE_NONBLOCKING. */ 5135N/A * @defgroup filter FILTER CHAIN 5680N/A * Filters operate using a "chaining" mechanism. The filters are chained 264N/A * together into a sequence. When output is generated, it is passed through 4431N/A * each of the filters on this chain, until it reaches the end (or "bottom") 4431N/A * and is placed onto the network. 4431N/A * The top of the chain, the code generating the output, is typically called 5135N/A * a "content generator." The content generator's output is fed into the 7243N/A * filter chain using the standard Apache output mechanisms: ap_rputs(), 5135N/A * ap_rprintf(), ap_rwrite(), etc. 5135N/A * Each filter is defined by a callback. This callback takes the output from 4431N/A * the previous filter (or the content generator if there is no previous 4431N/A * filter), operates on it, and passes the result to the next filter in the 4431N/A * chain. This pass-off is performed using the ap_fc_* functions, such as 4431N/A * ap_fc_puts(), ap_fc_printf(), ap_fc_write(), etc. 795N/A * When content generation is complete, the system will pass an "end of 795N/A * stream" marker into the filter chain. The filters will use this to flush 4431N/A * out any internal state and to detect incomplete syntax (for example, an 4431N/A * unterminated SSI directive). 4431N/A/* forward declare the filter type */ 4431N/A * This function type is used for filter callbacks. It will be passed a 4375N/A * pointer to "this" filter, and a "bucket" containing the content to be 4431N/A * In filter->ctx, the callback will find its context. This context is 4431N/A * provided here, so that a filter may be installed multiple times, each 4431N/A * receiving its own per-install context pointer. 4431N/A * Callbacks are associated with a filter definition, which is specified 4431N/A * by name. See ap_register_input_filter() and ap_register_output_filter() 4431N/A * for setting the association between a name for a filter and its 4431N/A * associated callback (and other information). 4369N/A * The *bucket structure (and all those referenced by ->next and ->prev) 4431N/A * should be considered "const". The filter is allowed to modify the 4431N/A * the types and values of the individual buckets should not be altered. 4431N/A * The return value of a filter should be an APR status value. 4431N/A * and sort the filters to properly sequence their operation. 4431N/A * The types have a particular sort order, which allows us to insert them 4431N/A * into the filter chain in a determistic order. Within a particular grouping, 4431N/A * the ordering is equivalent to the order of calls to ap_add_*_filter(). 4431N/A /** These filters are used to alter the content that is passed through 4431N/A * them. Examples are SSI or PHP. */ 4431N/A /** (XXX somebody rename me or get rid of me please) 4431N/A * This special type ensures that the HTTP header filter ends up in 4431N/A * the proper location in the filter chain. */ 4431N/A /** These filters implement transport encodings (e.g., chunking). */ 4375N/A /** These filters will alter the content, but in ways that are 795N/A * more strongly associated with the connection. Examples are 4431N/A * splitting * an HTTP connection into multiple requests and 6094N/A * buffering HTTP * responses across multiple requests. 5135N/A * It is important to note that these types of filters are not 4431N/A * allowed in a sub-request. A sub-request's output can certainly 4431N/A * be filtered by ::AP_FTYPE_CONTENT filters, but all of the "final 5174N/A * processing" is determined by the main request. */ 5174N/A /** These filters don't alter the content. They are responsible for 5174N/A * This is the request-time context structure for an installed filter (in 4431N/A * the output filter chain). It provides the callback to use for filtering, 4431N/A * the request this filter is associated with (which is important when 6610N/A * an output chain also includes sub-request filters), the context for this 4431N/A * Filter callbacks are free to use ->ctx as they please, to store context 4431N/A * during the filter process. Generally, this is superior over associating 6610N/A * the state directly with the request. A callback should not change any of 4431N/A * This structure is used for recording information about the 4431N/A * registered filters. It associates a name with the filter's callback 6610N/A * At the moment, these are simply linked in a chain, so a ->next pointer 6094N/A /** The registered name for this filter */ 5135N/A /** The function to call when this filter is invoked. */ 4431N/A /** The type of filter, either AP_FTYPE_CONTENT or AP_FTYPE_CONNECTION. 4431N/A * An AP_FTYPE_CONTENT filter modifies the data based on information 6094N/A * found in the content. An AP_FTYPE_CONNECTION filter modifies the 4431N/A * data based on the type of connection. 2063N/A /** The next filter_rec in the list */ 5135N/A * The representation of a filter chain. Each request has a list 5135N/A * of these structures which are called in turn to filter the data. Sub 5135N/A * requests get an exact copy of the main requests filter chain. 5135N/A /** The internal representation of this filter. This includes 4431N/A * the filter's name, type, and the actual function pointer. 5135N/A /** A place to store any data associated with the current filter */ 5135N/A /** The next filter in the chain */ 4431N/A /** The request_rec associated with the current filter. If a sub-request 3477N/A * adds filters, then the sub-request is the request associated with the 6094N/A /** The conn_rec associated with the current filter. This is analogous 6094N/A * to the request_rec, except that it is used for input filtering. 6094N/A * Get the current bucket brigade from the next filter on the filter 6094N/A * stack. The filter should return an apr_status_t value. If the bottom-most 264N/A * filter doesn't write to the network, then ::AP_NOBODY_READ is returned. 264N/A * @param filter The next filter in the chain 264N/A * @param bucket The current bucket brigade 4337N/A * @param mode ::AP_MODE_BLOCKING, ::AP_MODE_NONBLOCKING, or ::AP_MODE_PEEK 6094N/A * Pass the current bucket brigade down to the next filter on the filter 3817N/A * stack. The filter should return an apr_status_t value. If the bottom-most 5795N/A * filter doesn't write to the network, then ::AP_NOBODY_WROTE is returned. 4431N/A * @param filter The next filter in the chain 6094N/A * @param bucket The current bucket brigade 3817N/A * This function is used to register an input filter with the system. 3817N/A * After this registration is performed, then a filter may be added 3817N/A * into the filter chain by using ap_add_input_filter() and simply * @param name The name to attach to the filter function * @param filter_func The filter function to name * @param ftype The type of filter function, either ::AP_FTYPE_CONTENT or :: * @see add_input_filter() * This function is used to register an output filter with the system. * After this registration is performed, then a filter may be added * into the filter chain by using ap_add_output_filter() and simply * @param name The name to attach to the filter function * @param filter_func The filter function to name * @param ftype The type of filter function, either ::AP_FTYPE_CONTENT or * @see ap_add_output_filter() * Adds a named filter into the filter chain on the specified request record. * The filter will be installed with the specified context pointer. * Filters added in this way will always be placed at the end of the filters * that have the same type (thus, the filters have the same order as the * calls to ap_add_filter). If the current filter chain contains filters * from another request, then this filter will be added before those other * To re-iterate that last comment. This function is building a FIFO * list of filters. Take note of that when adding your filter to the chain. * @param name The name of the filter to add * @param r The request to add this filter for (or NULL if it isn't associated with a request) * @param c The connection to add the fillter for * Add a filter to the current request. Filters are added in a FIFO manner. * The first filter added will be the first filter called. * @param name The name of the filter to add * @param ctx Context data to set in the filter * @param r The request to add this filter for (or NULL if it isn't associated with a request) * @param c The connection to add this filter for * Remove an output filter from either the request or connection stack * @param f The filter to remove /* The next two filters are for abstraction purposes only. They could be * done away with, but that would require that we break modules if we ever * want to change our filter registration method. The basic idea, is that * all filters have a place to store data, the ctx pointer. These functions * fill out that pointer with a bucket brigade, and retrieve that data on * the next call. The nice thing about these functions, is that they * automatically concatenate the bucket brigades together for you. This means * that if you have already stored a brigade in the filters ctx pointer, then * when you add more it will be tacked onto the end of that brigade. When * you retrieve data, if you pass in a bucket brigade to the get function, * it will append the current brigade onto the one that you are retrieving. * prepare a bucket brigade to be setaside. If a different brigade was * set-aside earlier, then the two brigades are concatenated together. * @param f The current filter * @param save_to The brigade that was previously set-aside. Regardless, the * new bucket brigade is returned in this location. * @param b The bucket brigade to save aside. This brigade is always empty * Flush function for apr_brigade_* calls. This calls ap_pass_brigade * to flush the brigade if the brigade buffer overflows. * @param bb The brigade to flush * @param ctx The filter to pass the brigade to * Flush the current brigade down the filter stack. * @param f The current filter * @param bb The brigade to flush * Write a buffer for the current filter, buffering if possible. * @param f the filter doing the writing * @param bb The brigade to buffer into * @param data The data to write * @param nbyte The number of bytes in the data * Write a buffer for the current filter, buffering if possible. * @param f the filter doing the writing * @param bb The brigade to buffer into * @param str The string to write * Write a character for the current filter, buffering if possible. * @param f the filter doing the writing * @param bb The brigade to buffer into * @param c The character to write * Write an unspecified number of strings to the current filter * @param f the filter doing the writing * @param bb The brigade to buffer into * @param ... The strings to write * Output data to the filter in printf format * @param f the filter doing the writing * @param bb The brigade to buffer into * @param fmt The format string * @param ... The argumets to use to fill out the format string #
endif /* !AP_FILTER_H */