2 ** Licensed to the Apache Software Foundation (ASF) under one or more
3 ** contributor license agreements. See the NOTICE file distributed with
4 ** this work for additional information regarding copyright ownership.
5 ** The ASF licenses this file to You under the Apache License, Version 2.0
6 ** (the "License"); you may not use this file except in compliance with
7 ** the License. You may obtain a copy of the License at
9 ** http://www.apache.org/licenses/LICENSE-2.0
11 ** Unless required by applicable law or agreed to in writing, software
12 ** distributed under the License is distributed on an "AS IS" BASIS,
13 ** WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 ** See the License for the specific language governing permissions and
15 ** limitations under the License.
18 #ifndef APREQ_APACHE2_H
19 #define APREQ_APACHE2_H
21 #include "apreq_module.h"
22 #include "apr_optional.h"
31 * @defgroup mod_apreq2 Apache 2.X Filter Module
32 * @ingroup apreq_module
33 * @brief mod_apreq2 - DSO that ties libapreq2 to Apache HTTPD 2.X.
35 * mod_apreq2 provides the "APREQ2" input filter for using libapreq2
36 * (and allow its parsed data structures to be shared) within
37 * the Apache 2.X webserver. Using it, libapreq2 works properly
38 * in every phase of the HTTP request, from translation handlers
39 * to output filters, and even for subrequests / internal redirects.
43 * <h2>Activating mod_apreq2 in Apache 2.X</h2>
45 * The installation process triggered by
46 * <code>% make install</code>
47 * <em>will not modify your webserver's config file</em>. Hence,
48 * be sure you activate it on startup by adding a LoadModule directive
49 * to your webserver config; e.g.
53 * LoadModule apreq_module modules/mod_apreq2.so
57 * The mod_apreq2 filter is named "apreq2", and may be used in Apache's
58 * input filter directives, e.g.
61 * AddInputFilter apreq2 # or
62 * SetInputFilter apreq2
66 * However, this is not required because libapreq2 will add the filter (only)
67 * if it's necessary. You just need to ensure that your module invokes
68 * apreq_handle_apache2() <em>before the content handler ultimately reads
69 * from the input filter chain</em>. It is important to realize that no
70 * matter how the input filters are initially arranged, the APREQ2 filter
71 * will attempt to reposition itself to be the last input filter to read the
74 * If you want to use other input filters to transform the incoming HTTP
75 * request data, is important to register those filters with Apache
76 * as having type AP_FTYPE_CONTENT_SET or AP_FTYPE_RESOURCE. Due to the
77 * limitations of Apache's current input filter design, types higher than
78 * AP_FTYPE_CONTENT_SET may not work properly whenever the apreq filter is
81 * This is especially true when a content handler uses libapreq2 to parse
82 * some of the post data before doing an internal redirect. Any input
83 * filter subsequently added to the redirected request will bypass the
84 * original apreq filter (and therefore lose access to some of the original
85 * post data), unless its type is less than the type of the apreq filter
86 * (currently AP_FTYPE_PROTOCOL-1).
89 * <H2>Server Configuration Directives</H2>
91 * <TABLE class="qref">
92 * <CAPTION>Per-directory commands for mod_apreq2</CAPTION>
96 * <TH>Default</TH><TH>Description</TH>
99 * <TD>APREQ2_ReadLimit</TD>
101 * <TD> #APREQ_DEFAULT_READ_LIMIT </TD>
102 * <TD> Maximum number of bytes mod_apreq2 will send off to libapreq2
103 * for parsing. mod_apreq2 will log this event and subsequently
104 * remove itself from the filter chain.
108 * <TD>APREQ2_BrigadeLimit</TD>
110 * <TD>#APREQ_DEFAULT_BRIGADE_LIMIT</TD>
111 * <TD> Maximum number of bytes mod_apreq2 will let accumulate
112 * within the heap-buckets in a brigade. Excess data will be
113 * spooled to an appended file bucket.
117 * <TD>APREQ2_TempDir</TD>
120 * <TD> Sets the location of the temporary directory apreq will use to spool
121 * overflow brigade data (based on the APREQ2_BrigadeLimit setting).
122 * If left unset, libapreq2 will select a platform-specific location
123 * via apr_temp_dir_get().
128 * <H2>Implementation Details</H2>
130 * XXX apreq as a normal input filter
131 * XXX apreq as a "virtual" content handler.
132 * XXX apreq as a transparent "tee".
133 * XXX apreq parser registration in post_config
139 * Create an apreq handle which communicates with an Apache 2.X
142 APREQ_DECLARE(apreq_handle_t *) apreq_handle_apache2(request_rec *r);
149 typedef __declspec(dllexport) apreq_handle_t *
150 (__stdcall apr_OFN_apreq_handle_apache2_t) (request_rec *r);
152 APR_DECLARE_OPTIONAL_FN(APREQ_DECLARE(apreq_handle_t *),
153 apreq_handle_apache2, (request_rec *r));
157 * The mod_apreq2 filter is named "apreq2", and may be used in Apache's
158 * input filter directives, e.g.
161 * AddInputFilter apreq2 # or
162 * SetInputFilter apreq2
166 #define APREQ_FILTER_NAME "apreq2"
169 * The Apache2 Module Magic Number for use in the Apache 2.x module structures
170 * This gets bumped if changes in th4e API will break third party applications
171 * using this apache2 module
174 #define APREQ_APACHE2_MMN 20101207