modules.html.en revision 4c881d2fffa365e2e0c5e25eb1cf77f4f9406e44
1a190ae8769a33f33b241fab38049e04dc14fd60nd<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
1a190ae8769a33f33b241fab38049e04dc14fd60nd<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head><!--
1a190ae8769a33f33b241fab38049e04dc14fd60nd XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
1a190ae8769a33f33b241fab38049e04dc14fd60nd This file is generated from xml source: DO NOT EDIT
1a190ae8769a33f33b241fab38049e04dc14fd60nd XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
1a190ae8769a33f33b241fab38049e04dc14fd60nd<title>Converting Modules from Apache 1.3 to Apache 2.0 - Apache HTTP Server</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" />
1a190ae8769a33f33b241fab38049e04dc14fd60nd<link href="/style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" />
1a190ae8769a33f33b241fab38049e04dc14fd60nd<link href="/images/favicon.ico" rel="shortcut icon" /></head>
1a190ae8769a33f33b241fab38049e04dc14fd60nd<p class="menu"><a href="/mod/">Modules</a> | <a href="/mod/directives.html">Directives</a> | <a href="/faq/">FAQ</a> | <a href="/glossary.html">Glossary</a> | <a href="/sitemap.html">Sitemap</a></p>
52fff662005b1866a3ff09bb6c902800c5cc6dedjerenkrantz<p class="apache">Apache HTTP Server Version 2.3</p>
1a190ae8769a33f33b241fab38049e04dc14fd60nd<div class="up"><a href="./"><img title="<-" alt="<-" src="/images/left.gif" /></a></div>
4b5981e276e93df97c34e4da05ca5cf8bbd937dand<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.3</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> |
93e5a983fc4eaf7fa7213339ae879bfe32af31b5nd<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>
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>
bbbd690dc97941b1496fc940380969d3737f9ca1dreidstatic 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>
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 <h3><a name="moddef" id="moddef">Module Definition</a></h3>
1a190ae8769a33f33b241fab38049e04dc14fd60nd <p>There are now a lot fewer stages to worry about when
1a190ae8769a33f33b241fab38049e04dc14fd60nd creating your module definition. The old defintion looked
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 */
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> |
93e5a983fc4eaf7fa7213339ae879bfe32af31b5nd<a href="/ja/developer/modules.html" hreflang="ja" rel="alternate" title="Japanese"> ja </a></p>
4b22542f6f38567cae7873b176188a6622f67eb0fielding<p class="apache">Copyright 2006 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>
1a190ae8769a33f33b241fab38049e04dc14fd60nd<p class="menu"><a href="/mod/">Modules</a> | <a href="/mod/directives.html">Directives</a> | <a href="/faq/">FAQ</a> | <a href="/glossary.html">Glossary</a> | <a href="/sitemap.html">Sitemap</a></p></div>