1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
|
/*
** 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 APREQ_APACHE2_H
#define APREQ_APACHE2_H
#include "apreq_module.h"
#include "apr_optional.h"
#include <httpd.h>
#ifdef __cplusplus
extern "C" {
#endif
/**
* @defgroup mod_apreq2 Apache 2.X Filter Module
* @ingroup apreq_module
* @brief mod_apreq2 - DSO that ties libapreq2 to Apache HTTPD 2.X.
*
* mod_apreq2 provides the "APREQ2" input filter for using libapreq2
* (and allow its parsed data structures to be shared) within
* the Apache 2.X webserver. Using it, libapreq2 works properly
* in every phase of the HTTP request, from translation handlers
* to output filters, and even for subrequests / internal redirects.
*
* <hr>
*
* <h2>Activating mod_apreq2 in Apache 2.X</h2>
*
* The installation process triggered by
* <code>% make install</code>
* <em>will not modify your webserver's config file</em>. Hence,
* be sure you activate it on startup by adding a LoadModule directive
* to your webserver config; e.g.
*
* @code
*
* LoadModule apreq_module modules/mod_apreq2.so
*
* @endcode
*
* The mod_apreq2 filter is named "apreq2", and may be used in Apache's
* input filter directives, e.g.
* @code
*
* AddInputFilter apreq2 # or
* SetInputFilter apreq2
*
* @endcode
*
* However, this is not required because libapreq2 will add the filter (only)
* if it's necessary. You just need to ensure that your module invokes
* apreq_handle_apache2() <em>before the content handler ultimately reads
* from the input filter chain</em>. It is important to realize that no
* matter how the input filters are initially arranged, the APREQ2 filter
* will attempt to reposition itself to be the last input filter to read the
* data.
*
* If you want to use other input filters to transform the incoming HTTP
* request data, is important to register those filters with Apache
* as having type AP_FTYPE_CONTENT_SET or AP_FTYPE_RESOURCE. Due to the
* limitations of Apache's current input filter design, types higher than
* AP_FTYPE_CONTENT_SET may not work properly whenever the apreq filter is
* active.
*
* This is especially true when a content handler uses libapreq2 to parse
* some of the post data before doing an internal redirect. Any input
* filter subsequently added to the redirected request will bypass the
* original apreq filter (and therefore lose access to some of the original
* post data), unless its type is less than the type of the apreq filter
* (currently AP_FTYPE_PROTOCOL-1).
*
*
* <H2>Server Configuration Directives</H2>
*
* <TABLE class="qref">
* <CAPTION>Per-directory commands for mod_apreq2</CAPTION>
* <TR>
* <TH>Directive</TH>
* <TH>Context</TH>
* <TH>Default</TH><TH>Description</TH>
* </TR>
* <TR class="odd">
* <TD>APREQ2_ReadLimit</TD>
* <TD>directory</TD>
* <TD> #APREQ_DEFAULT_READ_LIMIT </TD>
* <TD> Maximum number of bytes mod_apreq2 will send off to libapreq2
* for parsing. mod_apreq2 will log this event and subsequently
* remove itself from the filter chain.
* </TD>
* </TR>
* <TR>
* <TD>APREQ2_BrigadeLimit</TD>
* <TD>directory</TD>
* <TD>#APREQ_DEFAULT_BRIGADE_LIMIT</TD>
* <TD> Maximum number of bytes mod_apreq2 will let accumulate
* within the heap-buckets in a brigade. Excess data will be
* spooled to an appended file bucket.
* </TD>
* </TR>
* <TR class="odd">
* <TD>APREQ2_TempDir</TD>
* <TD>directory</TD>
* <TD>NULL</TD>
* <TD> Sets the location of the temporary directory apreq will use to spool
* overflow brigade data (based on the APREQ2_BrigadeLimit setting).
* If left unset, libapreq2 will select a platform-specific location
* via apr_temp_dir_get().
* </TD>
* </TR>
* </TABLE>
*
* <H2>Implementation Details</H2>
* <PRE>
* XXX apreq as a normal input filter
* XXX apreq as a "virtual" content handler.
* XXX apreq as a transparent "tee".
* XXX apreq parser registration in post_config
* </PRE>
*
* @{
*/
/**
* Create an apreq handle which communicates with an Apache 2.X
* request_rec.
*/
APREQ_DECLARE(apreq_handle_t *) apreq_handle_apache2(request_rec *r);
/**
*
*
*/
#ifdef WIN32
typedef __declspec(dllexport) apreq_handle_t *
(__stdcall apr_OFN_apreq_handle_apache2_t) (request_rec *r);
#else
APR_DECLARE_OPTIONAL_FN(APREQ_DECLARE(apreq_handle_t *),
apreq_handle_apache2, (request_rec *r));
#endif
/**
* The mod_apreq2 filter is named "apreq2", and may be used in Apache's
* input filter directives, e.g.
* @code
*
* AddInputFilter apreq2 # or
* SetInputFilter apreq2
* @endcode
* See above
*/
#define APREQ_FILTER_NAME "apreq2"
/**
* The Apache2 Module Magic Number for use in the Apache 2.x module structures
* This gets bumped if changes in th4e API will break third party applications
* using this apache2 module
* @see APREQ_MODULE
*/
#define APREQ_APACHE2_MMN 20101207
/** @} */
#ifdef __cplusplus
}
#endif
#endif
|
