Filter Chain

Collaboration diagram for Filter Chain:

Data Structures
union	ap_filter_func
struct	ap_filter_rec_t
	This structure is used for recording information about the registered filters. It associates a name with the filter's callback and filter type. More...
struct	ap_filter_t
	The representation of a filter chain. More...

Macros
#define	ap_fwrite(f, bb, data, nbyte)    apr_brigade_write(bb, ap_filter_flush, f, data, nbyte)
#define	ap_fputs(f, bb, str)    apr_brigade_write(bb, ap_filter_flush, f, str, strlen(str))
#define	ap_fputc(f, bb, c)    apr_brigade_putc(bb, ap_filter_flush, f, c)
#define	AP_FILTER_PROTO_CHANGE   0x1
#define	AP_FILTER_PROTO_CHANGE_LENGTH   0x2
#define	AP_FILTER_PROTO_NO_BYTERANGE   0x4
#define	AP_FILTER_PROTO_NO_PROXY   0x8
#define	AP_FILTER_PROTO_NO_CACHE   0x10
#define	AP_FILTER_PROTO_TRANSFORM   0x20
#define	AP_BUCKET_IS_WC(e)

Typedefs
typedef struct ap_filter_t	ap_filter_t
typedef struct ap_filter_rec_t	ap_filter_rec_t
typedef struct ap_filter_provider_t	ap_filter_provider_t

Enumerations
enum	ap_filter_type {   AP_FTYPE_RESOURCE = 10 , AP_FTYPE_CONTENT_SET = 20 , AP_FTYPE_PROTOCOL = 30 , AP_FTYPE_TRANSCODE = 40 ,   AP_FTYPE_CONNECTION = 50 , AP_FTYPE_NETWORK = 60 }
enum	ap_filter_direction_e { AP_FILTER_INPUT = 1 , AP_FILTER_OUTPUT = 2 }

Functions
apr_bucket_brigade *	ap_acquire_brigade (conn_rec *c)
void	ap_release_brigade (conn_rec *c, apr_bucket_brigade *bb)
apr_status_t	ap_get_brigade (ap_filter_t *filter, apr_bucket_brigade *bucket, ap_input_mode_t mode, apr_read_type_e block, apr_off_t readbytes)
apr_status_t	ap_pass_brigade (ap_filter_t *filter, apr_bucket_brigade *bucket)
apr_status_t	ap_pass_brigade_fchk (request_rec *r, apr_bucket_brigade *bucket, const char *fmt,...) __attribute__((format(printf
apr_status_t ap_filter_rec_t *	ap_register_input_filter (const char *name, ap_in_filter_func filter_func, ap_init_filter_func filter_init, ap_filter_type ftype)
ap_filter_rec_t *	ap_register_output_filter (const char *name, ap_out_filter_func filter_func, ap_init_filter_func filter_init, ap_filter_type ftype)
ap_filter_rec_t *	ap_register_output_filter_protocol (const char *name, ap_out_filter_func filter_func, ap_init_filter_func filter_init, ap_filter_type ftype, unsigned int proto_flags)
ap_filter_t *	ap_add_input_filter (const char *name, void *ctx, request_rec *r, conn_rec *c)
ap_filter_t *	ap_add_input_filter_handle (ap_filter_rec_t *f, void *ctx, request_rec *r, conn_rec *c)
ap_filter_rec_t *	ap_get_input_filter_handle (const char *name)
ap_filter_t *	ap_add_output_filter (const char *name, void *ctx, request_rec *r, conn_rec *c)
ap_filter_t *	ap_add_output_filter_handle (ap_filter_rec_t *f, void *ctx, request_rec *r, conn_rec *c)
ap_filter_rec_t *	ap_get_output_filter_handle (const char *name)
void	ap_remove_input_filter (ap_filter_t *f)
void	ap_remove_output_filter (ap_filter_t *f)
apr_status_t	ap_remove_input_filter_byhandle (ap_filter_t *next, const char *handle)
apr_status_t	ap_remove_output_filter_byhandle (ap_filter_t *next, const char *handle)
apr_status_t	ap_save_brigade (ap_filter_t *f, apr_bucket_brigade **save_to, apr_bucket_brigade **b, apr_pool_t *p)
int	ap_filter_prepare_brigade (ap_filter_t *f)
apr_status_t	ap_filter_setaside_brigade (ap_filter_t *f, apr_bucket_brigade *bb)
apr_status_t	ap_filter_reinstate_brigade (ap_filter_t *f, apr_bucket_brigade *bb, apr_bucket **flush_upto)
void	ap_filter_adopt_brigade (ap_filter_t *f, apr_bucket_brigade *bb)
int	ap_filter_should_yield (ap_filter_t *f)
int	ap_filter_output_pending (conn_rec *c)
int	ap_filter_input_pending (conn_rec *c)
apr_status_t	ap_filter_flush (apr_bucket_brigade *bb, void *ctx)
apr_status_t	ap_fflush (ap_filter_t *f, apr_bucket_brigade *bb)
apr_status_t	ap_fputstrs (ap_filter_t *f, apr_bucket_brigade *bb,...) AP_FN_ATTR_SENTINEL
apr_status_t	ap_fprintf (ap_filter_t *f, apr_bucket_brigade *bb, const char *fmt,...) __attribute__((format(printf
apr_status_t void	ap_filter_protocol (ap_filter_t *f, unsigned int proto_flags)
apr_bucket *	ap_bucket_wc_make (apr_bucket *b)
apr_bucket *	ap_bucket_wc_create (apr_bucket_alloc_t *list)

Variables
AP_DECLARE_DATA const char	ap_bucket_wc_data
	Write Completion (WC) bucket. More...

Filter callbacks
This function type is used for filter callbacks. It will be passed a pointer to "this" filter, and a "bucket brigade" containing the content to be filtered. In filter->ctx, the callback will find its context. This context is provided here, so that a filter may be installed multiple times, each receiving its own per-install context pointer. Callbacks are associated with a filter definition, which is specified by name. See ap_register_input_filter() and ap_register_output_filter() for setting the association between a name for a filter and its associated callback (and other information). If the initialization function argument passed to the registration functions is non-NULL, it will be called iff the filter is in the input or output filter chains and before any data is generated to allow the filter to prepare for processing. The bucket brigade always belongs to the caller, but the filter is free to use the buckets within it as it sees fit. Normally, the brigade will be returned empty. Buckets may not be retained between successive calls to the filter unless they have been "set aside" with a call apr_bucket_setaside. Typically this will be done with ap_save_brigade(). Buckets removed from the brigade become the responsibility of the filter, which must arrange for them to be deleted, either by doing so directly or by inserting them in a brigade which will subsequently be destroyed. For the input and output filters, the return value of a filter should be an APR status value. For the init function, the return value should be an HTTP error code or OK if it was successful.
typedef apr_status_t(*	ap_out_filter_func) (ap_filter_t *f, apr_bucket_brigade *b)
typedef apr_status_t(*	ap_in_filter_func) (ap_filter_t *f, apr_bucket_brigade *b, ap_input_mode_t mode, apr_read_type_e block, apr_off_t readbytes)
typedef int(*	ap_init_filter_func) (ap_filter_t *f)
typedef union ap_filter_func	ap_filter_func

Detailed Description

Filters operate using a "chaining" mechanism. The filters are chained together into a sequence. When output is generated, it is passed through each of the filters on this chain, until it reaches the end (or "bottom") and is placed onto the network.

The top of the chain, the code generating the output, is typically called a "content generator." The content generator's output is fed into the filter chain using the standard Apache output mechanisms: ap_rputs(), ap_rprintf(), ap_rwrite(), etc.

Each filter is defined by a callback. This callback takes the output from the previous filter (or the content generator if there is no previous filter), operates on it, and passes the result to the next filter in the chain. This pass-off is performed using the ap_fc_* functions, such as ap_fc_puts(), ap_fc_printf(), ap_fc_write(), etc.

When content generation is complete, the system will pass an "end of stream" marker into the filter chain. The filters will use this to flush out any internal state and to detect incomplete syntax (for example, an unterminated SSI directive).

Macro Definition Documentation

AP_BUCKET_IS_WC

#define AP_BUCKET_IS_WC

(

e

)

Value:

                            (APR_BUCKET_IS_FLUSH(e) && \
                            (e)->data == (void *)&ap_bucket_wc_data)

Determine if a bucket is a Write Completion (WC) bucket

Parameters

e	The bucket to inspect

Returns

true or false

AP_FILTER_PROTO_CHANGE

#define AP_FILTER_PROTO_CHANGE   0x1

Filter changes contents (so invalidating checksums/etc)

AP_FILTER_PROTO_CHANGE_LENGTH

#define AP_FILTER_PROTO_CHANGE_LENGTH   0x2

Filter changes length of contents (so invalidating content-length/etc)

AP_FILTER_PROTO_NO_BYTERANGE

#define AP_FILTER_PROTO_NO_BYTERANGE   0x4

Filter requires complete input and can't work on byteranges

AP_FILTER_PROTO_NO_CACHE

#define AP_FILTER_PROTO_NO_CACHE   0x10

Filter makes output non-cacheable

AP_FILTER_PROTO_NO_PROXY

#define AP_FILTER_PROTO_NO_PROXY   0x8

Filter should not run in a proxy

AP_FILTER_PROTO_TRANSFORM

#define AP_FILTER_PROTO_TRANSFORM   0x20

Filter is incompatible with "Cache-Control: no-transform"

ap_fputc

#define ap_fputc	(		f,
			bb,
			c
	)		apr_brigade_putc(bb, ap_filter_flush, f, c)

Write a character for the current filter, buffering if possible.

Parameters

f	the filter we are writing to
bb	The brigade to buffer into
c	The character to write

ap_fputs

#define ap_fputs	(		f,
			bb,
			str
	)		apr_brigade_write(bb, ap_filter_flush, f, str, strlen(str))

Write a buffer for the current filter, buffering if possible.

Parameters

f	the filter we are writing to
bb	The brigade to buffer into
str	The string to write

ap_fwrite

#define ap_fwrite	(		f,
			bb,
			data,
			nbyte
	)		apr_brigade_write(bb, ap_filter_flush, f, data, nbyte)

Write a buffer for the current filter, buffering if possible.

Parameters

f	the filter we are writing to
bb	The brigade to buffer into
data	The data to write
nbyte	The number of bytes in the data

Typedef Documentation

ap_filter_func

typedef union ap_filter_func ap_filter_func

ap_filter_provider_t

typedef struct ap_filter_provider_t ap_filter_provider_t

ap_filter_rec_t

typedef struct ap_filter_rec_t ap_filter_rec_t

This is the request-time context structure for an installed filter (in the output filter chain). It provides the callback to use for filtering, the request this filter is associated with (which is important when an output chain also includes sub-request filters), the context for this installed filter, and the filter ordering/chaining fields.

Filter callbacks are free to use ->ctx as they please, to store context during the filter process. Generally, this is superior over associating the state directly with the request. A callback should not change any of the other fields.

ap_filter_t

typedef struct ap_filter_t ap_filter_t

ap_in_filter_func

typedef apr_status_t(* ap_in_filter_func) (ap_filter_t *f, apr_bucket_brigade *b, ap_input_mode_t mode, apr_read_type_e block, apr_off_t readbytes)

ap_init_filter_func

typedef int(* ap_init_filter_func) (ap_filter_t *f)

ap_out_filter_func

typedef apr_status_t(* ap_out_filter_func) (ap_filter_t *f, apr_bucket_brigade *b)

Enumeration Type Documentation

ap_filter_direction_e

enum ap_filter_direction_e

These flags indicate whether the given filter is an input filter or an output filter.

Enumerator
AP_FILTER_INPUT	Input filters
AP_FILTER_OUTPUT	Output filters

ap_filter_type

enum ap_filter_type

Filters have different types/classifications. These are used to group and sort the filters to properly sequence their operation.

The types have a particular sort order, which allows us to insert them into the filter chain in a determistic order. Within a particular grouping, the ordering is equivalent to the order of calls to ap_add_*_filter().

Enumerator
AP_FTYPE_RESOURCE	These filters are used to alter the content that is passed through them. Examples are SSI or PHP.
AP_FTYPE_CONTENT_SET	These filters are used to alter the content as a whole, but after all AP_FTYPE_RESOURCE filters are executed. These filters should not change the content-type. An example is deflate.
AP_FTYPE_PROTOCOL	These filters are used to handle the protocol between server and client. Examples are HTTP and POP.
AP_FTYPE_TRANSCODE	These filters implement transport encodings (e.g., chunking).
AP_FTYPE_CONNECTION	These filters will alter the content, but in ways that are more strongly associated with the connection. Examples are splitting an HTTP connection into multiple requests and buffering HTTP responses across multiple requests. It is important to note that these types of filters are not allowed in a sub-request. A sub-request's output can certainly be filtered by AP_FTYPE_RESOURCE filters, but all of the "final processing" is determined by the main request.
AP_FTYPE_NETWORK	These filters don't alter the content. They are responsible for sending/receiving data to/from the client.

Function Documentation

ap_acquire_brigade()

apr_bucket_brigade* ap_acquire_brigade

(

conn_rec *

c

)

Acquire a brigade created on the connection pool/alloc.

Parameters

c	The connection

Returns

The brigade (cleaned up)

ap_add_input_filter()

ap_filter_t* ap_add_input_filter	(	const char *	name,
		void *	ctx,
		request_rec *	r,
		conn_rec *	c
	)

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 filters.

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.

Parameters

name	The name of the filter to add
ctx	Context data to provide to the filter
r	The request to add this filter for (or NULL if it isn't associated with a request)
c	The connection to add the fillter for

ap_add_input_filter_handle()

ap_filter_t* ap_add_input_filter_handle	(	ap_filter_rec_t *	f,
		void *	ctx,
		request_rec *	r,
		conn_rec *	c
	)

Variant of ap_add_input_filter() that accepts a registered filter handle (as returned by ap_register_input_filter()) rather than a filter name

Parameters

f	The filter handle to add
ctx	Context data to provide to the filter
r	The request to add this filter for (or NULL if it isn't associated with a request)
c	The connection to add the fillter for

ap_add_output_filter()

ap_filter_t* ap_add_output_filter	(	const char *	name,
		void *	ctx,
		request_rec *	r,
		conn_rec *	c
	)

Add a filter to the current request. Filters are added in a FIFO manner. The first filter added will be the first filter called.

Parameters

name	The name of the filter to add
ctx	Context data to set in the filter
r	The request to add this filter for (or NULL if it isn't associated with a request)
c	The connection to add this filter for

Note

If adding a connection-level output filter (i.e. where the type is >= AP_FTYPE_CONNECTION) during processing of a request, the request object r must be passed in to ensure the filter chains are modified correctly. f->r will still be initialized as NULL in the new filter.

ap_add_output_filter_handle()

ap_filter_t* ap_add_output_filter_handle	(	ap_filter_rec_t *	f,
		void *	ctx,
		request_rec *	r,
		conn_rec *	c
	)

Variant of ap_add_output_filter() that accepts a registered filter handle (as returned by ap_register_output_filter()) rather than a filter name

Parameters

f	The filter handle to add
ctx	Context data to set in the filter
r	The request to add this filter for (or NULL if it isn't associated with a request)
c	The connection to add the filter for

Note

If adding a connection-level output filter (i.e. where the type is >= AP_FTYPE_CONNECTION) during processing of a request, the request object r must be passed in to ensure the filter chains are modified correctly. f->r will still be initialized as NULL in the new filter.

ap_bucket_wc_create()

apr_bucket* ap_bucket_wc_create

(

apr_bucket_alloc_t *

list

)

Create a bucket referring to a Write Completion (WC).

Parameters

list	The freelist from which this bucket should be allocated

Returns

The new bucket, or NULL if allocation failed

ap_bucket_wc_make()

apr_bucket* ap_bucket_wc_make

(

apr_bucket *

b

)

Make the bucket passed in a Write Completion (WC) bucket

Parameters

b	The bucket to make into a WC bucket

Returns

The new bucket, or NULL if allocation failed

ap_fflush()

apr_status_t ap_fflush	(	ap_filter_t *	f,
		apr_bucket_brigade *	bb
	)

Flush the current brigade down the filter stack.

Parameters

f	The filter we are passing to
bb	The brigade to flush

ap_filter_adopt_brigade()

void ap_filter_adopt_brigade	(	ap_filter_t *	f,
		apr_bucket_brigade *	bb
	)

Adopt a bucket brigade as is (no setaside nor copy).

Parameters

f	The current filter
bb	The bucket brigade adopted. This brigade is always empty on return

Remarks

All buckets in bb should be allocated on f->c->pool and f->c->bucket_alloc.

ap_filter_flush()

apr_status_t ap_filter_flush	(	apr_bucket_brigade *	bb,
		void *	ctx
	)

Flush function for apr_brigade_* calls. This calls ap_pass_brigade to flush the brigade if the brigade buffer overflows.

Parameters

bb	The brigade to flush
ctx	The filter to pass the brigade to

Note

this function has nothing to do with FLUSH buckets. It is simply a way to flush content out of a brigade and down a filter stack.

ap_filter_input_pending()

int ap_filter_input_pending

(

conn_rec *

c

)

This function determines whether there is pending data in the input filters. Pending data is data that has been read from the underlying socket but not yet returned to the application.

Parameters

c	The connection.

Returns

If no pending data remains, this function returns DECLINED. If some pending data remains, this function returns OK.

ap_filter_output_pending()

int ap_filter_output_pending

(

conn_rec *

c

)

This function determines whether there is unwritten data in the output filters, and if so, attempts to make a single write to each filter with unwritten data.

Parameters

c	The connection.

Returns

If no unwritten data remains, this function returns DECLINED. If some unwritten data remains, this function returns OK. If any attempt to write data failed, this functions returns a positive integer.

ap_filter_prepare_brigade()

int ap_filter_prepare_brigade

(

ap_filter_t *

f

)

Prepare the filter to allow brigades to be set aside. This can be used within an input filter to allocate space to set aside data in the input filters, or can be used within an output filter by being called via ap_filter_setaside_brigade().

Parameters

f	The current filter

Returns

OK if a brigade was created, DECLINED otherwise.

ap_filter_protocol()

apr_status_t void ap_filter_protocol	(	ap_filter_t *	f,
		unsigned int	proto_flags
	)

set protocol requirements for an output content filter (only works with AP_FTYPE_RESOURCE and AP_FTYPE_CONTENT_SET)

Parameters

f	the filter in question
proto_flags	Logical OR of AP_FILTER_PROTO_* bits

ap_filter_reinstate_brigade()

apr_status_t ap_filter_reinstate_brigade	(	ap_filter_t *	f,
		apr_bucket_brigade *	bb,
		apr_bucket **	flush_upto
	)

Reinstate a brigade setaside earlier, and calculate the amount of data we should write based on the presence of flush buckets, size limits on in memory buckets, and the number of outstanding requests in the pipeline. This is a safety mechanism to protect against a module that might try generate data too quickly for downstream to handle without yielding as it should.

If the brigade passed in is empty, we reinstate the brigade and return immediately on the assumption that any buckets needing to be flushed were flushed before being passed to ap_filter_setaside_brigade().

Parameters

f	The current filter
bb	The bucket brigade to restore to.
flush_upto	Work out the bucket we need to flush up to, based on the presence of a flush bucket, size limits on in-memory buckets, size limits on the number of requests outstanding in the pipeline.

Returns

APR_SUCCESS.

ap_filter_setaside_brigade()

apr_status_t ap_filter_setaside_brigade	(	ap_filter_t *	f,
		apr_bucket_brigade *	bb
	)

Prepare a bucket brigade to be setaside, creating a dedicated pool if necessary within the filter to handle the lifetime of the setaside brigade.

Parameters

f	The current filter
bb	The bucket brigade to set aside. This brigade is always empty on return

ap_filter_should_yield()

int ap_filter_should_yield

(

ap_filter_t *

f

)

This function calculates whether there are any as yet unsent buffered brigades in downstream filters, and returns non zero if so.

A filter should use this to determine whether the passing of data downstream might block, and so defer the passing of brigades downstream with ap_filter_setaside_brigade().

This function can be called safely from a handler.

ap_fprintf()

apr_status_t ap_fprintf	(	ap_filter_t *	f,
		apr_bucket_brigade *	bb,
		const char *	fmt,
			...
	)

Output data to the filter in printf format

Parameters

f	the filter we are writing to
bb	The brigade to buffer into
fmt	The format string
...	The arguments to use to fill out the format string

ap_fputstrs()

apr_status_t ap_fputstrs	(	ap_filter_t *	f,
		apr_bucket_brigade *	bb,
			...
	)

Write an unspecified number of strings to the current filter

Parameters

f	the filter we are writing to
bb	The brigade to buffer into
...	The strings to write

ap_get_brigade()

apr_status_t ap_get_brigade	(	ap_filter_t *	filter,
		apr_bucket_brigade *	bucket,
		ap_input_mode_t	mode,
		apr_read_type_e	block,
		apr_off_t	readbytes
	)

Get the current bucket brigade from the next filter on the filter stack. The filter returns an apr_status_t value. If the bottom-most filter doesn't read from the network, then AP_NOBODY_READ is returned. The bucket brigade will be empty when there is nothing left to get.

Parameters

filter	The next filter in the chain
bucket	The current bucket brigade. The original brigade passed to ap_get_brigade() must be empty.
mode	The way in which the data should be read
block	How the operations should be performed APR_BLOCK_READ, APR_NONBLOCK_READ
readbytes	How many bytes to read from the next filter.

ap_get_input_filter_handle()

ap_filter_rec_t* ap_get_input_filter_handle

(

const char *

name

)

Returns the filter handle for use with ap_add_input_filter_handle.

Parameters

name	The filter name to look up

ap_get_output_filter_handle()

ap_filter_rec_t* ap_get_output_filter_handle

(

const char *

name

)

Returns the filter handle for use with ap_add_output_filter_handle.

Parameters

name	The filter name to look up

ap_pass_brigade()

apr_status_t ap_pass_brigade	(	ap_filter_t *	filter,
		apr_bucket_brigade *	bucket
	)

Pass the current bucket brigade down to the next filter on the filter stack. The filter returns an apr_status_t value. If the bottom-most filter doesn't write to the network, then AP_NOBODY_WROTE is returned.

Parameters

filter	The next filter in the chain
bucket	The current bucket brigade

Remarks

Ownership of the brigade is retained by the caller. On return, the contents of the brigade are UNDEFINED, and the caller must either call apr_brigade_cleanup or apr_brigade_destroy on the brigade.

ap_pass_brigade_fchk()

apr_status_t ap_pass_brigade_fchk	(	request_rec *	r,
		apr_bucket_brigade *	bucket,
		const char *	fmt,
			...
	)

Pass the current bucket brigade down to the next filter on the filter stack checking for filter errors. The filter returns an apr_status_t value. Returns OK if the brigade is successfully passed AP_FILTER_ERROR on a filter error HTTP_INTERNAL_SERVER_ERROR on all other errors

Parameters

r	The request rec
bucket	The current bucket brigade
fmt	The format string. If NULL defaults to "ap_pass_brigade returned"
...	The arguments to use to fill out the format string

Remarks

Ownership of the brigade is retained by the caller. On return, the contents of the brigade are UNDEFINED, and the caller must either call apr_brigade_cleanup or apr_brigade_destroy on the brigade.

ap_register_input_filter()

apr_status_t ap_filter_rec_t* ap_register_input_filter	(	const char *	name,
		ap_in_filter_func	filter_func,
		ap_init_filter_func	filter_init,
		ap_filter_type	ftype
	)

This function is used to register an input filter with the system. After this registration is performed, then a filter may be added into the filter chain by using ap_add_input_filter() and simply specifying the name.

Parameters

name	The name to attach to the filter function
filter_func	The filter function to name
filter_init	The function to call before the filter handlers are invoked
ftype	The type of filter function, either AP_FTYPE_CONTENT_SET or AP_FTYPE_CONNECTION

See also

add_input_filter()

ap_register_output_filter()

ap_filter_rec_t* ap_register_output_filter	(	const char *	name,
		ap_out_filter_func	filter_func,
		ap_init_filter_func	filter_init,
		ap_filter_type	ftype
	)

Deprecated:

See also

ap_register_output_filter_protocol

ap_register_output_filter_protocol()

ap_filter_rec_t* ap_register_output_filter_protocol	(	const char *	name,
		ap_out_filter_func	filter_func,
		ap_init_filter_func	filter_init,
		ap_filter_type	ftype,
		unsigned int	proto_flags
	)

This function is used to register an output filter with the system. After this registration is performed, then a filter may be added directly to the filter chain by using ap_add_output_filter() and simply specifying the name, or as a provider under mod_filter.

Parameters

name	The name to attach to the filter function
filter_func	The filter function to name
filter_init	The function to call before the filter handlers are invoked
ftype	The type of filter function, either AP_FTYPE_CONTENT_SET or AP_FTYPE_CONNECTION
proto_flags	Protocol flags: logical OR of AP_FILTER_PROTO_* bits

Returns

the filter rec

See also

ap_add_output_filter()

ap_release_brigade()

void ap_release_brigade	(	conn_rec *	c,
		apr_bucket_brigade *	bb
	)

Release and cleanup a brigade (created on the connection pool/alloc!).

Parameters

c	The connection
bb	The brigade

ap_remove_input_filter()

void ap_remove_input_filter

(

ap_filter_t *

f

)

Remove an input filter from either the request or connection stack it is associated with.

Parameters

f	The filter to remove

ap_remove_input_filter_byhandle()

apr_status_t ap_remove_input_filter_byhandle	(	ap_filter_t *	next,
		const char *	handle
	)

Remove an input filter from either the request or connection stack it is associated with.

Parameters

next	The filter stack to search
handle	The filter handle (name) to remove

Returns

APR_SUCCESS on removal or error

ap_remove_output_filter()

void ap_remove_output_filter

(

ap_filter_t *

f

)

Remove an output filter from either the request or connection stack it is associated with.

Parameters

f	The filter to remove

ap_remove_output_filter_byhandle()

apr_status_t ap_remove_output_filter_byhandle	(	ap_filter_t *	next,
		const char *	handle
	)

Remove an output filter from either the request or connection stack it is associated with.

Parameters

next	The filter stack to search
handle	The filter handle (name) to remove

Returns

APR_SUCCESS on removal or error

ap_save_brigade()

apr_status_t ap_save_brigade	(	ap_filter_t *	f,
		apr_bucket_brigade **	save_to,
		apr_bucket_brigade **	b,
		apr_pool_t *	p
	)

Prepare a bucket brigade to be setaside. If a different brigade was set-aside earlier, then the two brigades are concatenated together.

If *save_to is NULL, the brigade will be created, and a cleanup registered to clear the brigade address when the pool is destroyed.

Parameters

f	The current filter
save_to	The brigade that was previously set-aside. Regardless, the new bucket brigade is returned in this location.
b	The bucket brigade to save aside. This brigade is always empty on return
p	Ensure that all data in the brigade lives as long as this pool

Variable Documentation

ap_bucket_wc_data

AP_DECLARE_DATA const char ap_bucket_wc_data

extern

Write Completion (WC) bucket.

A WC bucket is a FLUSH bucket with special ->data == &ap_bucket_wc_data, still both AP_BUCKET_IS_WC() and APR_BUCKET_IS_FLUSH() hold for them so they have the same semantics for most filters, namely: Everything produced before shall be passed to the next filter, including the WC/FLUSH bucket itself. The distinction between WC and FLUSH buckets is only for filters that care about write completion (calling ap_filter_reinstate_brigade() with non-NULL flush_upto), those can setaside WC buckets and the preceding data provided they have first determined that the next filter(s) have pending data already, usually by calling ap_filter_should_yield(f->next). Write Completion (WC) bucket data mark