601 lines
29 KiB
XML
601 lines
29 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
|
|
<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head>
|
|
<meta content="text/html; charset=UTF-8" http-equiv="Content-Type" />
|
|
<!--
|
|
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
|
|
This file is generated from xml source: DO NOT EDIT
|
|
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
|
|
-->
|
|
<title>API Changes in Apache HTTP Server 2.4 since 2.2 - Apache HTTP Server Version 2.4</title>
|
|
<link href="../style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" />
|
|
<link href="../style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" />
|
|
<link href="../style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" /><link rel="stylesheet" type="text/css" href="../style/css/prettify.css" />
|
|
<script src="../style/scripts/prettify.min.js" type="text/javascript">
|
|
</script>
|
|
|
|
<link href="../images/favicon.ico" rel="shortcut icon" /></head>
|
|
<body id="manual-page"><div id="page-header">
|
|
<p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="http://wiki.apache.org/httpd/FAQ">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p>
|
|
<p class="apache">Apache HTTP Server Version 2.4</p>
|
|
<img alt="" src="../images/feather.png" /></div>
|
|
<div class="up"><a href="./"><img title="<-" alt="<-" src="../images/left.gif" /></a></div>
|
|
<div id="path">
|
|
<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.4</a></div><div id="page-content"><div id="preamble"><h1>API Changes in Apache HTTP Server 2.4 since 2.2</h1>
|
|
<div class="toplang">
|
|
<p><span>Available Languages: </span><a href="../en/developer/new_api_2_4.html" title="English"> en </a></p>
|
|
</div>
|
|
|
|
<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. As of the first GA release of the
|
|
2.4 branch API compatibility is preserved for the life of the
|
|
2.4 branch. (The
|
|
<a href="http://svn.apache.org/repos/asf/httpd/httpd/branches/2.4.x/VERSIONING">VERSIONING</a>
|
|
description for the 2.4 release provides more information about API
|
|
compatibility.)</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 backwards-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>
|
|
</div>
|
|
<div id="quickview"><a href="https://www.apache.org/foundation/contributing.html" class="badge"><img src="https://www.apache.org/images/SupportApache-small.png" alt="Support Apache!" /></a><ul id="toc"><li><img alt="" src="../images/down.gif" /> <a href="#api_changes">Changed APIs</a></li>
|
|
<li><img alt="" src="../images/down.gif" /> <a href="#upgrading">Specific information on upgrading modules from 2.2</a></li>
|
|
</ul><h3>See also</h3><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
|
|
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
|
|
<div class="section">
|
|
<h2><a name="api_changes" id="api_changes">Changed APIs</a></h2>
|
|
|
|
|
|
<h3><a name="ap_expr" id="ap_expr">ap_expr (NEW!)</a></h3>
|
|
|
|
<p>Introduces a new API to parse and evaluate boolean and algebraic
|
|
expressions, including provision for a standard syntax and
|
|
customised variants.</p>
|
|
|
|
|
|
<h3><a name="ap_listen" id="ap_listen">ap_listen (changed; backwards-compatible)</a></h3>
|
|
|
|
<p>Introduces a new API to enable httpd child processes to serve
|
|
different purposes.</p>
|
|
|
|
|
|
<h3><a name="ap_mpm" id="ap_mpm">ap_mpm (changed)</a></h3>
|
|
|
|
<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>
|
|
|
|
|
|
<h3><a name="ap_regex" id="ap_regex">ap_regex (changed)</a></h3>
|
|
|
|
<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
|
|
backreferences is also added.</p>
|
|
|
|
|
|
<h3><a name="ap_slotmem" id="ap_slotmem">ap_slotmem (NEW!)</a></h3>
|
|
|
|
<p>Introduces an API for modules to allocate and manage memory slots,
|
|
most commonly for shared memory.</p>
|
|
|
|
|
|
<h3><a name="ap_socache" id="ap_socache">ap_socache (NEW!)</a></h3>
|
|
|
|
<p>API to manage a shared object cache.</p>
|
|
|
|
|
|
<h3><a name="heartbeat" id="heartbeat">heartbeat (NEW!)</a></h3>
|
|
|
|
<p>common structures for heartbeat modules</p>
|
|
|
|
|
|
<h3><a name="ap_parse_htaccess" id="ap_parse_htaccess">ap_parse_htaccess (changed)</a></h3>
|
|
|
|
<p>The function signature for <code>ap_parse_htaccess</code> has been
|
|
changed. A <code>apr_table_t</code> of individual directives allowed
|
|
for override must now be passed (override remains).</p>
|
|
|
|
|
|
<h3><a name="http_config" id="http_config">http_config (changed)</a></h3>
|
|
|
|
<ul>
|
|
<li>Introduces per-module, per-directory loglevels, including macro wrappers.</li>
|
|
<li>New <code>AP_DECLARE_MODULE</code> macro to declare all modules.</li>
|
|
<li>New <code>APLOG_USE_MODULE</code> macro necessary for per-module loglevels in
|
|
multi-file modules.</li>
|
|
<li>New API to retain data across module unload/load</li>
|
|
<li>New <code>check_config</code> hook</li>
|
|
<li>New <code>ap_process_fnmatch_configs()</code> function to process wildcards</li>
|
|
<li>Change <code>ap_configfile_t</code>, <code>ap_cfg_getline()</code>,
|
|
<code>ap_cfg_getc()</code> to return error codes, and add
|
|
<code>ap_pcfg_strerror()</code> for retrieving an error description.</li>
|
|
<li>Any config directive permitted in ACCESS_CONF context must now
|
|
correctly handle being called from an .htaccess file via the new
|
|
<code class="directive"><a href="../mod/core.html#allowoverridelist">AllowOverrideList</a></code> directive.
|
|
ap_check_cmd_context() accepts a new flag NOT_IN_HTACCESS to detect
|
|
this case.</li>
|
|
</ul>
|
|
|
|
|
|
<h3><a name="http_core" id="http_core">http_core (changed)</a></h3>
|
|
|
|
<ul>
|
|
<li>REMOVED <code>ap_default_type</code>, <code>ap_requires</code>, all
|
|
2.2 authnz API</li>
|
|
<li>Introduces Optional Functions for logio and authnz</li>
|
|
<li>New function <code>ap_get_server_name_for_url</code> to support IPv6
|
|
literals.</li>
|
|
<li>New function <code>ap_register_errorlog_handler</code> to register error log
|
|
format string handlers.</li>
|
|
<li>Arguments of <code>error_log</code> hook have changed. Declaration has moved to
|
|
<code>http_core.h</code>.</li>
|
|
<li>New function <code>ap_state_query</code> 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 <code>ap_get_conn_socket</code> to get the socket descriptor for a
|
|
connection. This should be used instead of accessing the core
|
|
connection config directly.</li>
|
|
</ul>
|
|
|
|
|
|
<h3><a name="httpd" id="httpd">httpd (changed)</a></h3>
|
|
|
|
<ul>
|
|
<li>Introduce per-directory, per-module loglevel</li>
|
|
<li>New loglevels <code>APLOG_TRACEn</code></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 <code>CONN_STATE</code> values</li>
|
|
<li>Function changes: <code>ap_escape_html</code> updated;
|
|
<code>ap_unescape_all</code>, <code>ap_escape_path_segment_buffer</code></li>
|
|
<li>Modules that load other modules later than the <code>EXEC_ON_READ</code> config
|
|
reading stage need to call <code>ap_reserve_module_slots()</code> or
|
|
<code>ap_reserve_module_slots_directive()</code> in their
|
|
<code>pre_config hook</code>.</li>
|
|
<li>The useragent IP address per request can now be tracked
|
|
independently of the client IP address of the connection, for
|
|
support of deployments with load balancers.</li>
|
|
</ul>
|
|
|
|
|
|
<h3><a name="http_log" id="http_log">http_log (changed)</a></h3>
|
|
|
|
<ul>
|
|
<li>Introduce per-directory, per-module loglevel</li>
|
|
<li>New loglevels <code>APLOG_TRACEn</code></li>
|
|
<li><code>ap_log_*error</code> become macro wrappers (backwards-compatible if
|
|
<code>APLOG_MARK</code> macro is used, except that is no longer possible to
|
|
use <code>#ifdef</code> inside the argument list)</li>
|
|
<li>piped logging revamped</li>
|
|
<li><code>module_index</code> added to error_log hook</li>
|
|
<li>new function: <code>ap_log_command_line</code></li>
|
|
</ul>
|
|
|
|
|
|
<h3><a name="http_request" id="http_request">http_request (changed)</a></h3>
|
|
|
|
<ul>
|
|
<li>New auth_internal API and auth_provider API</li>
|
|
<li>New <code>EOR</code> bucket type</li>
|
|
<li>New function <code>ap_process_async_request</code></li>
|
|
<li>New flags <code>AP_AUTH_INTERNAL_PER_CONF</code> and
|
|
<code>AP_AUTH_INTERNAL_PER_URI</code></li>
|
|
<li>New <code>access_checker_ex</code> hook to apply additional access control
|
|
and/or bypass authentication.</li>
|
|
<li>New functions <code>ap_hook_check_access_ex</code>,
|
|
<code>ap_hook_check_access</code>, <code>ap_hook_check_authn</code>,
|
|
<code>ap_hook_check_authz</code> which accept
|
|
<code>AP_AUTH_INTERNAL_PER_*</code> flags</li>
|
|
<li>DEPRECATED direct use of <code>ap_hook_access_checker</code>,
|
|
<code>access_checker_ex</code>, <code>ap_hook_check_user_id</code>,
|
|
<code>ap_hook_auth_checker</code></li>
|
|
</ul>
|
|
<p>When possible, registering all access control hooks (including
|
|
authentication and authorization hooks) using <code>AP_AUTH_INTERNAL_PER_CONF</code>
|
|
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
|
|
<code>AP_AUTH_INTERNAL_PER_URI</code>.</p>
|
|
|
|
|
|
<h3><a name="mod_auth" id="mod_auth">mod_auth (NEW!)</a></h3>
|
|
|
|
<p>Introduces the new provider framework for authn and authz</p>
|
|
|
|
|
|
<h3><a name="mod_cache" id="mod_cache">mod_cache (changed)</a></h3>
|
|
|
|
<p>Introduces a <code>commit_entity()</code> function to the cache provider
|
|
interface, allowing atomic writes to cache. Add a <code>cache_status()</code>
|
|
hook to report the cache decision. All private structures and functions were
|
|
removed.</p>
|
|
|
|
|
|
<h3><a name="mod_core" id="mod_core">mod_core (NEW!)</a></h3>
|
|
|
|
<p>This introduces low-level APIs to send arbitrary headers,
|
|
and exposes functions to handle HTTP OPTIONS and TRACE.</p>
|
|
|
|
|
|
<h3><a name="mod_cache_disk" id="mod_cache_disk">mod_cache_disk (changed)</a></h3>
|
|
|
|
<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>
|
|
|
|
|
|
<h3><a name="mod_disk_cache" id="mod_disk_cache">mod_disk_cache (renamed)</a></h3>
|
|
|
|
<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>
|
|
|
|
|
|
<h3><a name="mod_request" id="mod_request">mod_request (NEW!)</a></h3>
|
|
|
|
<p>The API for <code class="module"><a href="../mod/mod_request.html">mod_request</a></code>, to make input data
|
|
available to multiple application/handler modules where required,
|
|
and to parse HTML form data.</p>
|
|
|
|
|
|
<h3><a name="mpm_common" id="mpm_common">mpm_common (changed)</a></h3>
|
|
|
|
<ul>
|
|
<li>REMOVES: <code>accept</code>, <code>lockfile</code>, <code>lock_mech</code>,
|
|
<code>set_scoreboard</code> (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: <code>mpm_query</code>, <code>timed_callback</code>, and
|
|
<code>get_name</code></li>
|
|
<li>CHANGED interfaces: <code>monitor</code> hook,
|
|
<code>ap_reclaim_child_processes</code>,
|
|
<code>ap_relieve_child_processes</code></li>
|
|
</ul>
|
|
|
|
|
|
<h3><a name="scoreboard" id="scoreboard">scoreboard (changed)</a></h3>
|
|
|
|
<p><code>ap_get_scoreboard_worker</code> is made non-backwards-compatible
|
|
as an alternative version is introduced. Additional proxy_balancer
|
|
support. Child status stuff revamped.</p>
|
|
|
|
|
|
<h3><a name="util_cookies" id="util_cookies">util_cookies (NEW!)</a></h3>
|
|
|
|
<p>Introduces a new API for managing HTTP Cookies.</p>
|
|
|
|
|
|
<h3><a name="util_ldap" id="util_ldap">util_ldap (changed)</a></h3>
|
|
|
|
<p><em>no description available</em></p>
|
|
|
|
|
|
<h3><a name="util_mutex" id="util_mutex">util_mutex (NEW!)</a></h3>
|
|
|
|
<p>A wrapper for APR proc and global mutexes in httpd, providing
|
|
common configuration for the underlying mechanism and location
|
|
of lock files.</p>
|
|
|
|
|
|
<h3><a name="util_script" id="util_script">util_script (changed)</a></h3>
|
|
|
|
<p>NEW: <code>ap_args_to_table</code></p>
|
|
|
|
|
|
<h3><a name="util_time" id="util_time">util_time (changed)</a></h3>
|
|
|
|
<p>NEW: <code>ap_recent_ctime_ex</code></p>
|
|
|
|
|
|
</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
|
|
<div class="section">
|
|
<h2><a name="upgrading" id="upgrading">Specific information on upgrading modules from 2.2</a></h2>
|
|
|
|
|
|
<h3><a name="upgrading_logging" id="upgrading_logging">Logging</a></h3>
|
|
|
|
<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>
|
|
<div class="example"><p><code>
|
|
#include <http_log.h><br />
|
|
<br />
|
|
#ifdef APLOG_USE_MODULE<br />
|
|
APLOG_USE_MODULE(foo);<br />
|
|
#endif
|
|
</code></p></div>
|
|
<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>
|
|
|
|
<div class="example"><p><code>
|
|
/* 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 />
|
|
</code></p></div>
|
|
|
|
<p><code>ap_log_*error</code> are now implemented as macros. This means
|
|
that it is no longer possible to use <code>#ifdef</code> inside the
|
|
argument list of <code>ap_log_*error</code>, as this would cause
|
|
undefined behavior according to C99.</p>
|
|
|
|
<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>
|
|
|
|
|
|
<h3><a name="upgrading_byfunction" id="upgrading_byfunction">If your module uses these existing APIs...</a></h3>
|
|
|
|
|
|
<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_requires()</code></dt>
|
|
<dd>The core server now provides better infrastructure for handling
|
|
<code class="directive"><a href="../mod/mod_authz_core.html#require">Require</a></code> configuration.
|
|
Register an auth provider function for each supported entity using
|
|
<code>ap_register_auth_provider()</code>. The function will be
|
|
called as necessary during <code class="directive">Require</code>
|
|
processing. (Consult bundled modules for detailed examples.)</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 <code class="directive"><a href="../mod/core.html#mutex">Mutex</a></code> 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>
|
|
|
|
<dt><code>unixd_setup_child()</code></dt>
|
|
<dd>This has been renamed to ap_unixd_setup_child(), but most callers
|
|
should call the added ap_run_drop_privileges() hook.</dd>
|
|
|
|
<dt><code>conn_rec->remote_ip</code> and
|
|
<code>conn_rec->remote_addr</code></dt>
|
|
<dd>These fields have been renamed in order to distinguish between
|
|
the client IP address of the connection and the useragent IP address
|
|
of the request (potentially overridden by a load balancer or proxy).
|
|
References to either of these fields must be updated with one of the
|
|
following options, as appropriate for the module:
|
|
<ul>
|
|
<li>When you require the IP address of the user agent, which
|
|
might be connected directly to the server, or might optionally be
|
|
separated from the server by a transparent load balancer or
|
|
proxy, use <code>request_rec->useragent_ip</code> and
|
|
<code>request_rec->useragent_addr</code>.</li>
|
|
<li>When you require the IP address of the client that is
|
|
connected directly to the server, which might be the useragent or
|
|
might be the load balancer or proxy itself, use
|
|
<code>conn_rec->client_ip</code> and
|
|
<code>conn_rec->client_addr</code>.</li>
|
|
</ul>
|
|
</dd>
|
|
</dl>
|
|
|
|
|
|
<h3><a name="upgrading_byfeature" id="upgrading_byfeature">If your module interfaces with this feature...</a></h3>
|
|
|
|
<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>
|
|
|
|
|
|
<h3><a name="upgrading_newfeatures" id="upgrading_newfeatures">Does your module...</a></h3>
|
|
|
|
<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>
|
|
|
|
<dt>Create run-time files such as shared memory files, pid files,
|
|
etc.</dt>
|
|
<dd>Use <code>ap_runtime_dir_relative()</code> so that the global
|
|
configuration for the location of such files, either by the
|
|
<code>DEFAULT_REL_RUNTIMEDIR</code> compile setting or the
|
|
<code class="directive"><a href="../mod/core.html#defaultruntimedir">DefaultRuntimeDir</a></code> directive,
|
|
will be respected. <em>Apache httpd 2.4.2 and above.</em></dd>
|
|
|
|
</dl>
|
|
|
|
|
|
</div></div>
|
|
<div class="bottomlang">
|
|
<p><span>Available Languages: </span><a href="../en/developer/new_api_2_4.html" title="English"> en </a></p>
|
|
</div><div class="top"><a href="#page-header"><img src="../images/up.gif" alt="top" /></a></div><div class="section"><h2><a id="comments_section" name="comments_section">Comments</a></h2><div class="warning"><strong>Notice:</strong><br />This is not a Q&A section. Comments placed here should be pointed towards suggestions on improving the documentation or server, and may be removed by our moderators if they are either implemented or considered invalid/off-topic. Questions on how to manage the Apache HTTP Server should be directed at either our IRC channel, #httpd, on Libera.chat, or sent to our <a href="https://httpd.apache.org/lists.html">mailing lists</a>.</div>
|
|
<script type="text/javascript"><!--//--><![CDATA[//><!--
|
|
var comments_shortname = 'httpd';
|
|
var comments_identifier = 'http://httpd.apache.org/docs/2.4/developer/new_api_2_4.html';
|
|
(function(w, d) {
|
|
if (w.location.hostname.toLowerCase() == "httpd.apache.org") {
|
|
d.write('<div id="comments_thread"><\/div>');
|
|
var s = d.createElement('script');
|
|
s.type = 'text/javascript';
|
|
s.async = true;
|
|
s.src = 'https://comments.apache.org/show_comments.lua?site=' + comments_shortname + '&page=' + comments_identifier;
|
|
(d.getElementsByTagName('head')[0] || d.getElementsByTagName('body')[0]).appendChild(s);
|
|
}
|
|
else {
|
|
d.write('<div id="comments_thread">Comments are disabled for this page at the moment.<\/div>');
|
|
}
|
|
})(window, document);
|
|
//--><!]]></script></div><div id="footer">
|
|
<p class="apache">Copyright 2024 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>
|
|
<p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="http://wiki.apache.org/httpd/FAQ">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p></div><script type="text/javascript"><!--//--><![CDATA[//><!--
|
|
if (typeof(prettyPrint) !== 'undefined') {
|
|
prettyPrint();
|
|
}
|
|
//--><!]]></script>
|
|
</body></html> |