modules.xml revision aaef078ba3e233bd178a97074dfef37ccc78b21c
1a190ae8769a33f33b241fab38049e04dc14fd60nd<?xml-stylesheet type="text/xsl" href="/style/manual.en.xsl"?>
5f5d1b4cc970b7f06ff8ef6526128e9a27303d88nd<!-- $LastChangedRevision$ -->
031b91a62d25106ae69d4693475c79618dd5e884fielding Licensed to the Apache Software Foundation (ASF) under one or more
031b91a62d25106ae69d4693475c79618dd5e884fielding contributor license agreements. See the NOTICE file distributed with
031b91a62d25106ae69d4693475c79618dd5e884fielding this work for additional information regarding copyright ownership.
031b91a62d25106ae69d4693475c79618dd5e884fielding The ASF licenses this file to You under the Apache License, Version 2.0
031b91a62d25106ae69d4693475c79618dd5e884fielding (the "License"); you may not use this file except in compliance with
031b91a62d25106ae69d4693475c79618dd5e884fielding the License. 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>
aaef078ba3e233bd178a97074dfef37ccc78b21cchrisd <dd>do any setup required prior to processing configuration
aaef078ba3e233bd178a97074dfef37ccc78b21cchrisd directives</dd>
aaef078ba3e233bd178a97074dfef37ccc78b21cchrisd <dd>review configuration directive interdependencies</dd>
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>