modules.xml revision 5f5d1b4cc970b7f06ff8ef6526128e9a27303d88
1a190ae8769a33f33b241fab38049e04dc14fd60nd<?xml-stylesheet type="text/xsl" href="/style/manual.en.xsl"?>
5f5d1b4cc970b7f06ff8ef6526128e9a27303d88nd<!-- $LastChangedRevision$ -->
6fbd2e53c97ea6976d93e0ac521adabc55e0fb73nd Copyright 2003-2004 The Apache Software Foundation
816bc7965d58c92c0d02fd42d6ea58090f70c6bdnd Licensed under the Apache License, Version 2.0 (the "License");
816bc7965d58c92c0d02fd42d6ea58090f70c6bdnd you may not use this file except in compliance with the License.
816bc7965d58c92c0d02fd42d6ea58090f70c6bdnd You may obtain a copy of the License at
816bc7965d58c92c0d02fd42d6ea58090f70c6bdnd Unless required by applicable law or agreed to in writing, software
816bc7965d58c92c0d02fd42d6ea58090f70c6bdnd distributed under the License is distributed on an "AS IS" BASIS,
816bc7965d58c92c0d02fd42d6ea58090f70c6bdnd WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
816bc7965d58c92c0d02fd42d6ea58090f70c6bdnd See the License for the specific language governing permissions and
816bc7965d58c92c0d02fd42d6ea58090f70c6bdnd limitations under the License.
c82fca6d3f5608b946f18d37e8710b1d71e3478dnd<parentdocument href="./">Developer Documentation</parentdocument>
1a190ae8769a33f33b241fab38049e04dc14fd60nd<title>Converting Modules from Apache 1.3 to Apache 2.0</title>
1a190ae8769a33f33b241fab38049e04dc14fd60nd <p>This is a first attempt at writing the lessons I learned
1a190ae8769a33f33b241fab38049e04dc14fd60nd when trying to convert the <code>mod_mmap_static</code> module to Apache
1a190ae8769a33f33b241fab38049e04dc14fd60nd 2.0. It's by no means definitive and probably won't even be
1a190ae8769a33f33b241fab38049e04dc14fd60nd correct in some ways, but it's a start.</p>
1a190ae8769a33f33b241fab38049e04dc14fd60nd <p>These now need to be of type <code>apr_status_t</code> and return a
1a190ae8769a33f33b241fab38049e04dc14fd60nd value of that type. Normally the return value will be
1a190ae8769a33f33b241fab38049e04dc14fd60nd <code>APR_SUCCESS</code> unless there is some need to signal an error in
1a190ae8769a33f33b241fab38049e04dc14fd60nd the cleanup. Be aware that even though you signal an error not all code
1a190ae8769a33f33b241fab38049e04dc14fd60nd yet checks and acts upon the error.</p>
1a190ae8769a33f33b241fab38049e04dc14fd60nd </section>
1a190ae8769a33f33b241fab38049e04dc14fd60nd <section id="init"><title>Initialisation Routines</title>
1a190ae8769a33f33b241fab38049e04dc14fd60nd <p>These should now be renamed to better signify where they sit
1a190ae8769a33f33b241fab38049e04dc14fd60nd in the overall process. So the name gets a small change from
1a190ae8769a33f33b241fab38049e04dc14fd60nd <code>mmap_init</code> to <code>mmap_post_config</code>. The arguments
1a190ae8769a33f33b241fab38049e04dc14fd60nd passed have undergone a radical change and now look like</p>
1a190ae8769a33f33b241fab38049e04dc14fd60nd </section>
1a190ae8769a33f33b241fab38049e04dc14fd60nd href="http://apr.apache.org/">APR</a>. This means that some have had
1a190ae8769a33f33b241fab38049e04dc14fd60nd a name change, such as the one shown above. The following is a brief
1a190ae8769a33f33b241fab38049e04dc14fd60nd list of some of the changes that you are likely to have to make.</p>
1a190ae8769a33f33b241fab38049e04dc14fd60nd <li><code>pool</code> becomes <code>apr_pool_t</code></li>
1a190ae8769a33f33b241fab38049e04dc14fd60nd <li><code>table</code> becomes <code>apr_table_t</code></li>
1a190ae8769a33f33b241fab38049e04dc14fd60nd </section>
1a190ae8769a33f33b241fab38049e04dc14fd60nd <section id="register-hooks"><title>Register Hooks</title>
1a190ae8769a33f33b241fab38049e04dc14fd60nd <p>The new architecture uses a series of hooks to provide for
1a190ae8769a33f33b241fab38049e04dc14fd60nd calling your functions. These you'll need to add to your module
1a190ae8769a33f33b241fab38049e04dc14fd60nd by way of a new function, <code>static void register_hooks(void)</code>.
1a190ae8769a33f33b241fab38049e04dc14fd60nd The function is really reasonably straightforward once you
1a190ae8769a33f33b241fab38049e04dc14fd60nd understand what needs to be done. Each function that needs
1a190ae8769a33f33b241fab38049e04dc14fd60nd calling at some stage in the processing of a request needs to
1a190ae8769a33f33b241fab38049e04dc14fd60nd be registered, handlers do not. There are a number of phases
1a190ae8769a33f33b241fab38049e04dc14fd60nd where functions can be added, and for each you can specify with
1a190ae8769a33f33b241fab38049e04dc14fd60nd a high degree of control the relative order that the function
1a190ae8769a33f33b241fab38049e04dc14fd60nd will be called in.</p>
1a190ae8769a33f33b241fab38049e04dc14fd60nd <p>This is the code that was added to <code>mod_mmap_static</code>:</p>
1a190ae8769a33f33b241fab38049e04dc14fd60ndstatic void register_hooks(void)
1a190ae8769a33f33b241fab38049e04dc14fd60nd static const char * const aszPre[]={ "http_core.c",NULL };
1a190ae8769a33f33b241fab38049e04dc14fd60nd ap_hook_post_config(mmap_post_config,NULL,NULL,HOOK_MIDDLE);
1a190ae8769a33f33b241fab38049e04dc14fd60nd ap_hook_translate_name(mmap_static_xlat,aszPre,NULL,HOOK_LAST);
1a190ae8769a33f33b241fab38049e04dc14fd60nd </example>
1a190ae8769a33f33b241fab38049e04dc14fd60nd <p>This registers 2 functions that need to be called, one in
1a190ae8769a33f33b241fab38049e04dc14fd60nd the <code>post_config</code> stage (virtually every module will need this
1a190ae8769a33f33b241fab38049e04dc14fd60nd one) and one for the <code>translate_name</code> phase. note that while
1a190ae8769a33f33b241fab38049e04dc14fd60nd there are different function names the format of each is
1a190ae8769a33f33b241fab38049e04dc14fd60nd identical. So what is the format?</p>
1a190ae8769a33f33b241fab38049e04dc14fd60nd <var>predecessors</var>, <var>successors</var>, <var>position</var>);
1a190ae8769a33f33b241fab38049e04dc14fd60nd </example>
1a190ae8769a33f33b241fab38049e04dc14fd60nd <p>To define the position you use the position and then modify
1a190ae8769a33f33b241fab38049e04dc14fd60nd it with the predecessors and successors. Each of the modifiers
1a190ae8769a33f33b241fab38049e04dc14fd60nd can be a list of functions that should be called, either before
1a190ae8769a33f33b241fab38049e04dc14fd60nd the function is run (predecessors) or after the function has
1a190ae8769a33f33b241fab38049e04dc14fd60nd run (successors).</p>
1a190ae8769a33f33b241fab38049e04dc14fd60nd <p>In the <code>mod_mmap_static</code> case I didn't care about the
1a190ae8769a33f33b241fab38049e04dc14fd60nd <code>post_config</code> stage, but the <code>mmap_static_xlat</code>
1a190ae8769a33f33b241fab38049e04dc14fd60nd <strong>must</strong> be called after the core module had done it's name
1a190ae8769a33f33b241fab38049e04dc14fd60nd translation, hence the use of the aszPre to define a modifier to the
1a190ae8769a33f33b241fab38049e04dc14fd60nd </section>
1a190ae8769a33f33b241fab38049e04dc14fd60nd <p>There are now a lot fewer stages to worry about when
1a190ae8769a33f33b241fab38049e04dc14fd60nd creating your module definition. The old defintion looked
1a190ae8769a33f33b241fab38049e04dc14fd60nd STANDARD_MODULE_STUFF,
1a190ae8769a33f33b241fab38049e04dc14fd60nd /* initializer */
1a190ae8769a33f33b241fab38049e04dc14fd60nd /* dir config creater */
1a190ae8769a33f33b241fab38049e04dc14fd60nd /* dir merger --- default is to override */
1a190ae8769a33f33b241fab38049e04dc14fd60nd /* server config */
1a190ae8769a33f33b241fab38049e04dc14fd60nd /* merge server config */
1a190ae8769a33f33b241fab38049e04dc14fd60nd /* command handlers */
1a190ae8769a33f33b241fab38049e04dc14fd60nd /* handlers */
1a190ae8769a33f33b241fab38049e04dc14fd60nd /* filename translation */
1a190ae8769a33f33b241fab38049e04dc14fd60nd /* check_user_id */
1a190ae8769a33f33b241fab38049e04dc14fd60nd /* check auth */
1a190ae8769a33f33b241fab38049e04dc14fd60nd /* check access */
1a190ae8769a33f33b241fab38049e04dc14fd60nd /* type_checker */
1a190ae8769a33f33b241fab38049e04dc14fd60nd /* fixups */
1a190ae8769a33f33b241fab38049e04dc14fd60nd /* logger */
1a190ae8769a33f33b241fab38049e04dc14fd60nd /* header parser */
1a190ae8769a33f33b241fab38049e04dc14fd60nd /* child_init */
1a190ae8769a33f33b241fab38049e04dc14fd60nd /* child_exit */
1a190ae8769a33f33b241fab38049e04dc14fd60nd /* post read-request */
1a190ae8769a33f33b241fab38049e04dc14fd60nd </example>
1a190ae8769a33f33b241fab38049e04dc14fd60nd STANDARD20_MODULE_STUFF,
1a190ae8769a33f33b241fab38049e04dc14fd60nd /* create per-directory config structures */
1a190ae8769a33f33b241fab38049e04dc14fd60nd /* merge per-directory config structures */
1a190ae8769a33f33b241fab38049e04dc14fd60nd /* create per-server config structures */
1a190ae8769a33f33b241fab38049e04dc14fd60nd /* merge per-server config structures */
1a190ae8769a33f33b241fab38049e04dc14fd60nd /* command handlers */
1a190ae8769a33f33b241fab38049e04dc14fd60nd /* handlers */
1a190ae8769a33f33b241fab38049e04dc14fd60nd /* register hooks */
1a190ae8769a33f33b241fab38049e04dc14fd60nd </example>
1a190ae8769a33f33b241fab38049e04dc14fd60nd <p>Some of these read directly across, some don't. I'll try to
1a190ae8769a33f33b241fab38049e04dc14fd60nd summarise what should be done below.</p>
1a190ae8769a33f33b241fab38049e04dc14fd60nd <dd><code>/* create per-directory config structures */</code></dd>
1a190ae8769a33f33b241fab38049e04dc14fd60nd <dd><code>/* create per-server config structures */</code></dd>
1a190ae8769a33f33b241fab38049e04dc14fd60nd <dd><code>/* merge per-directory config structures */</code></dd>
1a190ae8769a33f33b241fab38049e04dc14fd60nd <dd><code>/* merge per-server config structures */</code></dd>
1a190ae8769a33f33b241fab38049e04dc14fd60nd <p>The remainder of the old functions should be registered as
1a190ae8769a33f33b241fab38049e04dc14fd60nd hooks. There are the following hook stages defined so
1a190ae8769a33f33b241fab38049e04dc14fd60nd far...</p>
1a190ae8769a33f33b241fab38049e04dc14fd60nd <dd>this is where the old <code>_init</code> routines get
1a190ae8769a33f33b241fab38049e04dc14fd60nd registered</dd>
1a190ae8769a33f33b241fab38049e04dc14fd60nd <dd>retrieve the http method from a request. (legacy)</dd>
1a190ae8769a33f33b241fab38049e04dc14fd60nd <dd>do any setup required just before processing, but after
1a190ae8769a33f33b241fab38049e04dc14fd60nd accepting</dd>
1a190ae8769a33f33b241fab38049e04dc14fd60nd <dd>last chance to modify things before generating content</dd>
1a190ae8769a33f33b241fab38049e04dc14fd60nd <dd>lets modules look at the headers, not used by most modules, because
1a190ae8769a33f33b241fab38049e04dc14fd60nd <dd>called after reading the request, before any other phase</dd>
1a190ae8769a33f33b241fab38049e04dc14fd60nd <dd>called before any request processing, used by cache modules.</dd>
1a190ae8769a33f33b241fab38049e04dc14fd60nd </section>
1a190ae8769a33f33b241fab38049e04dc14fd60nd</manualpage>