modules.html.en revision fd9abdda70912b99b24e3bf1a38f26fde908a74c
1a190ae8769a33f33b241fab38049e04dc14fd60nd<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
fd9abdda70912b99b24e3bf1a38f26fde908a74cnd<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head>
fd9abdda70912b99b24e3bf1a38f26fde908a74cnd<meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type" />
1a190ae8769a33f33b241fab38049e04dc14fd60nd XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
1a190ae8769a33f33b241fab38049e04dc14fd60nd This file is generated from xml source: DO NOT EDIT
1a190ae8769a33f33b241fab38049e04dc14fd60nd XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
96ad5d81ee4a2cc66a4ae19893efc8aa6d06fae7jailletc<title>Converting Modules from Apache 1.3 to Apache 2.0 - Apache HTTP Server Version 2.5</title>
1a190ae8769a33f33b241fab38049e04dc14fd60nd<link href="/style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" />
1a190ae8769a33f33b241fab38049e04dc14fd60nd<link href="/style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" />
d29d9ab4614ff992b0e8de6e2b88d52b6f1f153erbowen<link href="/style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" /><link rel="stylesheet" type="text/css" href="/style/css/prettify.css" />
2e545ce2450a9953665f701bb05350f0d3f26275nd<script src="/style/scripts/prettify.min.js" type="text/javascript">
1a190ae8769a33f33b241fab38049e04dc14fd60nd<link href="/images/favicon.ico" rel="shortcut icon" /></head>
af33a4994ae2ff15bc67d19ff1a7feb906745bf8rbowen<p class="menu"><a href="/mod/">Modules</a> | <a href="/mod/quickreference.html">Directives</a> | <a href="http://wiki.apache.org/httpd/FAQ">FAQ</a> | <a href="/glossary.html">Glossary</a> | <a href="/sitemap.html">Sitemap</a></p>
1a190ae8769a33f33b241fab38049e04dc14fd60nd<div class="up"><a href="./"><img title="<-" alt="<-" src="/images/left.gif" /></a></div>
3f08db06526d6901aa08c110b5bc7dde6bc39905nd<a href="http://www.apache.org/">Apache</a> > <a href="http://httpd.apache.org/">HTTP Server</a> > <a href="http://httpd.apache.org/docs/">Documentation</a> > <a href="../">Version 2.5</a> > <a href="./">Developer Documentation</a></div><div id="page-content"><div id="preamble"><h1>Converting Modules from Apache 1.3 to Apache 2.0</h1>
93e5a983fc4eaf7fa7213339ae879bfe32af31b5nd<p><span>Available Languages: </span><a href="/en/developer/modules.html" title="English"> en </a> |
f086b4b402fa9a2fefc7dda85de2a3cc1cd0a654rjung<a href="/ja/developer/modules.html" hreflang="ja" rel="alternate" title="Japanese"> ja </a></p>
7d9f2bf92f3b96b3d651365013e5da845849571brbowen <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
7d9f2bf92f3b96b3d651365013e5da845849571brbowen 2.0. It's by no means definitive and probably won't even be
7d9f2bf92f3b96b3d651365013e5da845849571brbowen correct in some ways, but it's a start.</p>
1a190ae8769a33f33b241fab38049e04dc14fd60nd<div id="quickview"><ul id="toc"><li><img alt="" src="/images/down.gif" /> <a href="#easy">The easier changes ...</a></li>
1a190ae8769a33f33b241fab38049e04dc14fd60nd<li><img alt="" src="/images/down.gif" /> <a href="#messy">The messier changes...</a></li>
30471a4650391f57975f60bbb6e4a90be7b284bfhumbedooh</ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
1a190ae8769a33f33b241fab38049e04dc14fd60nd<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
1a190ae8769a33f33b241fab38049e04dc14fd60nd<h2><a name="easy" id="easy">The easier changes ...</a></h2>
1a190ae8769a33f33b241fab38049e04dc14fd60nd <h3><a name="cleanup" id="cleanup">Cleanup Routines</a></h3>
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 <h3><a name="init" id="init">Initialisation Routines</a></h3>
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 <h3><a name="datatypes" id="datatypes">Data Types</a></h3>
1a190ae8769a33f33b241fab38049e04dc14fd60nd <p>A lot of the data types have been moved into the <a 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</div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
1a190ae8769a33f33b241fab38049e04dc14fd60nd<h2><a name="messy" id="messy">The messier changes...</a></h2>
1a190ae8769a33f33b241fab38049e04dc14fd60nd <h3><a name="register-hooks" id="register-hooks">Register Hooks</a></h3>
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>
4aa603e6448b99f9371397d439795c91a93637eand <div class="example"><pre>static void register_hooks(void)
bbbd690dc97941b1496fc940380969d3737f9ca1dreid static const char * const aszPre[]={ "http_core.c",NULL };
bbbd690dc97941b1496fc940380969d3737f9ca1dreid ap_hook_post_config(mmap_post_config,NULL,NULL,HOOK_MIDDLE);
bbbd690dc97941b1496fc940380969d3737f9ca1dreid ap_hook_translate_name(mmap_static_xlat,aszPre,NULL,HOOK_LAST);
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 <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>
c7d7b17e921d92419473ebe85ed7e4512001f68fhumbedooh <strong>must</strong> be called after the core module had done its name
1a190ae8769a33f33b241fab38049e04dc14fd60nd translation, hence the use of the aszPre to define a modifier to the
1a190ae8769a33f33b241fab38049e04dc14fd60nd <h3><a name="moddef" id="moddef">Module Definition</a></h3>
1a190ae8769a33f33b241fab38049e04dc14fd60nd <p>There are now a lot fewer stages to worry about when
48b62528cd9513fe8b5f1bbcee92ab3b28c94807rbowen creating your module definition. The old definition looked
4aa603e6448b99f9371397d439795c91a93637eand <div class="example"><pre>module MODULE_VAR_EXPORT <var>module_name</var>_module =
bbbd690dc97941b1496fc940380969d3737f9ca1dreid STANDARD_MODULE_STUFF,
bbbd690dc97941b1496fc940380969d3737f9ca1dreid /* initializer */
bbbd690dc97941b1496fc940380969d3737f9ca1dreid /* dir config creater */
bbbd690dc97941b1496fc940380969d3737f9ca1dreid /* dir merger --- default is to override */
bbbd690dc97941b1496fc940380969d3737f9ca1dreid /* server config */
bbbd690dc97941b1496fc940380969d3737f9ca1dreid /* merge server config */
bbbd690dc97941b1496fc940380969d3737f9ca1dreid /* command handlers */
bbbd690dc97941b1496fc940380969d3737f9ca1dreid /* handlers */
bbbd690dc97941b1496fc940380969d3737f9ca1dreid /* filename translation */
bbbd690dc97941b1496fc940380969d3737f9ca1dreid /* check_user_id */
bbbd690dc97941b1496fc940380969d3737f9ca1dreid /* check auth */
bbbd690dc97941b1496fc940380969d3737f9ca1dreid /* check access */
bbbd690dc97941b1496fc940380969d3737f9ca1dreid /* type_checker */
bbbd690dc97941b1496fc940380969d3737f9ca1dreid /* fixups */
bbbd690dc97941b1496fc940380969d3737f9ca1dreid /* logger */
bbbd690dc97941b1496fc940380969d3737f9ca1dreid /* header parser */
bbbd690dc97941b1496fc940380969d3737f9ca1dreid /* child_init */
bbbd690dc97941b1496fc940380969d3737f9ca1dreid /* child_exit */
bbbd690dc97941b1496fc940380969d3737f9ca1dreid /* post read-request */
4aa603e6448b99f9371397d439795c91a93637eand <div class="example"><pre>module MODULE_VAR_EXPORT <var>module_name</var>_module =
bbbd690dc97941b1496fc940380969d3737f9ca1dreid STANDARD20_MODULE_STUFF,
bbbd690dc97941b1496fc940380969d3737f9ca1dreid /* create per-directory config structures */
bbbd690dc97941b1496fc940380969d3737f9ca1dreid /* merge per-directory config structures */
bbbd690dc97941b1496fc940380969d3737f9ca1dreid /* create per-server config structures */
bbbd690dc97941b1496fc940380969d3737f9ca1dreid /* merge per-server config structures */
bbbd690dc97941b1496fc940380969d3737f9ca1dreid /* command handlers */
bbbd690dc97941b1496fc940380969d3737f9ca1dreid /* handlers */
bbbd690dc97941b1496fc940380969d3737f9ca1dreid /* register hooks */
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>
4c881d2fffa365e2e0c5e25eb1cf77f4f9406e44chrisd <dd>do any setup required prior to processing configuration
4c881d2fffa365e2e0c5e25eb1cf77f4f9406e44chrisd directives</dd>
4c881d2fffa365e2e0c5e25eb1cf77f4f9406e44chrisd <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>
93e5a983fc4eaf7fa7213339ae879bfe32af31b5nd<p><span>Available Languages: </span><a href="/en/developer/modules.html" title="English"> en </a> |
f086b4b402fa9a2fefc7dda85de2a3cc1cd0a654rjung<a href="/ja/developer/modules.html" hreflang="ja" rel="alternate" title="Japanese"> ja </a></p>
727872d18412fc021f03969b8641810d8896820bhumbedooh</div><div class="top"><a href="#page-header"><img src="/images/up.gif" alt="top" /></a></div><div class="section"><h2><a id="comments_section" name="comments_section">Comments</a></h2><div class="warning"><strong>Notice:</strong><br />This is not a Q&A section. Comments placed here should be pointed towards suggestions on improving the documentation or server, and may be removed again by our moderators if they are either implemented or considered invalid/off-topic. Questions on how to manage the Apache HTTP Server should be directed at either our IRC channel, #httpd, on Freenode, or sent to our <a href="http://httpd.apache.org/lists.html">mailing lists</a>.</div>
727872d18412fc021f03969b8641810d8896820bhumbedoohvar comments_shortname = 'httpd';
cc7e1025de9ac63bd4db6fe7f71c158b2cf09fe4humbedoohvar comments_identifier = 'http://httpd.apache.org/docs/trunk/developer/modules.html';
0d0ba3a410038e179b695446bb149cce6264e0abnd(function(w, d) {
cc7e1025de9ac63bd4db6fe7f71c158b2cf09fe4humbedooh if (w.location.hostname.toLowerCase() == "httpd.apache.org") {
727872d18412fc021f03969b8641810d8896820bhumbedooh d.write('<div id="comments_thread"><\/div>');
0d0ba3a410038e179b695446bb149cce6264e0abnd var s = d.createElement('script');
ac082aefa89416cbdc9a1836eaf3bed9698201c8humbedooh s.src = 'https://comments.apache.org/show_comments.lua?site=' + comments_shortname + '&page=' + comments_identifier;
0d0ba3a410038e179b695446bb149cce6264e0abnd (d.getElementsByTagName('head')[0] || d.getElementsByTagName('body')[0]).appendChild(s);
727872d18412fc021f03969b8641810d8896820bhumbedooh d.write('<div id="comments_thread">Comments are disabled for this page at the moment.<\/div>');
0d0ba3a410038e179b695446bb149cce6264e0abnd})(window, document);
205f749042ed530040a4f0080dbcb47ceae8a374rjung<p class="apache">Copyright 2015 The Apache Software Foundation.<br />Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.</p>
af33a4994ae2ff15bc67d19ff1a7feb906745bf8rbowen<p class="menu"><a href="/mod/">Modules</a> | <a href="/mod/quickreference.html">Directives</a> | <a href="http://wiki.apache.org/httpd/FAQ">FAQ</a> | <a href="/glossary.html">Glossary</a> | <a href="/sitemap.html">Sitemap</a></p></div><script type="text/javascript"><!--//--><![CDATA[//><!--
0d0ba3a410038e179b695446bb149cce6264e0abndif (typeof(prettyPrint) !== 'undefined') {
7fec19672a491661b2fe4b29f685bc7f4efa64d4nd prettyPrint();