hooks.html.en revision e41ae559e8408edb1c949c1237034f277d423ecc
749N/A<?xml version="1.0" encoding="ISO-8859-1"?>
749N/A<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
749N/A<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head><!--
749N/A XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
749N/A This file is generated from xml source: DO NOT EDIT
749N/A XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
749N/A -->
749N/A<title>Hook Functions in the Apache HTTP Server 2.x - Apache HTTP Server</title>
749N/A<link href="/style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" />
749N/A<link href="/style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" />
749N/A<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" />
749N/A<script src="/style/scripts/prettify.js" type="text/javascript">
749N/A</script>
749N/A
749N/A<link href="/images/favicon.ico" rel="shortcut icon" /></head>
749N/A<body id="manual-page"><div id="page-header">
749N/A<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>
749N/A<p class="apache">Apache HTTP Server Version 2.5</p>
749N/A<img alt="" src="/images/feather.gif" /></div>
749N/A<div class="up"><a href="./"><img title="&lt;-" alt="&lt;-" src="/images/left.gif" /></a></div>
749N/A<div id="path">
749N/A<a href="http://www.apache.org/">Apache</a> &gt; <a href="http://httpd.apache.org/">HTTP Server</a> &gt; <a href="http://httpd.apache.org/docs/">Documentation</a> &gt; <a href="../">Version 2.5</a> &gt; <a href="./">Developer Documentation</a></div><div id="page-content"><div id="preamble"><h1>Hook Functions in the Apache HTTP Server 2.x</h1>
749N/A<div class="toplang">
749N/A<p><span>Available Languages: </span><a href="/en/developer/hooks.html" title="English">&nbsp;en&nbsp;</a></p>
749N/A</div>
749N/A
749N/A <div class="warning"><h3>Warning</h3>
749N/A <p>This document is still in development and may be partially out of
749N/A date.</p>
749N/A </div>
749N/A
749N/A <p>In general, a hook function is one that the Apache HTTP Server
749N/A will call at some point during the processing of a request.
749N/A Modules can provide functions that are called, and specify when
749N/A they get called in comparison to other modules.</p>
749N/A</div>
749N/A<div id="quickview"><ul id="toc"><li><img alt="" src="/images/down.gif" /> <a href="#create">Creating a hook function</a></li>
749N/A<li><img alt="" src="/images/down.gif" /> <a href="#hooking">Hooking the hook</a></li>
749N/A</ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
749N/A<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
749N/A<div class="section">
749N/A<h2><a name="create" id="create">Creating a hook function</a></h2>
749N/A <p>In order to create a new hook, four things need to be
749N/A done:</p>
749N/A
749N/A <h3><a name="create-declare" id="create-declare">Declare the hook function</a></h3>
749N/A <p>Use the <code>AP_DECLARE_HOOK</code> macro, which needs to be given
749N/A the return type of the hook function, the name of the hook, and the
749N/A arguments. For example, if the hook returns an <code>int</code> and
749N/A takes a <code>request_rec *</code> and an <code>int</code> and is
749N/A called <code>do_something</code>, then declare it like this:</p>
749N/A <pre class="prettyprint lang-c">
749N/A AP_DECLARE_HOOK(int, do_something, (request_rec *r, int n))
749N/A </pre>
749N/A
749N/A
749N/A <p>This should go in a header which modules will include if
749N/A they want to use the hook.</p>
749N/A
749N/A
749N/A <h3><a name="create-create" id="create-create">Create the hook structure</a></h3>
749N/A <p>Each source file that exports a hook has a private structure
749N/A which is used to record the module functions that use the hook.
749N/A This is declared as follows:</p>
749N/A
749N/A <pre class="prettyprint lang-c">
749N/AAPR_HOOK_STRUCT(
749N/A APR_HOOK_LINK(do_something)
749N/A ...
749N/A)
749N/A </pre>
749N/A
749N/A
749N/A
749N/A <h3><a name="create-implement" id="create-implement">Implement the hook caller</a></h3>
749N/A <p>The source file that exports the hook has to implement a
749N/A function that will call the hook. There are currently three
749N/A possible ways to do this. In all cases, the calling function is
749N/A called <code>ap_run_<var>hookname</var>()</code>.</p>
749N/A
749N/A <h4>Void hooks</h4>
749N/A <p>If the return value of a hook is <code>void</code>, then all the
749N/A hooks are called, and the caller is implemented like this:</p>
749N/A
749N/A <pre class="prettyprint lang-c">
749N/A AP_IMPLEMENT_HOOK_VOID(do_something, (request_rec *r, int n), (r, n))
749N/A </pre>
749N/A
749N/A
749N/A <p>The second and third arguments are the dummy argument
749N/A declaration and the dummy arguments as they will be used when
749N/A calling the hook. In other words, this macro expands to
749N/A something like this:</p>
749N/A
749N/A <pre class="prettyprint lang-c">
749N/Avoid ap_run_do_something(request_rec *r, int n)
749N/A{
749N/A...
749N/Ado_something(r, n);
749N/A}
749N/A </pre>
749N/A
749N/A
749N/A
749N/A <h4>Hooks that return a value</h4>
749N/A <p>If the hook returns a value, then it can either be run until
749N/A the first hook that does something interesting, like so:</p>
749N/A
749N/A <pre class="prettyprint lang-c">
749N/A AP_IMPLEMENT_HOOK_RUN_FIRST(int, do_something, (request_rec *r, int n), (r, n), DECLINED)
749N/A </pre>
749N/A
749N/A
749N/A <p>The first hook that does <em>not</em> return <code>DECLINED</code>
749N/A stops the loop and its return value is returned from the hook
749N/A caller. Note that <code>DECLINED</code> is the traditional
749N/A hook return value meaning "I didn't do anything", but it can be
749N/A whatever suits you.</p>
749N/A
749N/A <p>Alternatively, all hooks can be run until an error occurs.
749N/A This boils down to permitting <em>two</em> return values, one of
749N/A which means "I did something, and it was OK" and the other
749N/A meaning "I did nothing". The first function that returns a
749N/A value other than one of those two stops the loop, and its
749N/A return is the return value. Declare these like so:</p>
749N/A
749N/A <pre class="prettyprint lang-c">
749N/A AP_IMPLEMENT_HOOK_RUN_ALL(int, do_something, (request_rec *r, int n), (r, n), OK, DECLINED)
749N/A </pre>
749N/A
749N/A
749N/A <p>Again, <code>OK</code> and <code>DECLINED</code> are the traditional
749N/A values. You can use what you want.</p>
749N/A
749N/A
749N/A
749N/A <h3><a name="create-call" id="create-call">Call the hook callers</a></h3>
749N/A <p>At appropriate moments in the code, call the hook caller,
749N/A like so:</p>
749N/A
749N/A <pre class="prettyprint lang-c">
749N/Aint n, ret;
749N/Arequest_rec *r;
749N/A
749N/Aret=ap_run_do_something(r, n);
749N/A </pre>
749N/A
749N/A
749N/A</div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
749N/A<div class="section">
749N/A<h2><a name="hooking" id="hooking">Hooking the hook</a></h2>
749N/A <p>A module that wants a hook to be called needs to do two
749N/A things.</p>
749N/A
749N/A <h3><a name="hooking-implement" id="hooking-implement">Implement the hook function</a></h3>
749N/A <p>Include the appropriate header, and define a static function
749N/A of the correct type:</p>
749N/A
749N/A <pre class="prettyprint lang-c">
749N/Astatic int my_something_doer(request_rec *r, int n)<br />
749N/A{
749N/A ...
749N/A return OK;
749N/A}
749N/A </pre>
749N/A
749N/A
749N/A
749N/A <h3><a name="hooking-add" id="hooking-add">Add a hook registering function</a></h3>
749N/A <p>During initialisation, the server will call each modules hook
749N/A registering function, which is included in the module
749N/A structure:</p>
749N/A
749N/A <pre class="prettyprint lang-c">
749N/Astatic void my_register_hooks()
749N/A{
749N/A ap_hook_do_something(my_something_doer, NULL, NULL, APR_HOOK_MIDDLE);
749N/A}
749N/A
749N/Amode MODULE_VAR_EXPORT my_module =
749N/A{
749N/A ...
749N/A my_register_hooks /* register hooks */
749N/A};
749N/A </pre>
749N/A
749N/A
749N/A
749N/A <h3><a name="hooking-order" id="hooking-order">Controlling hook calling order</a></h3>
749N/A <p>In the example above, we didn't use the three arguments in
749N/A the hook registration function that control calling order.
749N/A There are two mechanisms for doing this. The first, rather
749N/A crude, method, allows us to specify roughly where the hook is
749N/A run relative to other modules. The final argument control this.
749N/A There are three possible values: <code>APR_HOOK_FIRST</code>,
749N/A <code>APR_HOOK_MIDDLE</code> and <code>APR_HOOK_LAST</code>.</p>
749N/A
749N/A <p>All modules using any particular value may be run in any
749N/A order relative to each other, but, of course, all modules using
749N/A <code>APR_HOOK_FIRST</code> will be run before <code>APR_HOOK_MIDDLE</code>
749N/A which are before <code>APR_HOOK_LAST</code>. Modules that don't care
749N/A when they are run should use <code>APR_HOOK_MIDDLE</code>. <em>These
749N/A values are spaced out, so that positions like <code>APR_HOOK_FIRST-2</code>
749N/A are possible to hook slightly earlier than other functions.</em></p>
749N/A
749N/A <p>Note that there are two more values,
749N/A <code>APR_HOOK_REALLY_FIRST</code> and <code>APR_HOOK_REALLY_LAST</code>. These
749N/A should only be used by the hook exporter.</p>
749N/A
749N/A <p>The other method allows finer control. When a module knows
749N/A that it must be run before (or after) some other modules, it
749N/A can specify them by name. The second (third) argument is a
749N/A NULL-terminated array of strings consisting of the names of
749N/A modules that must be run before (after) the current module. For
749N/A example, suppose we want "mod_xyz.c" and "mod_abc.c" to run
749N/A before we do, then we'd hook as follows:</p>
749N/A
749N/A <pre class="prettyprint lang-c">
749N/Astatic void register_hooks()
749N/A{
749N/A static const char * const aszPre[] = { "mod_xyz.c", "mod_abc.c", NULL };
749N/A
749N/A ap_hook_do_something(my_something_doer, aszPre, NULL, APR_HOOK_MIDDLE);
749N/A}
749N/A </pre>
749N/A
749N/A
749N/A <p>Note that the sort used to achieve this is stable, so
749N/A ordering set by <code>APR_HOOK_<var>ORDER</var></code> is preserved, as far
749N/A as is possible.</p>
749N/A
749N/A
749N/A</div></div>
749N/A<div class="bottomlang">
749N/A<p><span>Available Languages: </span><a href="/en/developer/hooks.html" title="English">&nbsp;en&nbsp;</a></p>
749N/A</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&amp;A section. Comments placed here should be pointed towards suggestions on improving the documentation or server, and may be removed again 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 Freenode, or sent to our <a href="http://httpd.apache.org/lists.html">mailing lists</a>.</div>
749N/A<script type="text/javascript"><!--//--><![CDATA[//><!--
749N/Avar comments_shortname = 'httpd';
749N/Avar comments_identifier = 'http://httpd.apache.org/docs/trunk/developer/hooks.html';
749N/A(function(w, d) {
749N/A if (w.location.hostname.toLowerCase() == "httpd.apache.org") {
749N/A d.write('<div id="comments_thread"><\/div>');
749N/A var s = d.createElement('script');
749N/A s.type = 'text/javascript';
749N/A s.async = true;
749N/A s.src = 'https://comments.apache.org/show_comments.lua?site=' + comments_shortname + '&page=' + comments_identifier;
749N/A (d.getElementsByTagName('head')[0] || d.getElementsByTagName('body')[0]).appendChild(s);
749N/A }
749N/A else {
749N/A d.write('<div id="comments_thread">Comments are disabled for this page at the moment.<\/div>');
749N/A }
749N/A})(window, document);
749N/A//--><!]]></script></div><div id="footer">
749N/A<p class="apache">Copyright 2012 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>
749N/A<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[//><!--
749N/Aif (typeof(prettyPrint) !== 'undefined') {
749N/A prettyPrint();
749N/A}
749N/A//--><!]]></script>
749N/A</body></html>