new_api_2_4.html.en revision 50c04f297d76a57ead2fa6b73845f7563b1fc788
842ae4bd224140319ae7feec1872b93dfd491143fielding<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
842ae4bd224140319ae7feec1872b93dfd491143fielding<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head><!--
842ae4bd224140319ae7feec1872b93dfd491143fielding XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
842ae4bd224140319ae7feec1872b93dfd491143fielding This file is generated from xml source: DO NOT EDIT
842ae4bd224140319ae7feec1872b93dfd491143fielding XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
ce9621257ef9e54c1bbe5ad8a5f445a1f211c2dcnd<title>API Changes in Apache HTTP Server 2.4 since 2.2 - Apache HTTP Server</title>
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding<link href="/style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" />
ce9621257ef9e54c1bbe5ad8a5f445a1f211c2dcnd<link href="/style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" />
ce9621257ef9e54c1bbe5ad8a5f445a1f211c2dcnd<link href="/style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" />
ce9621257ef9e54c1bbe5ad8a5f445a1f211c2dcnd<link href="/images/favicon.ico" rel="shortcut icon" /></head>
ce9621257ef9e54c1bbe5ad8a5f445a1f211c2dcnd<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>
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding<p class="apache">Apache HTTP Server Version 2.3</p>
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding<div class="up"><a href="./"><img title="<-" alt="<-" src="/images/left.gif" /></a></div>
e8f95a682820a599fe41b22977010636be5c2717jim<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></div><div id="page-content"><div id="preamble"><h1>API Changes in Apache HTTP Server 2.4 since 2.2</h1>
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding<p><span>Available Languages: </span><a href="/en/developer/new_api_2_4.html" title="English"> en </a></p>
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding <p>This document describes changes to the Apache HTTPD API from
b6055b7832a0e4d0818416252fff5925aaebae4brbb version 2.2 to 2.4, that may be of interest to module/application
1b21d7b3d97def358b2e923655edeb16613a1c31gstein developers and core hacks. At the time of writing, the 2.4 API
1b21d7b3d97def358b2e923655edeb16613a1c31gstein is not finalised, and this document may serve to highlight
1b21d7b3d97def358b2e923655edeb16613a1c31gstein points that call for further review.</p>
1b21d7b3d97def358b2e923655edeb16613a1c31gstein <p>API changes fall into two categories: APIs that are altogether new,
1b21d7b3d97def358b2e923655edeb16613a1c31gstein and existing APIs that are expanded or changed. The latter are
2d71630471d1c23f0137309e3c3957c633ecbfd6rbb further divided into those where all changes are back-compatible
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding (so existing modules can ignore them), and those that might
449efc4dc68e42cc4421d15498a689618aab5dc3coar require attention by maintainers. As with the transition from
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding HTTPD 2.0 to 2.2, existing modules and applications will require
fd0edaa8e3d4dd67d0604ccef2e96b071db96643fielding recompiling and may call for some attention, but most should not
a877b7d5d03f91d6c93076d9ccf14469c70c648dcoar require any substantial updating (although some may be able to
1b21d7b3d97def358b2e923655edeb16613a1c31gstein take advantage of API changes to offer significant improvements).</p>
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding <p>For the purpose of this document, the API is split according
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding to the public header files. These headers are themselves the
a7ad08f37d876bde1a32f0cf793f4799536ab1a5ben reference documentation, and can be used to generate a browsable
ef5650b61a8e35f3cc93ec07e73efc17ea329894jorton<div id="quickview"><ul id="toc"><li><img alt="" src="/images/down.gif" /> <a href="#api_changes">Changed APIs</a></li>
076ae4ad21f0b3f25e2feabd9886b9500929eb2ejerenkrantz<li><img alt="" src="/images/down.gif" /> <a href="#upgrading">Specific information on upgrading modules from 2.2</a></li>
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
1ccd992d37d62c8cb2056126f2234f64ec189bfddougm<h2><a name="api_changes" id="api_changes">Changed APIs</a></h2>
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding <h3><a name="ap_expr" id="ap_expr">ap_expr (NEW!)</a></h3>
1ccd992d37d62c8cb2056126f2234f64ec189bfddougm <p>Introduces a new API to parse and evaluate boolean and algebraic
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding expressions, including provision for a standard syntax and
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding customised variants.</p>
1ccd992d37d62c8cb2056126f2234f64ec189bfddougm <h3><a name="ap_listen" id="ap_listen">ap_listen (changed; back-compatible)</a></h3>
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding <p>Introduces new API to enable apache child processes to serve different purposes.</p>
066877f1a045103acfdd376d48cdd473c33f409bdougm <h3><a name="ap_mpm" id="ap_mpm">ap_mpm (changed)</a></h3>
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding <p><code>ap_mpm_run</code> is replaced by a new <code>mpm</code> hook.
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding Also <code>ap_graceful_stop_signalled</code> is lost, and
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding <code>ap_mpm_register_timed_callback</code> is new.</p>
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding <h3><a name="ap_regex" id="ap_regex">ap_regex (changed)</a></h3>
066877f1a045103acfdd376d48cdd473c33f409bdougm <p>In addition to the existing regexp wrapper, a new higher-level API
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding <code>ap_rxplus</code> is now provided. This provides the capability to
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding compile Perl-style expressions like <code>s/regexp/replacement/flags</code>
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding and to execute them against arbitrary strings. Support for regexp
1ccd992d37d62c8cb2056126f2234f64ec189bfddougm backreference.</p>
1ccd992d37d62c8cb2056126f2234f64ec189bfddougm <h3><a name="ap_slotmem" id="ap_slotmem">ap_slotmem (NEW!)</a></h3>
076ae4ad21f0b3f25e2feabd9886b9500929eb2ejerenkrantz <p>Introduces an API for modules to allocate and manage memory slots
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding (normally) for shared memory.</p>
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding <h3><a name="ap_socache" id="ap_socache">ap_socache (NEW!)</a></h3>
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding <h3><a name="heartbeat" id="heartbeat">heartbeat (NEW!)</a></h3>
076ae4ad21f0b3f25e2feabd9886b9500929eb2ejerenkrantz <p>common structures for heartbeat modules (should this be public API?)</p>
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding <h3><a name="http_config" id="http_config">http_config (changed)</a></h3>
4d7e28c869788fb00bffda29a67f1b10e19f159dnd <li>Introduces per-module, per-directory loglevels, including macro wrappers.</li>
4d7e28c869788fb00bffda29a67f1b10e19f159dnd <li>New AP_DECLARE_MODULE macro to declare all modules.</li>
4d7e28c869788fb00bffda29a67f1b10e19f159dnd <li>New APLOG_USE_MODULE macro necessary for per-module loglevels in
a7ad08f37d876bde1a32f0cf793f4799536ab1a5ben multi-file modules.</li>
076ae4ad21f0b3f25e2feabd9886b9500929eb2ejerenkrantz <li>New API to retain data across module unload/load</li>
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding <li>New ap_process_fnmatch_configs() to process wildcards</li>
066877f1a045103acfdd376d48cdd473c33f409bdougm <h3><a name="http_core" id="http_core">http_core (changed)</a></h3>
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding <li>REMOVED ap_default_type, ap_requires, all 2.2 authnz API</li>
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding <li>Introduces Optional Functions for logio and authnz</li>
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding <li>New function ap_get_server_name_for_url to support ipv6 literals.</li>
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding <li>New function ap_register_errorlog_handler to register errorlog
ef5650b61a8e35f3cc93ec07e73efc17ea329894jorton format string handlers.</li>
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding <h3><a name="httpd" id="httpd">httpd (changed)</a></h3>
9bf4319b4fc7b31295b945215a55e2a92ba57903wrowe <li>Introduce errorlog ids for requests and connections</li>
9bf4319b4fc7b31295b945215a55e2a92ba57903wrowe <li>Support buffering filter data for async requests</li>
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding <li>Function changes: ap_escape_html updated; ap_unescape_all, ap_escape_path_segment_buffer</li>
4d7e28c869788fb00bffda29a67f1b10e19f159dnd <h3><a name="http_log" id="http_log">http_log (changed)</a></h3>
4d7e28c869788fb00bffda29a67f1b10e19f159dnd <li>ap_log_*error become macro wrappers (fully back-compatible if
615244e3f9a19f00f305be7520a604c65ebcc193trawick APLOG_MARK macro is used)</li>
1f0ca94141196628ecadf1a91f2b60a33349872fnd <h3><a name="http_request" id="http_request">http_request (changed)</a></h3>
4d7e28c869788fb00bffda29a67f1b10e19f159dnd <li>New flags AP_AUTH_INTERNAL_PER_CONF and AP_AUTH_INTERNAL_PER_URI</li>
4d7e28c869788fb00bffda29a67f1b10e19f159dnd <li>New access_checker_ex hook to apply additional access control and/or
4d7e28c869788fb00bffda29a67f1b10e19f159dnd bypass authentication.</li>
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding <li>New functions ap_hook_check_access_ex, ap_hook_check_access,
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding ap_hook_check_authn, ap_hook_check_authz which accept
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding AP_AUTH_INTERNAL_PER_* flags</li>
a7ad08f37d876bde1a32f0cf793f4799536ab1a5ben <li>DEPRECATED direct use of ap_hook_access_checker, access_checker_ex,
076ae4ad21f0b3f25e2feabd9886b9500929eb2ejerenkrantz ap_hook_check_user_id, ap_hook_auth_checker</li>
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding <p>When possible, registering all access control hooks (including
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding authentication and authorization hooks) using AP_AUTH_INTERNAL_PER_CONF
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding is recommended. If all modules' access control hooks are registered
a7ad08f37d876bde1a32f0cf793f4799536ab1a5ben with this flag, then whenever the server handles an internal
076ae4ad21f0b3f25e2feabd9886b9500929eb2ejerenkrantz sub-request that matches the same set of access control configuration
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding directives as the initial request (which is the common case), it can
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding avoid invoking the access control hooks another time.</p>
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding <p>If your module requires the old behavior and must perform access
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding control checks on every sub-request with a different URI from the
a7ad08f37d876bde1a32f0cf793f4799536ab1a5ben initial request, even if that URI matches the same set of access
076ae4ad21f0b3f25e2feabd9886b9500929eb2ejerenkrantz control configuration directives, then use AP_AUTH_INTERNAL_PER_URI.</p>
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding <h3><a name="mod_auth" id="mod_auth">mod_auth (NEW!)</a></h3>
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding <p>Introduces the new provider framework for authn and authz</p>
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding <h3><a name="mod_cache" id="mod_cache">mod_cache (changed)</a></h3>
a7ad08f37d876bde1a32f0cf793f4799536ab1a5ben <p>Introduces a commit_entity() function to the cache provider interface,
a7ad08f37d876bde1a32f0cf793f4799536ab1a5ben allowing atomic writes to cache. Add a cache_status() hook to report
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding the cache decision. Remove all private structures and functions from the
66a73d4405f9d941672c0343b36f6c494413a6b5rpluem <h3><a name="mod_core" id="mod_core">mod_core (NEW!)</a></h3>
172e83c0f024fe6396dd1f3ca3492fd83c304db5jim <p>This introduces low-level APIs to send arbitrary headers,
da128c59ec571c4dff70f41ecba9c8a9974c6cd6niq and exposes functions to handle HTTP OPTIONS and TRACE.</p>
da128c59ec571c4dff70f41ecba9c8a9974c6cd6niq <h3><a name="mod_disk_cache" id="mod_disk_cache">mod_disk_cache (changed)</a></h3>
da128c59ec571c4dff70f41ecba9c8a9974c6cd6niq <p>Changes the disk format of the disk cache to support atomic cache
da128c59ec571c4dff70f41ecba9c8a9974c6cd6niq updates without locking. The device/inode pair of the body file is
da128c59ec571c4dff70f41ecba9c8a9974c6cd6niq embedded in the header file, allowing confirmation that the header
da128c59ec571c4dff70f41ecba9c8a9974c6cd6niq and body belong to one another.</p>
076ae4ad21f0b3f25e2feabd9886b9500929eb2ejerenkrantz <h3><a name="mod_request" id="mod_request">mod_request (NEW!)</a></h3>
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding <p>The API for <code class="module"><a href="/mod/mod_request.html">mod_request</a></code>, to make input data
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding available to multiple application/handler modules where required,
ef5650b61a8e35f3cc93ec07e73efc17ea329894jorton and to parse HTML form data.</p>
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding <h3><a name="mpm_common" id="mpm_common">mpm_common (changed)</a></h3>
076ae4ad21f0b3f25e2feabd9886b9500929eb2ejerenkrantz <li>REMOVES: accept, lockfile, lock_mech, set_scoreboard (locking uses the new ap_mutex API)</li>
076ae4ad21f0b3f25e2feabd9886b9500929eb2ejerenkrantz <li>NEW API to drop privileges (delegates this platform-dependent
c7ab5a433d38d5eae5fc0bb76be80ffab6e4f71dniq function to modules)</li>
c7ab5a433d38d5eae5fc0bb76be80ffab6e4f71dniq <li>NEW Hooks: mpm_query, mpm_note_child_killed, timed_callback, get_name, and function ap_mpm_note_child_killed</li>
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding <h3><a name="scoreboard" id="scoreboard">scoreboard (changed)</a></h3>
076ae4ad21f0b3f25e2feabd9886b9500929eb2ejerenkrantz <p>ap_get_scoreboard_worker is gratuitously made non-back-compatible
076ae4ad21f0b3f25e2feabd9886b9500929eb2ejerenkrantz as an alternative version is introduced. Additional proxy_balancer
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding support. Child status stuff revamped.</p>
076ae4ad21f0b3f25e2feabd9886b9500929eb2ejerenkrantz <h3><a name="util_cookies" id="util_cookies">util_cookies (NEW!)</a></h3>
076ae4ad21f0b3f25e2feabd9886b9500929eb2ejerenkrantz <p>Introduces a new API for managing HTTP Cookies.</p>
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding <h3><a name="util_ldap" id="util_ldap">util_ldap (changed)</a></h3>
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding <h3><a name="util_mutex" id="util_mutex">util_mutex (NEW!)</a></h3>
a7ad08f37d876bde1a32f0cf793f4799536ab1a5ben <p>A wrapper for APR proc and global mutexes in httpd.</p>
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding <h3><a name="util_script" id="util_script">util_script (changed)</a></h3>
a7ad08f37d876bde1a32f0cf793f4799536ab1a5ben <h3><a name="util_time" id="util_time">util_time (changed)</a></h3>
076ae4ad21f0b3f25e2feabd9886b9500929eb2ejerenkrantz</div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding<h2><a name="upgrading" id="upgrading">Specific information on upgrading modules from 2.2</a></h2>
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding <h3><a name="upgrading_logging" id="upgrading_logging">Logging</a></h3>
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding <p>In order to take advantage of per-module loglevel configuration, any
4f9a74ad7e44b0464f7cf56525a205d788becacbtrawick source file that calls the <code>ap_log_*</code> functions should declare
4f9a74ad7e44b0464f7cf56525a205d788becacbtrawick which module it belongs to. If the module's module_struct is called
4f9a74ad7e44b0464f7cf56525a205d788becacbtrawick <code>foo_module</code>, the following code can be used to remain
4f9a74ad7e44b0464f7cf56525a205d788becacbtrawick backward compatible with HTTPD 2.0 and 2.2:</p>
4f9a74ad7e44b0464f7cf56525a205d788becacbtrawick #ifdef APLOG_USE_MODULE<br />
4f9a74ad7e44b0464f7cf56525a205d788becacbtrawick APLOG_USE_MODULE(foo);<br />
4f9a74ad7e44b0464f7cf56525a205d788becacbtrawick <p>The number of parameters of the <code>ap_log_*</code> functions and the
e8f95a682820a599fe41b22977010636be5c2717jim definition of <code>APLOG_MARK</code> has changed. Normally, the change
4f9a74ad7e44b0464f7cf56525a205d788becacbtrawick is completely transparent. However, if a module implements wrapper
4f9a74ad7e44b0464f7cf56525a205d788becacbtrawick functions for <code>ap_log_*</code> and uses <code>APLOG_MARK</code>
4f9a74ad7e44b0464f7cf56525a205d788becacbtrawick when calling these wrappers, some adjustments are necessary.
a7ad08f37d876bde1a32f0cf793f4799536ab1a5ben The easiest way is for the module to define and use a different macro
076ae4ad21f0b3f25e2feabd9886b9500929eb2ejerenkrantz that expands to the parameters required by the log wrapper functions.
4f9a74ad7e44b0464f7cf56525a205d788becacbtrawick <code>APLOG_MARK</code> should only be used when calling
e8f95a682820a599fe41b22977010636be5c2717jim <code>ap_log_*</code> without additional wrappers. In this way, the
4f9a74ad7e44b0464f7cf56525a205d788becacbtrawick code will remain compatible with HTTPD 2.0 and 2.2.</p>
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding<p><span>Available Languages: </span><a href="/en/developer/new_api_2_4.html" title="English"> en </a></p>
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding<p class="apache">Copyright 2010 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>
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding<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>