/usr/src/redhat/BUILD/httpd-2.2.3/include/util_filter.h

Apache filter library [詳細]

#include "apr.h"
#include "apr_buckets.h"
#include "httpd.h"

ソースコードを見る。

データ構造
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. [詳細]
struct	ap_filter_t
	The representation of a filter chain. [詳細]
Filter callbacks
This function type is used for filter callbacks. It will be passed a pointer to "this" filter, and a "bucket" 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 structure (and all those referenced by ->next and ->prev) should be considered "const". The filter is allowed to modify the next/prev to insert/remove/replace elements in the bucket list, but the types and values of the individual buckets should not be altered. 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)
マクロ定義
#define	AP_NOBODY_WROTE   -1
#define	AP_NOBODY_READ   -2
#define	AP_FILTER_ERROR   -3
#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_puts(bb, ap_filter_flush, f, 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
型定義
typedef ap_filter_t	ap_filter_t
typedef ap_filter_rec_t	ap_filter_rec_t
typedef ap_filter_provider_t	ap_filter_provider_t
列挙型
enum	ap_input_mode_t {   AP_MODE_READBYTES, AP_MODE_GETLINE, AP_MODE_EATCRLF, AP_MODE_SPECULATIVE,   AP_MODE_EXHAUSTIVE, AP_MODE_INIT }
	input filtering modes [詳細]
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 }
関数
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)
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_save_brigade (ap_filter_t *f, apr_bucket_brigade **save_to, apr_bucket_brigade **b, apr_pool_t *p)
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,...)
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)

---

説明

Apache filter library

---

マクロ定義

#define AP_FILTER_ERROR   -3

Returned when??

バグ:

find out when!

#define AP_FILTER_PROTO_CHANGE   0x1

Filter changes contents (so invalidating checksums/etc)

#define AP_FILTER_PROTO_CHANGE_LENGTH   0x2

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

#define AP_FILTER_PROTO_NO_BYTERANGE   0x4

Filter requires complete input and can't work on byteranges

#define AP_FILTER_PROTO_NO_CACHE   0x10

Filter makes output non-cacheable

#define AP_FILTER_PROTO_NO_PROXY   0x8

Filter should not run in a proxy

#define AP_FILTER_PROTO_TRANSFORM   0x20

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

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

引数:

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

#define ap_fputs	(	f,
		bb,
		str		)	apr_brigade_puts(bb, ap_filter_flush, f, str)

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

引数:

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

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

引数:

	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

#define AP_NOBODY_READ   -2

Returned by the bottom-most filter if no data was read.

参照:

ap_get_brigade().

#define AP_NOBODY_WROTE   -1

Returned by the bottom-most filter if no data was written.

参照:

ap_pass_brigade().

---

型定義

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.

---

列挙型

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().

列挙型の値:

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.

enum ap_input_mode_t

input filtering modes

列挙型の値:

AP_MODE_READBYTES	The filter should return at most readbytes data.
AP_MODE_GETLINE	The filter should return at most one line of CRLF data. (If a potential line is too long or no CRLF is found, the filter may return partial data).
AP_MODE_EATCRLF	The filter should implicitly eat any CRLF pairs that it sees.
AP_MODE_SPECULATIVE	The filter read should be treated as speculative and any returned data should be stored for later retrieval in another mode.
AP_MODE_EXHAUSTIVE	The filter read should be exhaustive and read until it can not read any more. Use this mode with extreme caution.
AP_MODE_INIT	The filter should initialize the connection if needed, NNTP or FTP over SSL for example.

---

関数

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.

引数:

	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_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

引数:

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

引数:

	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

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

引数:

	f	The filter handle to add
	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

apr_status_t ap_fflush	(	ap_filter_t *	f,
		apr_bucket_brigade *	bb
	)

Flush the current brigade down the filter stack.

引数:

	f	The filter we are passing to
	bb	The brigade to 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.

引数:

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

覚え書き:

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.

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)

引数:

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

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

Output data to the filter in printf format

引数:

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

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

Write an unspecified number of strings to the current filter

引数:

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

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.

引数:

	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_filter_rec_t* ap_get_input_filter_handle

(

const char *

name

)

Returns the filter handle for use with ap_add_input_filter_handle.

引数:

name

The filter name to look up

ap_filter_rec_t* ap_get_output_filter_handle

(

const char *

name

)

Returns the filter handle for use with ap_add_output_filter_handle.

引数:

name

The filter name to look up

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. The caller relinquishes ownership of the brigade.

引数:

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

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.

引数:

	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 or AP_FTYPE_CONNECTION

参照:

add_input_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
	)

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 specifying the name. It may also be used as a provider under mod_filter. This is (equivalent to) ap_register_output_filter_protocol with proto_flags=0, and is retained for back-compatibility with 2.0 modules.

引数:

	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 or AP_FTYPE_CONNECTION

参照:

ap_add_output_filter()

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 into the filter chain by using ap_add_output_filter() and simply specifying the name. It may also be used as a provider under mod_filter.

引数:

	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 or AP_FTYPE_CONNECTION
	proto_flags	Protocol flags: logical OR of AP_FILTER_PROTO_* bits

参照:

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

引数:

f

The filter to remove

void ap_remove_output_filter

(

ap_filter_t *

f

)

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

引数:

f

The filter to remove

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.

引数:

	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

---