Apache2
 All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
util_filter.h File Reference

Apache filter library. More...

#include "apr.h"
#include "apr_buckets.h"
#include "httpd.h"
Include dependency graph for util_filter.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

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
 

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

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
}
 
enum  ap_filter_direction_e { AP_FILTER_INPUT = 1, AP_FILTER_OUTPUT = 2 }
 

Functions

typedef APR_RING_HEAD (ap_filter_ring, ap_filter_t) ap_filter_ring_t
 The representation of a filters' ring. More...
 
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_tap_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_tap_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_tap_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_tap_add_input_filter (const char *name, void *ctx, request_rec *r, conn_rec *c)
 
ap_filter_tap_add_input_filter_handle (ap_filter_rec_t *f, void *ctx, request_rec *r, conn_rec *c)
 
ap_filter_rec_tap_get_input_filter_handle (const char *name)
 
ap_filter_tap_add_output_filter (const char *name, void *ctx, request_rec *r, conn_rec *c)
 
ap_filter_tap_add_output_filter_handle (ap_filter_rec_t *f, void *ctx, request_rec *r, conn_rec *c)
 
ap_filter_rec_tap_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_pool_t **p)
 
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)
 
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)
 

Detailed Description

Apache filter library.

Enumeration Type Documentation

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.