granicus.if.org Git - apache/blob - modules/apreq/apreq_module_apache2.h

   1 /*
   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
   8 **
   9 **      http://www.apache.org/licenses/LICENSE-2.0
  10 **
  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.
  16 */
  17
  18 #ifndef APREQ_APACHE2_H
  19 #define APREQ_APACHE2_H
  20
  21 #include "apreq_module.h"
  22 #include "apr_optional.h"
  23 #include <httpd.h>
  24
  25 #ifdef  __cplusplus
  26  extern "C" {
  27 #endif
  28
  29
  30 /**
  31  * @defgroup mod_apreq2 Apache 2.X Filter Module
  32  * @ingroup APACHE_MODS
  33  * @brief mod_apreq2 - DSO that ties libapreq2 to Apache HTTPD 2.X.
  34  *
  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.
  40  *
  41  * <hr>
  42  *
  43  * <h2>Activating mod_apreq2 in Apache 2.X</h2>
  44  *
  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.
  50  *
  51  * @code
  52  *
  53  *     LoadModule apreq_module    modules/mod_apreq2.so
  54  *
  55  * @endcode
  56  *
  57  * The mod_apreq2 filter is named "apreq2", and may be used in Apache's
  58  * input filter directives, e.g.
  59  * @code
  60  *
  61  *     AddInputFilter apreq2         # or
  62  *     SetInputFilter apreq2
  63  *
  64  * @endcode
  65  *
  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
  72  * data.
  73  *
  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
  79  * active.
  80  *
  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).
  87  *
  88  *
  89  * <H2>Server Configuration Directives</H2>
  90  *
  91  * <TABLE class="qref">
  92  *   <CAPTION>Per-directory commands for mod_apreq2</CAPTION>
  93  *   <TR>
  94  *     <TH>Directive</TH>
  95  *     <TH>Context</TH>
  96  *     <TH>Default</TH><TH>Description</TH>
  97  *   </TR>
  98  *   <TR class="odd">
  99  *     <TD>APREQ2_ReadLimit</TD>
 100  *     <TD>directory</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.
 105  *     </TD>
 106  *   </TR>
 107  *   <TR>
 108  *     <TD>APREQ2_BrigadeLimit</TD>
 109  *     <TD>directory</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.
 114  *     </TD>
 115  *   </TR>
 116  *   <TR class="odd">
 117  *     <TD>APREQ2_TempDir</TD>
 118  *     <TD>directory</TD>
 119  *     <TD>NULL</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().
 124  *     </TD>
 125  *  </TR>
 126  * </TABLE>
 127  *
 128  * <H2>Implementation Details</H2>
 129  * <PRE>
 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
 134  * </PRE>
 135  *
 136  * @{
 137  */
 138 /**
 139  * Create an apreq handle which communicates with an Apache 2.X
 140  * request_rec.
 141  */
 142 APREQ_DECLARE(apreq_handle_t *) apreq_handle_apache2(request_rec *r);
 143
 144 /**
 145  *
 146  *
 147  */
 148 #ifdef WIN32
 149 typedef __declspec(dllexport) apreq_handle_t *
 150 (__stdcall apr_OFN_apreq_handle_apache2_t) (request_rec *r);
 151 #else
 152 APR_DECLARE_OPTIONAL_FN(APREQ_DECLARE(apreq_handle_t *),
 153                         apreq_handle_apache2, (request_rec *r));
 154 #endif
 155
 156 /**
 157  * The mod_apreq2 filter is named "apreq2", and may be used in Apache's
 158  * input filter directives, e.g.
 159  * @code
 160  *
 161  *     AddInputFilter apreq2         # or
 162  *     SetInputFilter apreq2
 163  * @endcode
 164  * See above
 165  */
 166 #define APREQ_FILTER_NAME "apreq2"
 167
 168 /**
 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
 172  * @see APREQ_MODULE
 173  */
 174 #define APREQ_APACHE2_MMN 20101207
 175
 176 /** @} */
 177
 178 #ifdef __cplusplus
 179  }
 180 #endif
 181
 182 #endif