Main Page | Modules | Namespace List | Class List | Directories | File List | Class Members | File Members | Related Pages | Examples
include

util_filter.h File Reference

Apache filter library. More...

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

Go to the source code of this file.

Classes

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

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)
typedef ap_filter_func ap_filter_func
apr_bucket_brigade AP_DECLARE_NONSTD (apr_status_t) ap_fprintf(ap_filter_t *f

Defines

#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

Typedefs

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

Enumerations

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 More...
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
}

Functions

 AP_DECLARE (apr_status_t) ap_get_brigade(ap_filter_t *filter
apr_bucket_brigade apr_bucket_brigade
const char 		__attribute__ ((format(printf, 3, 4)))

Variables

apr_bucket_brigade * bucket
apr_bucket_brigade ap_input_mode_t mode
apr_bucket_brigade ap_input_mode_t
apr_read_type_e 		block
apr_bucket_brigade ap_input_mode_t
apr_read_type_e apr_off_t 		readbytes
ap_in_filter_func filter_func
ap_in_filter_func ap_init_filter_func filter_init
ap_in_filter_func ap_init_filter_func
ap_filter_type 		ftype
ap_out_filter_func ap_init_filter_func
ap_filter_type unsigned int 		proto_flags
void * ctx
void request_rec * r
void request_rec conn_rec * c
apr_bucket_brigade ** save_to
apr_bucket_brigade apr_bucket_brigade ** b
apr_bucket_brigade apr_bucket_brigade
apr_pool_t * 		p
apr_bucket_brigade * bb
apr_bucket_brigade apr_bucket_brigade
const char * 		fmt

Detailed Description

Apache filter library.

Definition in file util_filter.h.

Define Documentation

#define AP_FILTER_ERROR   -3
 

Returned when??

Bug:
find out when!

Definition at line 45 of file util_filter.h.

Referenced by AP_CORE_DECLARE_NONSTD(), AP_DECLARE(), APR_OPTIONAL_FN_TYPE(), and ssl_io_filter_Upgrade().

#define AP_FILTER_PROTO_CHANGE   0x1
 

Filter changes contents (so invalidating checksums/etc)

Definition at line 573 of file util_filter.h.

Referenced by filter_lookup(), and filter_protocol().

#define AP_FILTER_PROTO_CHANGE_LENGTH   0x2
 

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

Definition at line 576 of file util_filter.h.

Referenced by filter_insert(), filter_lookup(), and filter_protocol().

#define AP_FILTER_PROTO_NO_BYTERANGE   0x4
 

Filter requires complete input and can't work on byteranges

Definition at line 579 of file util_filter.h.

Referenced by filter_insert(), filter_lookup(), and filter_protocol().

#define AP_FILTER_PROTO_NO_CACHE   0x10
 

Filter makes output non-cacheable

Definition at line 585 of file util_filter.h.

Referenced by filter_lookup(), and filter_protocol().

#define AP_FILTER_PROTO_NO_PROXY   0x8
 

Filter should not run in a proxy

Definition at line 582 of file util_filter.h.

Referenced by filter_harness(), filter_lookup(), and filter_protocol().

#define AP_FILTER_PROTO_TRANSFORM   0x20
 

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

Definition at line 588 of file util_filter.h.

Referenced by filter_harness(), filter_lookup(), and filter_protocol().

#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

Definition at line 538 of file util_filter.h.

Referenced by dav_send_one_response().

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

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

Definition at line 529 of file util_filter.h.

Referenced by dav_begin_multistatus(), dav_finish_multistatus(), and dav_send_one_response().

#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

Definition at line 520 of file util_filter.h.

Referenced by buffer_output().

#define AP_NOBODY_READ   -2
 

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

See also:
ap_get_brigade().

Definition at line 43 of file util_filter.h.

Referenced by AP_DECLARE().

#define AP_NOBODY_WROTE   -1
 

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

See also:
ap_pass_brigade().

Definition at line 40 of file util_filter.h.

Typedef Documentation

typedef union ap_filter_func ap_filter_func
 

typedef struct ap_filter_provider_t ap_filter_provider_t
 

Definition at line 202 of file util_filter.h.

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.

Definition at line 201 of file util_filter.h.

typedef struct ap_filter_t ap_filter_t
 

Definition at line 101 of file util_filter.h.

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)
 

Definition at line 138 of file util_filter.h.

typedef int(* ap_init_filter_func)(ap_filter_t *f)
 

Definition at line 143 of file util_filter.h.

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

Definition at line 136 of file util_filter.h.

Enumeration Type Documentation

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.

Definition at line 160 of file util_filter.h.

00160              {
00163     AP_FTYPE_RESOURCE     = 10,
00167     AP_FTYPE_CONTENT_SET  = 20,
00170     AP_FTYPE_PROTOCOL     = 30,
00172     AP_FTYPE_TRANSCODE    = 40,
00182     AP_FTYPE_CONNECTION  = 50,
00185     AP_FTYPE_NETWORK     = 60
00186 } ap_filter_type;

enum ap_input_mode_t
 

input filtering modes

Enumerator:
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.

Definition at line 50 of file util_filter.h.

00050              {
00052     AP_MODE_READBYTES,
00057     AP_MODE_GETLINE,
00059     AP_MODE_EATCRLF,
00062     AP_MODE_SPECULATIVE,
00067     AP_MODE_EXHAUSTIVE,
00071     AP_MODE_INIT
00072 } ap_input_mode_t;

Function Documentation

apr_bucket_brigade apr_bucket_brigade const char __attribute__ (  (format(printf, 3, 4))   ) 
 

Variable Documentation

apr_bucket_brigade apr_bucket_brigade** b
 

Definition at line 492 of file util_filter.h.

apr_bucket_brigade apr_bucket_brigade* bb
 

Definition at line 559 of file util_filter.h.

apr_bucket_brigade ap_input_mode_t apr_read_type_e block
 

Definition at line 296 of file util_filter.h.

apr_bucket_brigade * bucket
 

Definition at line 310 of file util_filter.h.

Referenced by add_client(), AP_DECLARE(), APR_OPTIONAL_FN_TYPE(), bio_filter_out_write(), cgi_handler(), cgid_handler(), find_ipaddr(), get_client(), ssl_io_filter_error(), ssl_io_filter_input(), ssl_io_filter_output(), and xlate_brigade().

void request_rec conn_rec* c
 

Definition at line 441 of file util_filter.h.

ap_out_filter_func filter_func
 

Definition at line 374 of file util_filter.h.

ap_out_filter_func ap_init_filter_func filter_init
 

Definition at line 374 of file util_filter.h.

Referenced by filter_declare(), and filter_init().

apr_bucket_brigade apr_bucket_brigade const char* fmt
 

Definition at line 559 of file util_filter.h.

ap_out_filter_func ap_init_filter_func ap_filter_type ftype
 

Definition at line 374 of file util_filter.h.

unsigned int proto_flags
 

Definition at line 570 of file util_filter.h.

Referenced by filter_lookup().

void request_rec* r
 

Definition at line 441 of file util_filter.h.

apr_bucket_brigade ap_input_mode_t apr_read_type_e apr_off_t readbytes
 

Definition at line 296 of file util_filter.h.

Referenced by ap_proxy_http_process_response(), and proxy_ftp_handler().

apr_bucket_brigade** save_to
 

Definition at line 492 of file util_filter.h.

© sourcejam.com 2005-2008