749N/A<?
xml version="1.0" encoding="ISO-8859-1"?>
749N/A XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX 749N/A This file is generated from xml source: DO NOT EDIT 749N/A XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX 749N/A<
title>Hook Functions in the Apache HTTP Server
2.x - Apache HTTP Server</
title>
749N/A<
body id="manual-page"><
div id="page-header">
749N/A<
p class="apache">Apache HTTP Server Version 2.5</
p>
749N/A<
div class="up"><
a href="./"><
img title="<-" alt="<-" src="/images/left.gif" /></
a></
div>
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 <
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 id="quickview"><
ul id="toc"><
li><
img alt="" src="/images/down.gif" /> <
a href="#create">Creating a hook function</
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<
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 <
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 <
p>This should go in a header which modules will include if
749N/A they want to use the hook.</
p>
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 <
pre class="prettyprint lang-c">
749N/A APR_HOOK_LINK(do_something)
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 <
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 <
pre class="prettyprint lang-c">
749N/A AP_IMPLEMENT_HOOK_VOID(do_something, (request_rec *r, int n), (r, n))
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 <
pre class="prettyprint lang-c">
749N/Avoid ap_run_do_something(request_rec *r, int n)
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 <
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 <
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 <
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 <
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 <
p>Again, <
code>OK</
code> and <
code>DECLINED</
code> are the traditional
749N/A values. You can use what you want.</
p>
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 <
pre class="prettyprint lang-c">
749N/Aret=ap_run_do_something(r, n);
749N/A</
div><
div class="top"><
a href="#page-header"><
img alt="top" src="/images/up.gif" /></
a></
div>
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 <
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 <
pre class="prettyprint lang-c">
749N/Astatic int my_something_doer(request_rec *r, int n)<
br />
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 <
pre class="prettyprint lang-c">
749N/Astatic void my_register_hooks()
749N/A ap_hook_do_something(my_something_doer, NULL, NULL, APR_HOOK_MIDDLE);
749N/Amode MODULE_VAR_EXPORT my_module =
749N/A my_register_hooks /* register hooks */
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 <
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 <
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 <
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 before we do, then we'd hook as follows:</
p>
749N/A <
pre class="prettyprint lang-c">
749N/Astatic void register_hooks()
749N/A ap_hook_do_something(my_something_doer, aszPre, NULL, APR_HOOK_MIDDLE);
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<
div class="bottomlang">
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&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/Avar comments_shortname = 'httpd'; 749N/A d.write('<div id="comments_thread">Comments are disabled for this page at the moment.<\/div>'); 749N/A//--><!]]></
script></
div><
div id="footer">
749N/Aif (typeof(prettyPrint) !== 'undefined') {