docs/manual/developer/new_api_2_4.xml - httpd - Git at Google

 <?xml version='1.0' encoding='UTF-8' ?>
 <!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd">
 <?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
 <!-- $LastChangedRevision$ -->

 <!--
  Licensed to the Apache Software Foundation (ASF) under one or more
  contributor license agreements.  See the NOTICE file distributed with
  this work for additional information regarding copyright ownership.
  The ASF licenses this file to You under the Apache License, Version 2.0
  (the "License"); you may not use this file except in compliance with
  the License.  You may obtain a copy of the License at

      http://www.apache.org/licenses/LICENSE-2.0

  Unless required by applicable law or agreed to in writing, software
  distributed under the License is distributed on an "AS IS" BASIS,
  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  See the License for the specific language governing permissions and
  limitations under the License.
 -->

 <manualpage metafile="new_api_2_4.xml.meta">

 <title>API Changes in Apache HTTP Server 2.4 since 2.2</title>

 <summary>
   <p>This document describes changes to the Apache HTTPD API from
      version 2.2 to 2.4, that may be of interest to module/application
      developers and core hacks.  At the time of writing, the 2.4 API
      is not finalised, and this document may serve to highlight
      points that call for further review.</p>
   <p>API changes fall into two categories: APIs that are altogether new,
      and existing APIs that are expanded or changed.  The latter are
      further divided into those where all changes are back-compatible
      (so existing modules can ignore them), and those that might
      require attention by maintainers.  As with the transition from
      HTTPD 2.0 to 2.2, existing modules and applications will require
      recompiling and may call for some attention, but most should not
      require any substantial updating (although some may be able to
      take advantage of API changes to offer significant improvements).</p>
   <p>For the purpose of this document, the API is split according
      to the public header files.  These headers are themselves the
      reference documentation, and can be used to generate a browsable
      HTML reference with <code>make docs</code>.</p>
 </summary>

 <section id="api_changes">
   <title>Changed APIs</title>

   <section id="ap_expr">
     <title>ap_expr (NEW!)</title>
     <p>Introduces a new API to parse and evaluate boolean and algebraic
        expressions, including provision for a standard syntax and
        customised variants.</p>
   </section>

   <section id="ap_listen">
     <title>ap_listen (changed; back-compatible)</title>
     <p>Introduces new API to enable apache child processes to serve different purposes.</p>
   </section>

   <section id="ap_mpm">
     <title>ap_mpm (changed)</title>
   <p><code>ap_mpm_run</code> is replaced by a new <code>mpm</code> hook.
   Also <code>ap_graceful_stop_signalled</code> is lost, and
   <code>ap_mpm_register_timed_callback</code> is new.</p>
   </section>

   <section id="ap_regex">
     <title>ap_regex (changed)</title>
   <p>In addition to the existing regexp wrapper, a new higher-level API
   <code>ap_rxplus</code> is now provided.  This provides the capability to
   compile Perl-style expressions like <code>s/regexp/replacement/flags</code>
   and to execute them against arbitrary strings. Support for regexp
   backreference.</p>
   </section>

   <section id="ap_slotmem">
     <title>ap_slotmem (NEW!)</title>
     <p>Introduces an API for modules to allocate and manage memory slots
     (normally) for shared memory.</p>
   </section>

   <section id="ap_socache">
     <title>ap_socache (NEW!)</title>
     <p>API to manage a shared object cache.</p>
   </section>

   <section id="heartbeat">
     <title>heartbeat (NEW!)</title>
     <p>common structures for heartbeat modules (should this be public API?)</p>
   </section>

   <section id="http_config">
     <title>http_config (changed)</title>
     <ul>
       <li>Introduces per-module, per-directory loglevels, including macro wrappers.</li>
       <li>New AP_DECLARE_MODULE macro to declare all modules.</li>
       <li>New APLOG_USE_MODULE macro necessary for per-module loglevels in
           multi-file modules.</li>
       <li>New API to retain data across module unload/load</li>
       <li>New check_config hook</li>
       <li>New ap_process_fnmatch_configs() to process wildcards</li>
       <li>Change ap_configfile_t, ap_cfg_getline(), ap_cfg_getc() to return error
           code, new ap_pcfg_strerror().</li>
     </ul>
   </section>

   <section id="http_core">
     <title>http_core (changed)</title>
     <ul>
       <li>REMOVED ap_default_type, ap_requires, all 2.2 authnz API</li>
       <li>Introduces Optional Functions for logio and authnz</li>
       <li>New function ap_get_server_name_for_url to support ipv6 literals.</li>
       <li>New function ap_register_errorlog_handler to register errorlog
           format string handlers.</li>
       <li>New function ap_state_query to determine if the server is in the
           initial configuration preflight phase or not. This is both easier to
           use and more correct than the old method of creating a pool userdata
           entry in the process pool.</li>
       <li>New function ap_get_conn_socket to get the socket descriptor for a
           connection. This should be used instead of accessing the core
           connection config directly.</li>
     </ul>
   </section>

   <section id="httpd">
     <title>httpd (changed)</title>
     <ul>
       <li>Introduce per-directory, per-module loglevel</li>
       <li>New loglevels APLOG_TRACEn</li>
       <li>Introduce errorlog ids for requests and connections</li>
       <li>Support for mod_request kept_body</li>
       <li>Support buffering filter data for async requests</li>
       <li>New CONN_STATE values</li>
       <li>Function changes: ap_escape_html updated; ap_unescape_all,
           ap_escape_path_segment_buffer</li>
       <li>Modules that load other modules later than the EXEC_ON_READ config
           reading stage need to call ap_reserve_module_slots() or
           ap_reserve_module_slots_directive() in their pre_config hook.</li>
     </ul>
   </section>

   <section id="http_log">
     <title>http_log (changed)</title>
     <ul>
       <li>Introduce per-directory, per-module loglevel</li>
       <li>New loglevels APLOG_TRACEn</li>
       <li>ap_log_*error become macro wrappers (fully back-compatible if
           APLOG_MARK macro is used)</li>
       <li>piped logging revamped</li>
       <li>module_index added to error_log hook</li>
       <li>new function: ap_log_command_line</li>
     </ul>
   </section>

   <section id="http_request">
     <title>http_request (changed)</title>
     <ul>
       <li>New auth_internal API and auth_provider API</li>
       <li>New EOR bucket type</li>
       <li>New function ap_process_async_request</li>
       <li>New flags AP_AUTH_INTERNAL_PER_CONF and AP_AUTH_INTERNAL_PER_URI</li>
       <li>New access_checker_ex hook to apply additional access control and/or
           bypass authentication.</li>
       <li>New functions ap_hook_check_access_ex, ap_hook_check_access,
           ap_hook_check_authn, ap_hook_check_authz which accept
           AP_AUTH_INTERNAL_PER_* flags</li>
       <li>DEPRECATED direct use of ap_hook_access_checker, access_checker_ex,
           ap_hook_check_user_id, ap_hook_auth_checker</li>
     </ul>
     <p>When possible, registering all access control hooks (including
        authentication and authorization hooks) using AP_AUTH_INTERNAL_PER_CONF
        is recommended.  If all modules' access control hooks are registered
        with this flag, then whenever the server handles an internal
        sub-request that matches the same set of access control configuration
        directives as the initial request (which is the common case), it can
        avoid invoking the access control hooks another time.</p>
     <p>If your module requires the old behavior and must perform access
        control checks on every sub-request with a different URI from the
        initial request, even if that URI matches the same set of access
        control configuration directives, then use AP_AUTH_INTERNAL_PER_URI.</p>
   </section>

   <section id="mod_auth">
     <title>mod_auth (NEW!)</title>
     <p>Introduces the new provider framework for authn and authz</p>
   </section>

   <section id="mod_cache">
     <title>mod_cache (changed)</title>
     <p>Introduces a commit_entity() function to the cache provider interface,
     allowing atomic writes to cache. Add a cache_status() hook to report
     the cache decision. Remove all private structures and functions from the
     public mod_cache.h header file.</p>
   </section>

   <section id="mod_core">
     <title>mod_core (NEW!)</title>
     <p>This introduces low-level APIs to send arbitrary headers,
     and exposes functions to handle HTTP OPTIONS and TRACE.</p>
   </section>

   <section id="mod_cache_disk">
     <title>mod_cache_disk (changed)</title>
     <p>Changes the disk format of the disk cache to support atomic cache
     updates without locking. The device/inode pair of the body file is
     embedded in the header file, allowing confirmation that the header
     and body belong to one another.</p>
   </section>

   <section id="mod_disk_cache">
     <title>mod_disk_cache (renamed)</title>
     <p>The mod_disk_cache module has been renamed to mod_cache_disk in
     order to be consistent with the naming of other modules within the
     server.</p>
   </section>

   <section id="mod_request">
     <title>mod_request (NEW!)</title>
     <p>The API for <module>mod_request</module>, to make input data
     available to multiple application/handler modules where required,
     and to parse HTML form data.</p>
   </section>

   <section id="mpm_common">
     <title>mpm_common (changed)</title>
     <ul>
       <li>REMOVES: accept, lockfile, lock_mech, set_scoreboard (locking uses the new ap_mutex API)</li>
       <li>NEW API to drop privileges (delegates this platform-dependent
           function to modules)</li>
       <li>NEW Hooks: mpm_query, timed_callback, and get_name</li>
       <li>CHANGED interfaces: monitor hook,
       ap_reclaim_child_processes, ap_relieve_child_processes</li>
     </ul>
   </section>

   <section id="scoreboard">
     <title>scoreboard (changed)</title>
     <p>ap_get_scoreboard_worker is gratuitously made non-back-compatible
     as an alternative version is introduced.  Additional proxy_balancer
     support.  Child status stuff revamped.</p>
   </section>

   <section id="util_cookies">
     <title>util_cookies (NEW!)</title>
     <p>Introduces a new API for managing HTTP Cookies.</p>
   </section>

   <section id="util_ldap">
     <title>util_ldap (changed)</title>
     <p>I have yet to get a handle on this update.</p>
   </section>

   <section id="util_mutex">
     <title>util_mutex (NEW!)</title>
     <p>A wrapper for APR proc and global mutexes in httpd.</p>
   </section>

   <section id="util_script">
     <title>util_script (changed)</title>
     <p>NEW: ap_args_to_table</p>
   </section>

   <section id="util_time">
     <title>util_time (changed)</title>
     <p>NEW: ap_recent_ctime_ex</p>
   </section>

 </section>

 <section id="upgrading">
   <title>Specific information on upgrading modules from 2.2</title>

   <section id="upgrading_logging">
     <title>Logging</title>
     <p>In order to take advantage of per-module loglevel configuration, any
        source file that calls the <code>ap_log_*</code> functions should declare
        which module it belongs to. If the module's module_struct is called
        <code>foo_module</code>, the following code can be used to remain
        backward compatible with HTTPD 2.0 and 2.2:</p>
     <example>
         #include &lt;http_log.h&gt;<br/>
         <br/>
         #ifdef APLOG_USE_MODULE<br/>
         APLOG_USE_MODULE(foo);<br/>
         #endif
     </example>
     <p>Note: This is absolutely required for C++-language modules.  It
     can be skipped for C-language modules, though that breaks
     module-specific log level support for files without it.</p>
     <p>The number of parameters of the <code>ap_log_*</code> functions and the
        definition of <code>APLOG_MARK</code> has changed. Normally, the change
        is completely transparent. However, changes are required if a
        module uses <code>APLOG_MARK</code> as a parameter to its own functions
        or if a module calls <code>ap_log_*</code> without passing
        <code>APLOG_MARK</code>.  A module which uses wrappers
        around <code>ap_log_*</code> typically uses both of these constructs.</p>

     <p>The easiest way to change code which passes <code>APLOG_MARK</code> to
        its own functions is to define and use a different macro that expands to
        the parameters required by those functions, as <code>APLOG_MARK</code>
        should only be used when calling <code>ap_log_*</code>
        directly.  In this way, the code will remain compatible with HTTPD 2.0
        and 2.2.</p>

     <p>Code which calls <code>ap_log_*</code> without passing
        <code>APLOG_MARK</code> will necessarily differ between 2.4 and earlier
        releases, as 2.4 requires a new third argument,
        <code>APLOG_MODULE_INDEX</code>.</p>

     <example>
        /* code for httpd 2.0/2.2 */<br />
        ap_log_perror(file, line, APLOG_ERR, 0, p, "Failed to allocate dynamic lock structure");<br />
        <br />
        /* code for httpd 2.4 */<br />
        ap_log_perror(file, line, APLOG_MODULE_INDEX, APLOG_ERR, 0, p, "Failed to allocate dynamic lock structure");<br />
        <br />
     </example>

     <p>A <code>server_rec</code> pointer must be passed to
        <code>ap_log_error()</code> when called after startup.  This
        was always appropriate, but there are even more limitations with
        a <code>NULL</code> <code>server_rec</code> in 2.4 than in
        previous releases.  Beginning with 2.3.12, the global variable
        <code>ap_server_conf</code> can always be used as
        the <code>server_rec</code> parameter, as it will be
        <code>NULL</code> only when it is valid to pass <code>NULL</code>
        to <code>ap_log_error()</code>.  <code>ap_server_conf</code>
        should be used only when a more appropriate <code>server_rec</code>
        is not available.</p>

     <p>Consider the following changes to take advantage of the new
        <code>APLOG_TRACE1..8</code> log levels:</p>
        <ul>
          <li>Check current use of <code>APLOG_DEBUG</code> and
          consider if one of the <code>APLOG_TRACEn</code> levels is
          more appropriate.</li>
          <li>If your module currently has a mechanism for configuring
          the amount of debug logging which is performed, consider
          eliminating that mechanism and relying on the use of
          different <code>APLOG_TRACEn</code> levels.  If expensive
          trace processing needs to be bypassed depending on the
          configured log level, use the <code>APLOGtrace<em>n</em></code>
          and <code>APLOGrtrace<em>n</em></code> macros to first check
          if tracing is enabled.</li>
        </ul>

     <p>Modules sometimes add process id and/or thread id to their log
        messages.  These ids are now logged by default, so it may not
        be necessary for the module to log them explicitly.  (Users may
        remove them from the error log format, but they can be
        instructed to add it back if necessary for problem diagnosis.)</p>
   </section>

   <section id="upgrading_byfunction">
     <title>If your module uses these existing APIs...</title>

     <dl>
       <dt><code>ap_default_type()</code></dt>
       <dd>This is no longer available; Content-Type must be configured
           explicitly or added by the application.</dd>

       <dt><code>ap_get_server_name()</code></dt>
       <dd>If the returned server name is used in a URL,
       use <code>ap_get_server_name_for_url()</code> instead.  This new
       function handles the odd case where the server name is an IPv6
       literal address.</dd>

       <dt><code>ap_get_server_version()</code></dt>
       <dd>For logging purposes, where detailed information is
           appropriate, use <code>ap_get_server_description()</code>.
           When generating output, where the amount of information
           should be configurable by ServerTokens, use
           <code>ap_get_server_banner()</code>.</dd>

       <dt><code>ap_graceful_stop_signalled()</code></dt>
       <dd>Replace with a call
       to <code>ap_mpm_query(AP_MPMQ_MPM_STATE)</code> and checking for
       state <code>AP_MPMQ_STOPPING</code>.</dd>

       <dt><code>ap_max_daemons_limit</code>, <code>ap_my_generation</code>,
           and <code>ap_threads_per_child</code></dt>
       <dd>Use <code>ap_mpm_query()</code> query codes
           <code>AP_MPMQ_MAX_DAEMON_USED</code>, <code>AP_MPMQ_GENERATION</code>,
           and <code>AP_MPMQ_MAX_THREADS</code>, respectively.</dd>

       <dt><code>ap_mpm_query()</code></dt>
       <dd>Ensure that it is not used until after the register-hooks
           hook has completed.  Otherwise, an MPM built as a DSO
           would not have had a chance to enable support for this
           function.</dd>

       <dt><code>ap_server_conf->process->pool</code>
       userdata</dt>
       <dd>
         Optional:
         <ul>
           <li>If your module uses this to determine which pass of the
 	  startup hooks is being run,
 	  use <code>ap_state_query(AP_SQ_MAIN_STATE)</code>.</li>
           <li>If your module uses this to maintain data across the
           unloading and reloading of your module, use
           <code>ap_retained_data_create()</code> and
           <code>ap_retained_data_get()</code>.</li>
         </ul>
       </dd>

       <dt><code>apr_global_mutex_create()</code>,
           <code>apr_proc_mutex_create()</code></dt>
       <dd>Optional: See <code>ap_mutex_register()</code>,
           <code>ap_global_mutex_create()</code>, and
           <code>ap_proc_mutex_create()</code>; these allow your
           mutexes to be configurable with
           the <directive module="core">Mutex</directive> directive;
           you can also remove any configuration mechanisms in your
           module for such mutexes
       </dd>

       <dt><code>CORE_PRIVATE</code></dt>
       <dd>This is now unnecessary and ignored.</dd>

       <dt><code>dav_new_error()</code>
       and <code>dav_new_error_tag()</code></dt>
       <dd>Previously, these assumed that <code>errno</code> contained
       information describing the failure.  Now,
       an <code>apr_status_t</code> parameter must be provided.  Pass
       0/APR_SUCCESS if there is no such error information, or a valid
       <code>apr_status_t</code> value otherwise.</dd>

       <dt><code>mpm_default.h</code>, <code>DEFAULT_LOCKFILE</code>,
       <code>DEFAULT_THREAD_LIMIT</code>, <code>DEFAULT_PIDLOG</code>,
       etc.</dt>
       <dd>The header file and most of the default configuration
       values set in it are no longer visible to modules.  (Most can
       still be overridden at build time.)  <code>DEFAULT_PIDLOG</code>
       and <code>DEFAULT_REL_RUNTIMEDIR</code> are now universally
       available via <code>ap_config.h</code>.</dd>

       <dt><code>unixd_config</code></dt>
       <dd>This has been renamed to ap_unixd_config.</dd>
     </dl>
   </section>

   <section id="upgrading_byfeature">
     <title>If your module interfaces with this feature...</title>
     <dl>
       <dt>suEXEC</dt>
       <dd>Optional: If your module logs an error
           when <code>ap_unixd_config.suexec_enabled</code> is 0,
           also log the value of the new
           field <code>suexec_disabled_reason</code>, which contains an
           explanation of why it is not available.</dd>

       <dt>Extended status data in the scoreboard</dt>
       <dd>In previous releases, <code>ExtendedStatus</code> had to be
           set to <code>On</code>, which in turn required that
           mod_status was loaded.  In 2.4, just
           set <code>ap_extended_status</code> to <code>1</code> in a
           pre-config hook and the extended status data will be
           available.</dd>

     </dl>
   </section>

   <section id="upgrading_newfeatures">
     <title>Does your module...</title>
     <dl>
     <dt>Parse query args</dt>
     <dd>Consider if <code>ap_args_to_table()</code> would be
     helpful.</dd>

     <dt>Parse form data...</dt>
     <dd>Use <code>ap_parse_form_data()</code>.</dd>

     <dt>Check for request header fields <code>Content-Length</code>
     and <code>Transfer-Encoding</code> to see if a body was
     specified</dt>
     <dd>Use <code>ap_request_has_body()</code>.</dd>

     <dt>Implement cleanups which clear pointer variables</dt>
     <dd>Use <code>ap_pool_cleanup_set_null()</code>.</dd>
     </dl>
   </section>

 </section>

 </manualpage>
	<?xml version='1.0' encoding='UTF-8' ?>
	<!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd">
	<?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
	<!-- $LastChangedRevision$ -->

	<!--
	Licensed to the Apache Software Foundation (ASF) under one or more
	contributor license agreements. See the NOTICE file distributed with
	this work for additional information regarding copyright ownership.
	The ASF licenses this file to You under the Apache License, Version 2.0
	(the "License"); you may not use this file except in compliance with
	the License. You may obtain a copy of the License at

	http://www.apache.org/licenses/LICENSE-2.0

	Unless required by applicable law or agreed to in writing, software
	distributed under the License is distributed on an "AS IS" BASIS,
	WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
	See the License for the specific language governing permissions and
	limitations under the License.
	-->

	<manualpage metafile="new_api_2_4.xml.meta">

	<title>API Changes in Apache HTTP Server 2.4 since 2.2</title>

	<summary>
	<p>This document describes changes to the Apache HTTPD API from
	version 2.2 to 2.4, that may be of interest to module/application
	developers and core hacks. At the time of writing, the 2.4 API
	is not finalised, and this document may serve to highlight
	points that call for further review.</p>
	<p>API changes fall into two categories: APIs that are altogether new,
	and existing APIs that are expanded or changed. The latter are
	further divided into those where all changes are back-compatible
	(so existing modules can ignore them), and those that might
	require attention by maintainers. As with the transition from
	HTTPD 2.0 to 2.2, existing modules and applications will require
	recompiling and may call for some attention, but most should not
	require any substantial updating (although some may be able to
	take advantage of API changes to offer significant improvements).</p>
	<p>For the purpose of this document, the API is split according
	to the public header files. These headers are themselves the
	reference documentation, and can be used to generate a browsable
	HTML reference with <code>make docs</code>.</p>
	</summary>

	<section id="api_changes">
	<title>Changed APIs</title>

	<section id="ap_expr">
	<title>ap_expr (NEW!)</title>
	<p>Introduces a new API to parse and evaluate boolean and algebraic
	expressions, including provision for a standard syntax and
	customised variants.</p>
	</section>

	<section id="ap_listen">
	<title>ap_listen (changed; back-compatible)</title>
	<p>Introduces new API to enable apache child processes to serve different purposes.</p>
	</section>

	<section id="ap_mpm">
	<title>ap_mpm (changed)</title>
	<p><code>ap_mpm_run</code> is replaced by a new <code>mpm</code> hook.
	Also <code>ap_graceful_stop_signalled</code> is lost, and
	<code>ap_mpm_register_timed_callback</code> is new.</p>
	</section>

	<section id="ap_regex">
	<title>ap_regex (changed)</title>
	<p>In addition to the existing regexp wrapper, a new higher-level API
	<code>ap_rxplus</code> is now provided. This provides the capability to
	compile Perl-style expressions like <code>s/regexp/replacement/flags</code>
	and to execute them against arbitrary strings. Support for regexp
	backreference.</p>
	</section>

	<section id="ap_slotmem">
	<title>ap_slotmem (NEW!)</title>
	<p>Introduces an API for modules to allocate and manage memory slots
	(normally) for shared memory.</p>
	</section>

	<section id="ap_socache">
	<title>ap_socache (NEW!)</title>
	<p>API to manage a shared object cache.</p>
	</section>

	<section id="heartbeat">
	<title>heartbeat (NEW!)</title>
	<p>common structures for heartbeat modules (should this be public API?)</p>
	</section>

	<section id="http_config">
	<title>http_config (changed)</title>
	<ul>
	<li>Introduces per-module, per-directory loglevels, including macro wrappers.</li>
	<li>New AP_DECLARE_MODULE macro to declare all modules.</li>
	<li>New APLOG_USE_MODULE macro necessary for per-module loglevels in
	multi-file modules.</li>
	<li>New API to retain data across module unload/load</li>
	<li>New check_config hook</li>
	<li>New ap_process_fnmatch_configs() to process wildcards</li>
	<li>Change ap_configfile_t, ap_cfg_getline(), ap_cfg_getc() to return error
	code, new ap_pcfg_strerror().</li>
	</ul>
	</section>

	<section id="http_core">
	<title>http_core (changed)</title>
	<ul>
	<li>REMOVED ap_default_type, ap_requires, all 2.2 authnz API</li>
	<li>Introduces Optional Functions for logio and authnz</li>
	<li>New function ap_get_server_name_for_url to support ipv6 literals.</li>
	<li>New function ap_register_errorlog_handler to register errorlog
	format string handlers.</li>
	<li>New function ap_state_query to determine if the server is in the
	initial configuration preflight phase or not. This is both easier to
	use and more correct than the old method of creating a pool userdata
	entry in the process pool.</li>
	<li>New function ap_get_conn_socket to get the socket descriptor for a
	connection. This should be used instead of accessing the core
	connection config directly.</li>
	</ul>
	</section>

	<section id="httpd">
	<title>httpd (changed)</title>
	<ul>
	<li>Introduce per-directory, per-module loglevel</li>
	<li>New loglevels APLOG_TRACEn</li>
	<li>Introduce errorlog ids for requests and connections</li>
	<li>Support for mod_request kept_body</li>
	<li>Support buffering filter data for async requests</li>
	<li>New CONN_STATE values</li>
	<li>Function changes: ap_escape_html updated; ap_unescape_all,
	ap_escape_path_segment_buffer</li>
	<li>Modules that load other modules later than the EXEC_ON_READ config
	reading stage need to call ap_reserve_module_slots() or
	ap_reserve_module_slots_directive() in their pre_config hook.</li>
	</ul>
	</section>

	<section id="http_log">
	<title>http_log (changed)</title>
	<ul>
	<li>Introduce per-directory, per-module loglevel</li>
	<li>New loglevels APLOG_TRACEn</li>
	<li>ap_log_*error become macro wrappers (fully back-compatible if
	APLOG_MARK macro is used)</li>
	<li>piped logging revamped</li>
	<li>module_index added to error_log hook</li>
	<li>new function: ap_log_command_line</li>
	</ul>
	</section>

	<section id="http_request">
	<title>http_request (changed)</title>
	<ul>
	<li>New auth_internal API and auth_provider API</li>
	<li>New EOR bucket type</li>
	<li>New function ap_process_async_request</li>
	<li>New flags AP_AUTH_INTERNAL_PER_CONF and AP_AUTH_INTERNAL_PER_URI</li>
	<li>New access_checker_ex hook to apply additional access control and/or
	bypass authentication.</li>
	<li>New functions ap_hook_check_access_ex, ap_hook_check_access,
	ap_hook_check_authn, ap_hook_check_authz which accept
	AP_AUTH_INTERNAL_PER_* flags</li>
	<li>DEPRECATED direct use of ap_hook_access_checker, access_checker_ex,
	ap_hook_check_user_id, ap_hook_auth_checker</li>
	</ul>
	<p>When possible, registering all access control hooks (including
	authentication and authorization hooks) using AP_AUTH_INTERNAL_PER_CONF
	is recommended. If all modules' access control hooks are registered
	with this flag, then whenever the server handles an internal
	sub-request that matches the same set of access control configuration
	directives as the initial request (which is the common case), it can
	avoid invoking the access control hooks another time.</p>
	<p>If your module requires the old behavior and must perform access
	control checks on every sub-request with a different URI from the
	initial request, even if that URI matches the same set of access
	control configuration directives, then use AP_AUTH_INTERNAL_PER_URI.</p>
	</section>

	<section id="mod_auth">
	<title>mod_auth (NEW!)</title>
	<p>Introduces the new provider framework for authn and authz</p>
	</section>

	<section id="mod_cache">
	<title>mod_cache (changed)</title>
	<p>Introduces a commit_entity() function to the cache provider interface,
	allowing atomic writes to cache. Add a cache_status() hook to report
	the cache decision. Remove all private structures and functions from the
	public mod_cache.h header file.</p>
	</section>

	<section id="mod_core">
	<title>mod_core (NEW!)</title>
	<p>This introduces low-level APIs to send arbitrary headers,
	and exposes functions to handle HTTP OPTIONS and TRACE.</p>
	</section>

	<section id="mod_cache_disk">
	<title>mod_cache_disk (changed)</title>
	<p>Changes the disk format of the disk cache to support atomic cache
	updates without locking. The device/inode pair of the body file is
	embedded in the header file, allowing confirmation that the header
	and body belong to one another.</p>
	</section>

	<section id="mod_disk_cache">
	<title>mod_disk_cache (renamed)</title>
	<p>The mod_disk_cache module has been renamed to mod_cache_disk in
	order to be consistent with the naming of other modules within the
	server.</p>
	</section>

	<section id="mod_request">
	<title>mod_request (NEW!)</title>
	<p>The API for <module>mod_request</module>, to make input data
	available to multiple application/handler modules where required,
	and to parse HTML form data.</p>
	</section>

	<section id="mpm_common">
	<title>mpm_common (changed)</title>
	<ul>
	<li>REMOVES: accept, lockfile, lock_mech, set_scoreboard (locking uses the new ap_mutex API)</li>
	<li>NEW API to drop privileges (delegates this platform-dependent
	function to modules)</li>
	<li>NEW Hooks: mpm_query, timed_callback, and get_name</li>
	<li>CHANGED interfaces: monitor hook,
	ap_reclaim_child_processes, ap_relieve_child_processes</li>
	</ul>
	</section>

	<section id="scoreboard">
	<title>scoreboard (changed)</title>
	<p>ap_get_scoreboard_worker is gratuitously made non-back-compatible
	as an alternative version is introduced. Additional proxy_balancer
	support. Child status stuff revamped.</p>
	</section>

	<section id="util_cookies">
	<title>util_cookies (NEW!)</title>
	<p>Introduces a new API for managing HTTP Cookies.</p>
	</section>

	<section id="util_ldap">
	<title>util_ldap (changed)</title>
	<p>I have yet to get a handle on this update.</p>
	</section>

	<section id="util_mutex">
	<title>util_mutex (NEW!)</title>
	<p>A wrapper for APR proc and global mutexes in httpd.</p>
	</section>

	<section id="util_script">
	<title>util_script (changed)</title>
	<p>NEW: ap_args_to_table</p>
	</section>

	<section id="util_time">
	<title>util_time (changed)</title>
	<p>NEW: ap_recent_ctime_ex</p>
	</section>

	</section>

	<section id="upgrading">
	<title>Specific information on upgrading modules from 2.2</title>

	<section id="upgrading_logging">
	<title>Logging</title>
	<p>In order to take advantage of per-module loglevel configuration, any
	source file that calls the <code>ap_log_*</code> functions should declare
	which module it belongs to. If the module's module_struct is called
	<code>foo_module</code>, the following code can be used to remain
	backward compatible with HTTPD 2.0 and 2.2:</p>
	<example>
	#include <http_log.h><br/>
	<br/>
	#ifdef APLOG_USE_MODULE<br/>
	APLOG_USE_MODULE(foo);<br/>
	#endif
	</example>
	<p>Note: This is absolutely required for C++-language modules. It
	can be skipped for C-language modules, though that breaks
	module-specific log level support for files without it.</p>
	<p>The number of parameters of the <code>ap_log_*</code> functions and the
	definition of <code>APLOG_MARK</code> has changed. Normally, the change
	is completely transparent. However, changes are required if a
	module uses <code>APLOG_MARK</code> as a parameter to its own functions
	or if a module calls <code>ap_log_*</code> without passing
	<code>APLOG_MARK</code>. A module which uses wrappers
	around <code>ap_log_*</code> typically uses both of these constructs.</p>

	<p>The easiest way to change code which passes <code>APLOG_MARK</code> to
	its own functions is to define and use a different macro that expands to
	the parameters required by those functions, as <code>APLOG_MARK</code>
	should only be used when calling <code>ap_log_*</code>
	directly. In this way, the code will remain compatible with HTTPD 2.0
	and 2.2.</p>

	<p>Code which calls <code>ap_log_*</code> without passing
	<code>APLOG_MARK</code> will necessarily differ between 2.4 and earlier
	releases, as 2.4 requires a new third argument,
	<code>APLOG_MODULE_INDEX</code>.</p>

	<example>
	/* code for httpd 2.0/2.2 */<br />
	ap_log_perror(file, line, APLOG_ERR, 0, p, "Failed to allocate dynamic lock structure");<br />
	<br />
	/* code for httpd 2.4 */<br />
	ap_log_perror(file, line, APLOG_MODULE_INDEX, APLOG_ERR, 0, p, "Failed to allocate dynamic lock structure");<br />
	<br />
	</example>

	<p>A <code>server_rec</code> pointer must be passed to
	<code>ap_log_error()</code> when called after startup. This
	was always appropriate, but there are even more limitations with
	a <code>NULL</code> <code>server_rec</code> in 2.4 than in
	previous releases. Beginning with 2.3.12, the global variable
	<code>ap_server_conf</code> can always be used as
	the <code>server_rec</code> parameter, as it will be
	<code>NULL</code> only when it is valid to pass <code>NULL</code>
	to <code>ap_log_error()</code>. <code>ap_server_conf</code>
	should be used only when a more appropriate <code>server_rec</code>
	is not available.</p>

	<p>Consider the following changes to take advantage of the new
	<code>APLOG_TRACE1..8</code> log levels:</p>
	<ul>
	<li>Check current use of <code>APLOG_DEBUG</code> and
	consider if one of the <code>APLOG_TRACEn</code> levels is
	more appropriate.</li>
	<li>If your module currently has a mechanism for configuring
	the amount of debug logging which is performed, consider
	eliminating that mechanism and relying on the use of
	different <code>APLOG_TRACEn</code> levels. If expensive
	trace processing needs to be bypassed depending on the
	configured log level, use the <code>APLOGtrace<em>n</em></code>
	and <code>APLOGrtrace<em>n</em></code> macros to first check
	if tracing is enabled.</li>
	</ul>

	<p>Modules sometimes add process id and/or thread id to their log
	messages. These ids are now logged by default, so it may not
	be necessary for the module to log them explicitly. (Users may
	remove them from the error log format, but they can be
	instructed to add it back if necessary for problem diagnosis.)</p>
	</section>

	<section id="upgrading_byfunction">
	<title>If your module uses these existing APIs...</title>

	<dl>
	<dt><code>ap_default_type()</code></dt>
	<dd>This is no longer available; Content-Type must be configured
	explicitly or added by the application.</dd>

	<dt><code>ap_get_server_name()</code></dt>
	<dd>If the returned server name is used in a URL,
	use <code>ap_get_server_name_for_url()</code> instead. This new
	function handles the odd case where the server name is an IPv6
	literal address.</dd>

	<dt><code>ap_get_server_version()</code></dt>
	<dd>For logging purposes, where detailed information is
	appropriate, use <code>ap_get_server_description()</code>.
	When generating output, where the amount of information
	should be configurable by ServerTokens, use
	<code>ap_get_server_banner()</code>.</dd>

	<dt><code>ap_graceful_stop_signalled()</code></dt>
	<dd>Replace with a call
	to <code>ap_mpm_query(AP_MPMQ_MPM_STATE)</code> and checking for
	state <code>AP_MPMQ_STOPPING</code>.</dd>

	<dt><code>ap_max_daemons_limit</code>, <code>ap_my_generation</code>,
	and <code>ap_threads_per_child</code></dt>
	<dd>Use <code>ap_mpm_query()</code> query codes
	<code>AP_MPMQ_MAX_DAEMON_USED</code>, <code>AP_MPMQ_GENERATION</code>,
	and <code>AP_MPMQ_MAX_THREADS</code>, respectively.</dd>

	<dt><code>ap_mpm_query()</code></dt>
	<dd>Ensure that it is not used until after the register-hooks
	hook has completed. Otherwise, an MPM built as a DSO
	would not have had a chance to enable support for this
	function.</dd>

	<dt><code>ap_server_conf->process->pool</code>
	userdata</dt>
	<dd>
	Optional:
	<ul>
	<li>If your module uses this to determine which pass of the
	startup hooks is being run,
	use <code>ap_state_query(AP_SQ_MAIN_STATE)</code>.</li>
	<li>If your module uses this to maintain data across the
	unloading and reloading of your module, use
	<code>ap_retained_data_create()</code> and
	<code>ap_retained_data_get()</code>.</li>
	</ul>
	</dd>

	<dt><code>apr_global_mutex_create()</code>,
	<code>apr_proc_mutex_create()</code></dt>
	<dd>Optional: See <code>ap_mutex_register()</code>,
	<code>ap_global_mutex_create()</code>, and
	<code>ap_proc_mutex_create()</code>; these allow your
	mutexes to be configurable with
	the <directive module="core">Mutex</directive> directive;
	you can also remove any configuration mechanisms in your
	module for such mutexes
	</dd>

	<dt><code>CORE_PRIVATE</code></dt>
	<dd>This is now unnecessary and ignored.</dd>

	<dt><code>dav_new_error()</code>
	and <code>dav_new_error_tag()</code></dt>
	<dd>Previously, these assumed that <code>errno</code> contained
	information describing the failure. Now,
	an <code>apr_status_t</code> parameter must be provided. Pass
	0/APR_SUCCESS if there is no such error information, or a valid
	<code>apr_status_t</code> value otherwise.</dd>

	<dt><code>mpm_default.h</code>, <code>DEFAULT_LOCKFILE</code>,
	<code>DEFAULT_THREAD_LIMIT</code>, <code>DEFAULT_PIDLOG</code>,
	etc.</dt>
	<dd>The header file and most of the default configuration
	values set in it are no longer visible to modules. (Most can
	still be overridden at build time.) <code>DEFAULT_PIDLOG</code>
	and <code>DEFAULT_REL_RUNTIMEDIR</code> are now universally
	available via <code>ap_config.h</code>.</dd>

	<dt><code>unixd_config</code></dt>
	<dd>This has been renamed to ap_unixd_config.</dd>
	</dl>
	</section>

	<section id="upgrading_byfeature">
	<title>If your module interfaces with this feature...</title>
	<dl>
	<dt>suEXEC</dt>
	<dd>Optional: If your module logs an error
	when <code>ap_unixd_config.suexec_enabled</code> is 0,
	also log the value of the new
	field <code>suexec_disabled_reason</code>, which contains an
	explanation of why it is not available.</dd>

	<dt>Extended status data in the scoreboard</dt>
	<dd>In previous releases, <code>ExtendedStatus</code> had to be
	set to <code>On</code>, which in turn required that
	mod_status was loaded. In 2.4, just
	set <code>ap_extended_status</code> to <code>1</code> in a
	pre-config hook and the extended status data will be
	available.</dd>

	</dl>
	</section>

	<section id="upgrading_newfeatures">
	<title>Does your module...</title>
	<dl>
	<dt>Parse query args</dt>
	<dd>Consider if <code>ap_args_to_table()</code> would be
	helpful.</dd>

	<dt>Parse form data...</dt>
	<dd>Use <code>ap_parse_form_data()</code>.</dd>

	<dt>Check for request header fields <code>Content-Length</code>
	and <code>Transfer-Encoding</code> to see if a body was
	specified</dt>
	<dd>Use <code>ap_request_has_body()</code>.</dd>

	<dt>Implement cleanups which clear pointer variables</dt>
	<dd>Use <code>ap_pool_cleanup_set_null()</code>.</dd>
	</dl>
	</section>

	</section>

	</manualpage>