modules.html.en revision 4c881d2fffa365e2e0c5e25eb1cf77f4f9406e44
dc3a272f8afcbc137adcfee4c3aa052d2bdf4df7gryzor<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
dc3a272f8afcbc137adcfee4c3aa052d2bdf4df7gryzor<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head><!--
dc3a272f8afcbc137adcfee4c3aa052d2bdf4df7gryzor XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
dc3a272f8afcbc137adcfee4c3aa052d2bdf4df7gryzor This file is generated from xml source: DO NOT EDIT
dc3a272f8afcbc137adcfee4c3aa052d2bdf4df7gryzor XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
dc3a272f8afcbc137adcfee4c3aa052d2bdf4df7gryzor<title>Converting Modules from Apache 1.3 to Apache 2.0 - Apache HTTP Server</title>
dc3a272f8afcbc137adcfee4c3aa052d2bdf4df7gryzor<link href="/style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" />
dc3a272f8afcbc137adcfee4c3aa052d2bdf4df7gryzor<link href="/style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" />
dc3a272f8afcbc137adcfee4c3aa052d2bdf4df7gryzor<link href="/style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" />
dc3a272f8afcbc137adcfee4c3aa052d2bdf4df7gryzor<link href="/images/favicon.ico" rel="shortcut icon" /></head>
dc3a272f8afcbc137adcfee4c3aa052d2bdf4df7gryzor<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>
dc3a272f8afcbc137adcfee4c3aa052d2bdf4df7gryzor<div class="up"><a href="./"><img title="<-" alt="<-" src="/images/left.gif" /></a></div>
dc3a272f8afcbc137adcfee4c3aa052d2bdf4df7gryzor<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>
dc3a272f8afcbc137adcfee4c3aa052d2bdf4df7gryzor<p><span>Available Languages: </span><a href="/en/developer/modules.html" title="English"> en </a> |
dc3a272f8afcbc137adcfee4c3aa052d2bdf4df7gryzor<a href="/ja/developer/modules.html" hreflang="ja" rel="alternate" title="Japanese"> ja </a></p>
f086b4b402fa9a2fefc7dda85de2a3cc1cd0a654rjung <p>This is a first attempt at writing the lessons I learned
dc3a272f8afcbc137adcfee4c3aa052d2bdf4df7gryzor when trying to convert the <code>mod_mmap_static</code> module to Apache
dc3a272f8afcbc137adcfee4c3aa052d2bdf4df7gryzor 2.0. It's by no means definitive and probably won't even be
dc3a272f8afcbc137adcfee4c3aa052d2bdf4df7gryzor correct in some ways, but it's a start.</p>
dc3a272f8afcbc137adcfee4c3aa052d2bdf4df7gryzor<div id="quickview"><ul id="toc"><li><img alt="" src="/images/down.gif" /> <a href="#easy">The easier changes ...</a></li>
dc3a272f8afcbc137adcfee4c3aa052d2bdf4df7gryzor<li><img alt="" src="/images/down.gif" /> <a href="#messy">The messier changes...</a></li>
dc3a272f8afcbc137adcfee4c3aa052d2bdf4df7gryzor<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
c867dba1041640ecec7c8194d35a5b4ffce442earbowen<h2><a name="easy" id="easy">The easier changes ...</a></h2>
b71e5eae594d54e9e56dc20208c6a7fb52610e29rbowen <h3><a name="cleanup" id="cleanup">Cleanup Routines</a></h3>
c867dba1041640ecec7c8194d35a5b4ffce442earbowen <p>These now need to be of type <code>apr_status_t</code> and return a
c867dba1041640ecec7c8194d35a5b4ffce442earbowen value of that type. Normally the return value will be
c867dba1041640ecec7c8194d35a5b4ffce442earbowen <code>APR_SUCCESS</code> unless there is some need to signal an error in
c867dba1041640ecec7c8194d35a5b4ffce442earbowen the cleanup. Be aware that even though you signal an error not all code
c867dba1041640ecec7c8194d35a5b4ffce442earbowen yet checks and acts upon the error.</p>
c867dba1041640ecec7c8194d35a5b4ffce442earbowen <h3><a name="init" id="init">Initialisation Routines</a></h3>
c867dba1041640ecec7c8194d35a5b4ffce442earbowen <p>These should now be renamed to better signify where they sit
c867dba1041640ecec7c8194d35a5b4ffce442earbowen in the overall process. So the name gets a small change from
c867dba1041640ecec7c8194d35a5b4ffce442earbowen <code>mmap_init</code> to <code>mmap_post_config</code>. The arguments
c867dba1041640ecec7c8194d35a5b4ffce442earbowen passed have undergone a radical change and now look like</p>
dc3a272f8afcbc137adcfee4c3aa052d2bdf4df7gryzor <h3><a name="datatypes" id="datatypes">Data Types</a></h3>
dc3a272f8afcbc137adcfee4c3aa052d2bdf4df7gryzor <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
dc3a272f8afcbc137adcfee4c3aa052d2bdf4df7gryzor a name change, such as the one shown above. The following is a brief
dc3a272f8afcbc137adcfee4c3aa052d2bdf4df7gryzor list of some of the changes that you are likely to have to make.</p>
dc3a272f8afcbc137adcfee4c3aa052d2bdf4df7gryzor <li><code>pool</code> becomes <code>apr_pool_t</code></li>
dc3a272f8afcbc137adcfee4c3aa052d2bdf4df7gryzor <li><code>table</code> becomes <code>apr_table_t</code></li>
dc3a272f8afcbc137adcfee4c3aa052d2bdf4df7gryzor</div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
dc3a272f8afcbc137adcfee4c3aa052d2bdf4df7gryzor<h2><a name="messy" id="messy">The messier changes...</a></h2>
dc3a272f8afcbc137adcfee4c3aa052d2bdf4df7gryzor <h3><a name="register-hooks" id="register-hooks">Register Hooks</a></h3>
dc3a272f8afcbc137adcfee4c3aa052d2bdf4df7gryzor <p>The new architecture uses a series of hooks to provide for
dc3a272f8afcbc137adcfee4c3aa052d2bdf4df7gryzor calling your functions. These you'll need to add to your module
c867dba1041640ecec7c8194d35a5b4ffce442earbowen by way of a new function, <code>static void register_hooks(void)</code>.
c867dba1041640ecec7c8194d35a5b4ffce442earbowen The function is really reasonably straightforward once you
c867dba1041640ecec7c8194d35a5b4ffce442earbowen understand what needs to be done. Each function that needs
c867dba1041640ecec7c8194d35a5b4ffce442earbowen calling at some stage in the processing of a request needs to
c867dba1041640ecec7c8194d35a5b4ffce442earbowen be registered, handlers do not. There are a number of phases
c867dba1041640ecec7c8194d35a5b4ffce442earbowen where functions can be added, and for each you can specify with
c867dba1041640ecec7c8194d35a5b4ffce442earbowen a high degree of control the relative order that the function
c867dba1041640ecec7c8194d35a5b4ffce442earbowen will be called in.</p>
c867dba1041640ecec7c8194d35a5b4ffce442earbowen <p>This is the code that was added to <code>mod_mmap_static</code>:</p>
c867dba1041640ecec7c8194d35a5b4ffce442earbowenstatic void register_hooks(void)
c867dba1041640ecec7c8194d35a5b4ffce442earbowen static const char * const aszPre[]={ "http_core.c",NULL };
c867dba1041640ecec7c8194d35a5b4ffce442earbowen ap_hook_post_config(mmap_post_config,NULL,NULL,HOOK_MIDDLE);
c867dba1041640ecec7c8194d35a5b4ffce442earbowen ap_hook_translate_name(mmap_static_xlat,aszPre,NULL,HOOK_LAST);
c867dba1041640ecec7c8194d35a5b4ffce442earbowen <p>This registers 2 functions that need to be called, one in
c867dba1041640ecec7c8194d35a5b4ffce442earbowen the <code>post_config</code> stage (virtually every module will need this
c867dba1041640ecec7c8194d35a5b4ffce442earbowen one) and one for the <code>translate_name</code> phase. note that while
c867dba1041640ecec7c8194d35a5b4ffce442earbowen there are different function names the format of each is
c867dba1041640ecec7c8194d35a5b4ffce442earbowen identical. So what is the format?</p>
c867dba1041640ecec7c8194d35a5b4ffce442earbowen ap_hook_<var>phase_name</var>(<var>function_name</var>,
c867dba1041640ecec7c8194d35a5b4ffce442earbowen <var>predecessors</var>, <var>successors</var>, <var>position</var>);
dc3a272f8afcbc137adcfee4c3aa052d2bdf4df7gryzor <p>To define the position you use the position and then modify
dc3a272f8afcbc137adcfee4c3aa052d2bdf4df7gryzor it with the predecessors and successors. Each of the modifiers
dc3a272f8afcbc137adcfee4c3aa052d2bdf4df7gryzor can be a list of functions that should be called, either before
dc3a272f8afcbc137adcfee4c3aa052d2bdf4df7gryzor the function is run (predecessors) or after the function has
dc3a272f8afcbc137adcfee4c3aa052d2bdf4df7gryzor run (successors).</p>
dc3a272f8afcbc137adcfee4c3aa052d2bdf4df7gryzor <p>In the <code>mod_mmap_static</code> case I didn't care about the
dc3a272f8afcbc137adcfee4c3aa052d2bdf4df7gryzor <code>post_config</code> stage, but the <code>mmap_static_xlat</code>
c867dba1041640ecec7c8194d35a5b4ffce442earbowen <strong>must</strong> be called after the core module had done it's name
dc3a272f8afcbc137adcfee4c3aa052d2bdf4df7gryzor translation, hence the use of the aszPre to define a modifier to the
dc3a272f8afcbc137adcfee4c3aa052d2bdf4df7gryzor <h3><a name="moddef" id="moddef">Module Definition</a></h3>
dc3a272f8afcbc137adcfee4c3aa052d2bdf4df7gryzor <p>There are now a lot fewer stages to worry about when
c867dba1041640ecec7c8194d35a5b4ffce442earbowen creating your module definition. The old defintion looked
c867dba1041640ecec7c8194d35a5b4ffce442earbowenmodule MODULE_VAR_EXPORT <var>module_name</var>_module =
c867dba1041640ecec7c8194d35a5b4ffce442earbowen STANDARD_MODULE_STUFF,
8e9c6d6438af1ccb46adaa60d34caa3ac98f3851igalic /* initializer */
8e9c6d6438af1ccb46adaa60d34caa3ac98f3851igalic /* dir config creater */
8e9c6d6438af1ccb46adaa60d34caa3ac98f3851igalic /* dir merger --- default is to override */
8e9c6d6438af1ccb46adaa60d34caa3ac98f3851igalic /* server config */
8e9c6d6438af1ccb46adaa60d34caa3ac98f3851igalic /* merge server config */
c867dba1041640ecec7c8194d35a5b4ffce442earbowen /* command handlers */
c867dba1041640ecec7c8194d35a5b4ffce442earbowen /* handlers */
c867dba1041640ecec7c8194d35a5b4ffce442earbowen /* filename translation */
8e9c6d6438af1ccb46adaa60d34caa3ac98f3851igalic /* check_user_id */
8e9c6d6438af1ccb46adaa60d34caa3ac98f3851igalic /* check auth */
c867dba1041640ecec7c8194d35a5b4ffce442earbowen /* check access */
c867dba1041640ecec7c8194d35a5b4ffce442earbowen /* type_checker */
c867dba1041640ecec7c8194d35a5b4ffce442earbowen /* fixups */
c867dba1041640ecec7c8194d35a5b4ffce442earbowen /* logger */
c867dba1041640ecec7c8194d35a5b4ffce442earbowen /* header parser */
c867dba1041640ecec7c8194d35a5b4ffce442earbowen /* child_init */
c867dba1041640ecec7c8194d35a5b4ffce442earbowen /* child_exit */
c867dba1041640ecec7c8194d35a5b4ffce442earbowen /* post read-request */
c867dba1041640ecec7c8194d35a5b4ffce442earbowenmodule MODULE_VAR_EXPORT <var>module_name</var>_module =
dc3a272f8afcbc137adcfee4c3aa052d2bdf4df7gryzor STANDARD20_MODULE_STUFF,
dc3a272f8afcbc137adcfee4c3aa052d2bdf4df7gryzor /* create per-directory config structures */
c867dba1041640ecec7c8194d35a5b4ffce442earbowen /* merge per-directory config structures */
c867dba1041640ecec7c8194d35a5b4ffce442earbowen /* create per-server config structures */
c867dba1041640ecec7c8194d35a5b4ffce442earbowen /* merge per-server config structures */
c867dba1041640ecec7c8194d35a5b4ffce442earbowen /* command handlers */
dc3a272f8afcbc137adcfee4c3aa052d2bdf4df7gryzor /* handlers */
dc3a272f8afcbc137adcfee4c3aa052d2bdf4df7gryzor /* register hooks */
dc3a272f8afcbc137adcfee4c3aa052d2bdf4df7gryzor <p>Some of these read directly across, some don't. I'll try to
dc3a272f8afcbc137adcfee4c3aa052d2bdf4df7gryzor summarise what should be done below.</p>
dc3a272f8afcbc137adcfee4c3aa052d2bdf4df7gryzor <dd><code>/* create per-directory config structures */</code></dd>
dc3a272f8afcbc137adcfee4c3aa052d2bdf4df7gryzor <dd><code>/* create per-server config structures */</code></dd>
c867dba1041640ecec7c8194d35a5b4ffce442earbowen <dd><code>/* merge per-directory config structures */</code></dd>
c867dba1041640ecec7c8194d35a5b4ffce442earbowen <dd><code>/* merge per-server config structures */</code></dd>
dc3a272f8afcbc137adcfee4c3aa052d2bdf4df7gryzor <p>The remainder of the old functions should be registered as
dc3a272f8afcbc137adcfee4c3aa052d2bdf4df7gryzor hooks. There are the following hook stages defined so
c867dba1041640ecec7c8194d35a5b4ffce442earbowen <dd>do any setup required prior to processing configuration
c867dba1041640ecec7c8194d35a5b4ffce442earbowen directives</dd>
dc3a272f8afcbc137adcfee4c3aa052d2bdf4df7gryzor <dd>review configuration directive interdependencies</dd>
dc3a272f8afcbc137adcfee4c3aa052d2bdf4df7gryzor <dd>this is where the old <code>_init</code> routines get
c867dba1041640ecec7c8194d35a5b4ffce442earbowen registered</dd>
dc3a272f8afcbc137adcfee4c3aa052d2bdf4df7gryzor <dd>retrieve the http method from a request. (legacy)</dd>
c867dba1041640ecec7c8194d35a5b4ffce442earbowen <dd>check if the resource requires authorization</dd>
dc3a272f8afcbc137adcfee4c3aa052d2bdf4df7gryzor <dd>do any setup required just before processing, but after
dc3a272f8afcbc137adcfee4c3aa052d2bdf4df7gryzor accepting</dd>
dc3a272f8afcbc137adcfee4c3aa052d2bdf4df7gryzor <dd>last chance to modify things before generating content</dd>
dc3a272f8afcbc137adcfee4c3aa052d2bdf4df7gryzor <dd>lets modules look at the headers, not used by most modules, because
dc3a272f8afcbc137adcfee4c3aa052d2bdf4df7gryzor they use <code>post_read_request</code> for this</dd>
dc3a272f8afcbc137adcfee4c3aa052d2bdf4df7gryzor <dd>retrieve any functions registered as optional</dd>
dc3a272f8afcbc137adcfee4c3aa052d2bdf4df7gryzor <dd>called after reading the request, before any other phase</dd>
dc3a272f8afcbc137adcfee4c3aa052d2bdf4df7gryzor <dd>called before any request processing, used by cache modules.</dd>
dc3a272f8afcbc137adcfee4c3aa052d2bdf4df7gryzor<p><span>Available Languages: </span><a href="/en/developer/modules.html" title="English"> en </a> |
dc3a272f8afcbc137adcfee4c3aa052d2bdf4df7gryzor<a href="/ja/developer/modules.html" hreflang="ja" rel="alternate" title="Japanese"> ja </a></p>
dc3a272f8afcbc137adcfee4c3aa052d2bdf4df7gryzor<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>
dc3a272f8afcbc137adcfee4c3aa052d2bdf4df7gryzor<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>