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