util_filter.h

Go to the documentation of this file.

/* Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
 
#ifndef AP_FILTER_H
#define AP_FILTER_H
 
#include "apr.h"
#include "apr_buckets.h"
 
#include "httpd.h"
 
#if APR_HAVE_STDARG_H
#include <stdarg.h>
#endif
 
#ifdef __cplusplus
extern "C" {
#endif
 
typedef enum {
    AP_MODE_READBYTES,
    AP_MODE_GETLINE,
    AP_MODE_EATCRLF,
    AP_MODE_SPECULATIVE,
    AP_MODE_EXHAUSTIVE,
    AP_MODE_INIT
} ap_input_mode_t;
 
/* forward declare the filter type */
typedef struct ap_filter_t ap_filter_t;
 
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_out_filter_func out_func;
    ap_in_filter_func in_func;
} ap_filter_func;
 
typedef enum {
    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
} ap_filter_type;
 
typedef enum {
    AP_FILTER_INPUT     = 1,
    AP_FILTER_OUTPUT    = 2,
} ap_filter_direction_e;
 
typedef struct ap_filter_rec_t ap_filter_rec_t;
typedef struct ap_filter_provider_t ap_filter_provider_t;
 
struct ap_filter_rec_t {
    const char *name;
 
    ap_filter_func filter_func;
 
    ap_init_filter_func filter_init_func;
 
    struct ap_filter_rec_t *next;
 
    ap_filter_provider_t *providers;
 
    ap_filter_type ftype;
 
    int debug;
 
    unsigned int proto_flags;
 
    ap_filter_direction_e direction;
};
 
struct ap_filter_private;
 
struct ap_filter_t {
    ap_filter_rec_t *frec;
 
    void *ctx;
 
    ap_filter_t *next;
 
    request_rec *r;
 
    conn_rec *c;
 
    struct ap_filter_private *priv;
};
 
struct ap_filter_conn_ctx;
 
AP_DECLARE(apr_bucket_brigade *) ap_acquire_brigade(conn_rec *c);
 
AP_DECLARE(void) ap_release_brigade(conn_rec *c, apr_bucket_brigade *bb);
 
AP_DECLARE(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);
 
AP_DECLARE(apr_status_t) ap_pass_brigade(ap_filter_t *filter,
                                         apr_bucket_brigade *bucket);
 
AP_DECLARE(apr_status_t) ap_pass_brigade_fchk(request_rec *r,
                                              apr_bucket_brigade *bucket,
                                              const char *fmt,
                                              ...)
                                              __attribute__((format(printf,3,4)));
 
AP_DECLARE(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_DECLARE(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);
 
/* For httpd-?.? I suggest replacing the above with
#define ap_register_output_filter(name,ffunc,init,ftype) \
             ap_register_output_filter_protocol(name,ffunc,init,ftype,0)
*/
 
AP_DECLARE(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_DECLARE(ap_filter_t *) ap_add_input_filter(const char *name, void *ctx,
                                              request_rec *r, conn_rec *c);
 
AP_DECLARE(ap_filter_t *) ap_add_input_filter_handle(ap_filter_rec_t *f,
                                                     void *ctx,
                                                     request_rec *r,
                                                     conn_rec *c);
 
AP_DECLARE(ap_filter_rec_t *) ap_get_input_filter_handle(const char *name);
 
AP_DECLARE(ap_filter_t *) ap_add_output_filter(const char *name, void *ctx,
                                               request_rec *r, conn_rec *c);
 
AP_DECLARE(ap_filter_t *) ap_add_output_filter_handle(ap_filter_rec_t *f,
                                                      void *ctx,
                                                      request_rec *r,
                                                      conn_rec *c);
 
AP_DECLARE(ap_filter_rec_t *) ap_get_output_filter_handle(const char *name);
 
AP_DECLARE(void) ap_remove_input_filter(ap_filter_t *f);
 
AP_DECLARE(void) ap_remove_output_filter(ap_filter_t *f);
 
AP_DECLARE(apr_status_t) ap_remove_input_filter_byhandle(ap_filter_t *next,
                                                         const char *handle);
AP_DECLARE(apr_status_t) ap_remove_output_filter_byhandle(ap_filter_t *next,
                                                          const char *handle);
 
/* 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.
 */
 
AP_DECLARE(apr_status_t) ap_save_brigade(ap_filter_t *f,
                                         apr_bucket_brigade **save_to,
                                         apr_bucket_brigade **b, apr_pool_t *p);
 
AP_DECLARE(int) ap_filter_prepare_brigade(ap_filter_t *f);
 
AP_DECLARE(apr_status_t) ap_filter_setaside_brigade(ap_filter_t *f,
                                                    apr_bucket_brigade *bb);
 
AP_DECLARE(apr_status_t) ap_filter_reinstate_brigade(ap_filter_t *f,
                                                     apr_bucket_brigade *bb,
                                                     apr_bucket **flush_upto);
 
AP_DECLARE(void) ap_filter_adopt_brigade(ap_filter_t *f,
                                         apr_bucket_brigade *bb);
 
AP_DECLARE(int) ap_filter_should_yield(ap_filter_t *f);
 
AP_DECLARE_NONSTD(int) ap_filter_output_pending(conn_rec *c);
 
AP_DECLARE_NONSTD(int) ap_filter_input_pending(conn_rec *c);
 
AP_DECLARE_NONSTD(apr_status_t) ap_filter_flush(apr_bucket_brigade *bb,
                                                void *ctx);
 
AP_DECLARE(apr_status_t) ap_fflush(ap_filter_t *f, apr_bucket_brigade *bb);
 
#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)
 
AP_DECLARE_NONSTD(apr_status_t) ap_fputstrs(ap_filter_t *f,
                                            apr_bucket_brigade *bb,
                                            ...)
                                AP_FN_ATTR_SENTINEL;
 
AP_DECLARE_NONSTD(apr_status_t) ap_fprintf(ap_filter_t *f,
                                           apr_bucket_brigade *bb,
                                           const char *fmt,
                                           ...)
        __attribute__((format(printf,3,4)));
 
AP_DECLARE(void) ap_filter_protocol(ap_filter_t* f, unsigned int proto_flags);
 
#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
 
AP_DECLARE_DATA extern const char ap_bucket_wc_data;
 
#define AP_BUCKET_IS_WC(e) (APR_BUCKET_IS_FLUSH(e) && \
                            (e)->data == (void *)&ap_bucket_wc_data)
 
AP_DECLARE(apr_bucket *) ap_bucket_wc_make(apr_bucket *b);
 
AP_DECLARE(apr_bucket *) ap_bucket_wc_create(apr_bucket_alloc_t *list);
 
#ifdef __cplusplus
}
#endif
 
#endif  /* !AP_FILTER_H */