content/apreq/docs/libapreq2/group__mod__apreq2.html - httpd-site - Git at Google

 <html>
 <head>
   <link rel="stylesheet" type="text/css" href="dox.css" />
   <title>libapreq2-2.13: libapreq2: Apache 2.X Filter Module</title>
 </head>
 <body>
 <div id="page-header">
 <p class="menu">
    <a href="http://www.apache.org/">Apache Software Foundation</a> &gt; <a href="http://httpd.apache.org">HTTP Server Project</a> &gt;
 <a href="http://httpd.apache.org/apreq/">Request Library Subproject</a></p>
 <p class="apache">Apache HTTP Server Request Library</p>
 <img alt="" src="feather.gif" /></div>
 <!-- Generated by Doxygen 1.5.6 -->
 <div class="navigation" id="top">
   <div class="tabs">
     <ul>
       <li><a href="index.html"><span>Main&nbsp;Page</span></a></li>
       <li><a href="pages.html"><span>Related&nbsp;Pages</span></a></li>
       <li><a href="modules.html"><span>Modules</span></a></li>
       <li><a href="annotated.html"><span>Data&nbsp;Structures</span></a></li>
       <li><a href="files.html"><span>Files</span></a></li>
       <li><a href="examples.html"><span>Examples</span></a></li>
     </ul>
   </div>
 </div>
 <div class="contents">
 <h1>Apache 2.X Filter Module<br>
 <small>
 [<a class="el" href="group__apreq__module.html">Modules</a>]</small>
 </h1>mod_apreq2 - DSO that ties libapreq2 to <a class="elRef" doxygen="apu.tag:http://apr.apache.org/docs/apr-util/1.3/" href="http://apr.apache.org/docs/apr-util/1.3/namespace_apache.html">Apache</a> HTTPD 2.X.
 <a href="#_details">More...</a><table border="0" cellpadding="0" cellspacing="0">
 <tr><td></td></tr>
 <tr><td colspan="2"><br><h2>Defines</h2></td></tr>
 <tr><td class="memItemLeft" nowrap align="right" valign="top">#define&nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__mod__apreq2.html#g4b67634b709506e4912f86ebda448504">APREQ_FILTER_NAME</a>&nbsp;&nbsp;&nbsp;&quot;apreq2&quot;</td></tr>

 <tr><td class="memItemLeft" nowrap align="right" valign="top">#define&nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__mod__apreq2.html#gab4a3c4b04f2aee2e17b648da09463b0">APREQ_APACHE2_MMN</a>&nbsp;&nbsp;&nbsp;20090110</td></tr>

 <tr><td colspan="2"><br><h2>Functions</h2></td></tr>
 <tr><td class="memItemLeft" nowrap align="right" valign="top"><a class="el" href="structapreq__handle__t.html">apreq_handle_t</a> *&nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__mod__apreq2.html#g68f508b2e1d9909328d7b1277ce4aa80">apreq_handle_apache2</a> (request_rec *r)</td></tr>

 <tr><td class="memItemLeft" nowrap align="right" valign="top"><a class="anchor" name="g082ed084cdc19fb048e87c9c1b4989dc"></a><!-- doxytag: member="mod_apreq2::APR_DECLARE_OPTIONAL_FN" ref="g082ed084cdc19fb048e87c9c1b4989dc" args="(apreq_handle_t *, apreq_handle_apache2,(request_rec *r))" -->
 &nbsp;</td><td class="memItemRight" valign="bottom"><b>APR_DECLARE_OPTIONAL_FN</b> (<a class="el" href="structapreq__handle__t.html">apreq_handle_t</a> *, apreq_handle_apache2,(request_rec *r))</td></tr>

 </table>
 <hr><a name="_details"></a><h2>Detailed Description</h2>
 mod_apreq2 - DSO that ties libapreq2 to <a class="elRef" doxygen="apu.tag:http://apr.apache.org/docs/apr-util/1.3/" href="http://apr.apache.org/docs/apr-util/1.3/namespace_apache.html">Apache</a> HTTPD 2.X.
 <p>
 mod_apreq2 provides the "APREQ2" input filter for using libapreq2 (and allow its parsed data structures to be shared) within the <a class="elRef" doxygen="apu.tag:http://apr.apache.org/docs/apr-util/1.3/" href="http://apr.apache.org/docs/apr-util/1.3/namespace_apache.html">Apache</a> 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.<p>
 <hr>
 <p>
 <h2>Activating mod_apreq2 in <a class="elRef" doxygen="apu.tag:http://apr.apache.org/docs/apr-util/1.3/" href="http://apr.apache.org/docs/apr-util/1.3/namespace_apache.html">Apache</a> 2.X</h2>
 <p>
 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.<p>
 <div class="fragment"><pre class="fragment">     LoadModule apreq_module    modules/mod_apreq2.so
 </pre></div><p>
 The mod_apreq2 filter is named "apreq2", and may be used in Apache's input filter directives, e.g. <div class="fragment"><pre class="fragment">     AddInputFilter apreq2         # or
      SetInputFilter apreq2
 </pre></div><p>
 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 <a class="el" href="group__mod__apreq2.html#g68f508b2e1d9909328d7b1277ce4aa80">apreq_handle_apache2()</a> <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.<p>
 If you want to use other input filters to transform the incoming HTTP request data, is important to register those filters with <a class="elRef" doxygen="apu.tag:http://apr.apache.org/docs/apr-util/1.3/" href="http://apr.apache.org/docs/apr-util/1.3/namespace_apache.html">Apache</a> 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.<p>
 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).<p>
 <h2>Server Configuration Directives</h2>
 <p>
 <table class="qref" border="1" cellspacing="3" cellpadding="3">
 <caption align="bottom">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><a class="el" href="apreq_8h.html#744fa55285c4a3868a9154f473d58ac4">APREQ_DEFAULT_READ_LIMIT</a>  </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><a class="el" href="apreq_8h.html#f54c8645b8266fa7c9b2e261c608744f">APREQ_DEFAULT_BRIGADE_LIMIT</a> </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 <a class="elRef" doxygen="apr.tag:http://apr.apache.org/docs/apr/1.3/" href="http://apr.apache.org/docs/apr/1.3/group__apr__file__io.html#g5cc19828a668c362be0ad7a12b805cc0">apr_temp_dir_get()</a>.   </td></tr>
 </table>
 <p>
 <h2>Implementation Details</h2>
 <p>
 <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> <hr><h2>Define Documentation</h2>
 <a class="anchor" name="gab4a3c4b04f2aee2e17b648da09463b0"></a><!-- doxytag: member="apreq_module_apache2.h::APREQ_APACHE2_MMN" ref="gab4a3c4b04f2aee2e17b648da09463b0" args="" -->
 <div class="memitem">
 <div class="memproto">
       <table class="memname">
         <tr>
           <td class="memname">#define APREQ_APACHE2_MMN&nbsp;&nbsp;&nbsp;20090110          </td>
         </tr>
       </table>
 </div>
 <div class="memdoc">

 <p>
 The Apache2 Module Magic Number for use in the <a class="elRef" doxygen="apu.tag:http://apr.apache.org/docs/apr-util/1.3/" href="http://apr.apache.org/docs/apr-util/1.3/namespace_apache.html">Apache</a> 2.x module structures This gets bumped if changes in th4e API will break third party applications using this apache2 module <dl class="see" compact><dt><b>See also:</b></dt><dd><a class="el" href="apreq__module_8h.html#7d6d0550f527e18c8cfab702e65daf3b">APREQ_MODULE</a> </dd></dl>

 </div>
 </div><p>
 <a class="anchor" name="g4b67634b709506e4912f86ebda448504"></a><!-- doxytag: member="apreq_module_apache2.h::APREQ_FILTER_NAME" ref="g4b67634b709506e4912f86ebda448504" args="" -->
 <div class="memitem">
 <div class="memproto">
       <table class="memname">
         <tr>
           <td class="memname">#define APREQ_FILTER_NAME&nbsp;&nbsp;&nbsp;&quot;apreq2&quot;          </td>
         </tr>
       </table>
 </div>
 <div class="memdoc">

 <p>
 The mod_apreq2 filter is named "apreq2", and may be used in Apache's input filter directives, e.g. <div class="fragment"><pre class="fragment">     AddInputFilter apreq2         # or
      SetInputFilter apreq2
 </pre></div> See above
 </div>
 </div><p>
 <hr><h2>Function Documentation</h2>
 <a class="anchor" name="g68f508b2e1d9909328d7b1277ce4aa80"></a><!-- doxytag: member="apreq_module_apache2.h::apreq_handle_apache2" ref="g68f508b2e1d9909328d7b1277ce4aa80" args="(request_rec *r)" -->
 <div class="memitem">
 <div class="memproto">
       <table class="memname">
         <tr>
           <td class="memname"><a class="el" href="structapreq__handle__t.html">apreq_handle_t</a>* apreq_handle_apache2           </td>
           <td>(</td>
           <td class="paramtype">request_rec *&nbsp;</td>
           <td class="paramname"> <em>r</em>          </td>
           <td>&nbsp;)&nbsp;</td>
           <td></td>
         </tr>
       </table>
 </div>
 <div class="memdoc">

 <p>
 Create an apreq handle which communicates with an <a class="elRef" doxygen="apu.tag:http://apr.apache.org/docs/apr-util/1.3/" href="http://apr.apache.org/docs/apr-util/1.3/namespace_apache.html">Apache</a> 2.X request_rec.
 </div>
 </div><p>
 </div>
 <div id="footer">
 <p class="apache">
 Copyright &copy; 2003-2006 <a href="http://www.apache.org">The Apache Software Foundation</a>.<br/>
 See <a href="apreq_license.html">LICENSE</a>.</p>
 <p class="menu">
 <span style="color:#aaa">page generated by <a href="http://www.doxygen.org/"><code>doxygen</code></a>
 version 1.5.6 on 3 Dec 2010</span>
 </p>
 </div>
 </body>
 </html>
	<html>
	<head>
	<link rel="stylesheet" type="text/css" href="dox.css" />
	<title>libapreq2-2.13: libapreq2: Apache 2.X Filter Module</title>
	</head>
	<body>
	<div id="page-header">
	<p class="menu">
	<a href="http://www.apache.org/">Apache Software Foundation</a> > <a href="http://httpd.apache.org">HTTP Server Project</a> >
	<a href="http://httpd.apache.org/apreq/">Request Library Subproject</a></p>
	<p class="apache">Apache HTTP Server Request Library</p>
	<img alt="" src="feather.gif" /></div>
	<!-- Generated by Doxygen 1.5.6 -->
	<div class="navigation" id="top">
	<div class="tabs">
	<ul>
	<li><a href="index.html"><span>Main Page</span></a></li>
	<li><a href="pages.html"><span>Related Pages</span></a></li>
	<li><a href="modules.html"><span>Modules</span></a></li>
	<li><a href="annotated.html"><span>Data Structures</span></a></li>
	<li><a href="files.html"><span>Files</span></a></li>
	<li><a href="examples.html"><span>Examples</span></a></li>
	</ul>
	</div>
	</div>
	<div class="contents">
	<h1>Apache 2.X Filter Module<br>
	<small>
	[<a class="el" href="group__apreq__module.html">Modules</a>]</small>
	</h1>mod_apreq2 - DSO that ties libapreq2 to <a class="elRef" doxygen="apu.tag:http://apr.apache.org/docs/apr-util/1.3/" href="http://apr.apache.org/docs/apr-util/1.3/namespace_apache.html">Apache</a> HTTPD 2.X.
	<a href="#_details">More...</a><table border="0" cellpadding="0" cellspacing="0">
	<tr><td></td></tr>
	<tr><td colspan="2"><br><h2>Defines</h2></td></tr>
	<tr><td class="memItemLeft" nowrap align="right" valign="top">#define </td><td class="memItemRight" valign="bottom"><a class="el" href="group__mod__apreq2.html#g4b67634b709506e4912f86ebda448504">APREQ_FILTER_NAME</a>   "apreq2"</td></tr>

	<tr><td class="memItemLeft" nowrap align="right" valign="top">#define </td><td class="memItemRight" valign="bottom"><a class="el" href="group__mod__apreq2.html#gab4a3c4b04f2aee2e17b648da09463b0">APREQ_APACHE2_MMN</a>   20090110</td></tr>

	<tr><td colspan="2"><br><h2>Functions</h2></td></tr>
	<tr><td class="memItemLeft" nowrap align="right" valign="top"><a class="el" href="structapreq__handle__t.html">apreq_handle_t</a> * </td><td class="memItemRight" valign="bottom"><a class="el" href="group__mod__apreq2.html#g68f508b2e1d9909328d7b1277ce4aa80">apreq_handle_apache2</a> (request_rec *r)</td></tr>

	<tr><td class="memItemLeft" nowrap align="right" valign="top"><a class="anchor" name="g082ed084cdc19fb048e87c9c1b4989dc"></a><!-- doxytag: member="mod_apreq2::APR_DECLARE_OPTIONAL_FN" ref="g082ed084cdc19fb048e87c9c1b4989dc" args="(apreq_handle_t , apreq_handle_apache2,(request_rec r))" -->
	</td><td class="memItemRight" valign="bottom"><b>APR_DECLARE_OPTIONAL_FN</b> (<a class="el" href="structapreq__handle__t.html">apreq_handle_t</a> , apreq_handle_apache2,(request_rec r))</td></tr>

	</table>
	<hr><a name="_details"></a><h2>Detailed Description</h2>
	mod_apreq2 - DSO that ties libapreq2 to <a class="elRef" doxygen="apu.tag:http://apr.apache.org/docs/apr-util/1.3/" href="http://apr.apache.org/docs/apr-util/1.3/namespace_apache.html">Apache</a> HTTPD 2.X.
	<p>
	mod_apreq2 provides the "APREQ2" input filter for using libapreq2 (and allow its parsed data structures to be shared) within the <a class="elRef" doxygen="apu.tag:http://apr.apache.org/docs/apr-util/1.3/" href="http://apr.apache.org/docs/apr-util/1.3/namespace_apache.html">Apache</a> 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.<p>
	<hr>
	<p>
	<h2>Activating mod_apreq2 in <a class="elRef" doxygen="apu.tag:http://apr.apache.org/docs/apr-util/1.3/" href="http://apr.apache.org/docs/apr-util/1.3/namespace_apache.html">Apache</a> 2.X</h2>
	<p>
	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.<p>
	<div class="fragment"><pre class="fragment"> LoadModule apreq_module modules/mod_apreq2.so
	</pre></div><p>
	The mod_apreq2 filter is named "apreq2", and may be used in Apache's input filter directives, e.g. <div class="fragment"><pre class="fragment"> AddInputFilter apreq2 # or
	SetInputFilter apreq2
	</pre></div><p>
	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 <a class="el" href="group__mod__apreq2.html#g68f508b2e1d9909328d7b1277ce4aa80">apreq_handle_apache2()</a> <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.<p>
	If you want to use other input filters to transform the incoming HTTP request data, is important to register those filters with <a class="elRef" doxygen="apu.tag:http://apr.apache.org/docs/apr-util/1.3/" href="http://apr.apache.org/docs/apr-util/1.3/namespace_apache.html">Apache</a> 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.<p>
	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).<p>
	<h2>Server Configuration Directives</h2>
	<p>
	<table class="qref" border="1" cellspacing="3" cellpadding="3">
	<caption align="bottom">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><a class="el" href="apreq_8h.html#744fa55285c4a3868a9154f473d58ac4">APREQ_DEFAULT_READ_LIMIT</a> </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><a class="el" href="apreq_8h.html#f54c8645b8266fa7c9b2e261c608744f">APREQ_DEFAULT_BRIGADE_LIMIT</a> </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 <a class="elRef" doxygen="apr.tag:http://apr.apache.org/docs/apr/1.3/" href="http://apr.apache.org/docs/apr/1.3/group__apr__file__io.html#g5cc19828a668c362be0ad7a12b805cc0">apr_temp_dir_get()</a>. </td></tr>
	</table>
	<p>
	<h2>Implementation Details</h2>
	<p>
	<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> <hr><h2>Define Documentation</h2>
	<a class="anchor" name="gab4a3c4b04f2aee2e17b648da09463b0"></a><!-- doxytag: member="apreq_module_apache2.h::APREQ_APACHE2_MMN" ref="gab4a3c4b04f2aee2e17b648da09463b0" args="" -->
	<div class="memitem">
	<div class="memproto">
	<table class="memname">
	<tr>
	<td class="memname">#define APREQ_APACHE2_MMN   20090110 </td>
	</tr>
	</table>
	</div>
	<div class="memdoc">

	<p>
	The Apache2 Module Magic Number for use in the <a class="elRef" doxygen="apu.tag:http://apr.apache.org/docs/apr-util/1.3/" href="http://apr.apache.org/docs/apr-util/1.3/namespace_apache.html">Apache</a> 2.x module structures This gets bumped if changes in th4e API will break third party applications using this apache2 module <dl class="see" compact><dt><b>See also:</b></dt><dd><a class="el" href="apreq__module_8h.html#7d6d0550f527e18c8cfab702e65daf3b">APREQ_MODULE</a> </dd></dl>

	</div>
	</div><p>
	<a class="anchor" name="g4b67634b709506e4912f86ebda448504"></a><!-- doxytag: member="apreq_module_apache2.h::APREQ_FILTER_NAME" ref="g4b67634b709506e4912f86ebda448504" args="" -->
	<div class="memitem">
	<div class="memproto">
	<table class="memname">
	<tr>
	<td class="memname">#define APREQ_FILTER_NAME   "apreq2" </td>
	</tr>
	</table>
	</div>
	<div class="memdoc">

	<p>
	The mod_apreq2 filter is named "apreq2", and may be used in Apache's input filter directives, e.g. <div class="fragment"><pre class="fragment"> AddInputFilter apreq2 # or
	SetInputFilter apreq2
	</pre></div> See above
	</div>
	</div><p>
	<hr><h2>Function Documentation</h2>
	<a class="anchor" name="g68f508b2e1d9909328d7b1277ce4aa80"></a><!-- doxytag: member="apreq_module_apache2.h::apreq_handle_apache2" ref="g68f508b2e1d9909328d7b1277ce4aa80" args="(request_rec *r)" -->
	<div class="memitem">
	<div class="memproto">
	<table class="memname">
	<tr>
	<td class="memname"><a class="el" href="structapreq__handle__t.html">apreq_handle_t</a>* apreq_handle_apache2 </td>
	<td>(</td>
	<td class="paramtype">request_rec * </td>
	<td class="paramname"> <em>r</em> </td>
	<td> ) </td>
	<td></td>
	</tr>
	</table>
	</div>
	<div class="memdoc">

	<p>
	Create an apreq handle which communicates with an <a class="elRef" doxygen="apu.tag:http://apr.apache.org/docs/apr-util/1.3/" href="http://apr.apache.org/docs/apr-util/1.3/namespace_apache.html">Apache</a> 2.X request_rec.
	</div>
	</div><p>
	</div>
	<div id="footer">
	<p class="apache">
	Copyright © 2003-2006 <a href="http://www.apache.org">The Apache Software Foundation</a>.<br/>
	See <a href="apreq_license.html">LICENSE</a>.</p>
	<p class="menu">
	<span style="color:#aaa">page generated by <a href="http://www.doxygen.org/"><code>doxygen</code></a>
	version 1.5.6 on 3 Dec 2010</span>
	</p>
	</div>
	</body>
	</html>