mirror of
https://github.com/apache/httpd.git
synced 2025-11-06 16:49:32 +03:00
a7c1dc2853
API docs. The macro needs a trailing semicolon. git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@1023002 13f79535-47bb-0310-9956-ffa450edef68
282 lines
11 KiB
XML
282 lines
11 KiB
XML
<?xml version='1.0' encoding='UTF-8' ?>
|
|
<!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd">
|
|
<?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
|
|
|
|
<!--
|
|
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>
|
|
</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>
|
|
</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>
|
|
</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_disk_cache">
|
|
<title>mod_disk_cache (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_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, mpm_note_child_killed, timed_callback, get_name, and function ap_mpm_note_child_killed</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>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, if a module implements wrapper
|
|
functions for <code>ap_log_*</code> and uses <code>APLOG_MARK</code>
|
|
when calling these wrappers, some adjustments are necessary.
|
|
The easiest way is for the module to define and use a different macro
|
|
that expands to the parameters required by the log wrapper functions.
|
|
<code>APLOG_MARK</code> should only be used when calling
|
|
<code>ap_log_*</code> without additional wrappers. In this way, the
|
|
code will remain compatible with HTTPD 2.0 and 2.2.</p>
|
|
</section>
|
|
|
|
</section>
|
|
|
|
</manualpage>
|