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