1<?xml version="1.0" encoding="ISO-8859-1"?> 2<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> 3<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head><!-- 4 XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX 5 This file is generated from xml source: DO NOT EDIT 6 XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX 7 --> 8<title>Apache 2.0 Hook Functions - Apache HTTP Server</title> 9<link href="/style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" /> 10<link href="/style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" /> 11<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" /> 12<script src="/style/scripts/prettify.js" type="text/javascript"> 13</script> 14 15<link href="/images/favicon.ico" rel="shortcut icon" /></head> 16<body id="manual-page"><div id="page-header"> 17<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> 18<p class="apache">Apache HTTP Server Version 2.2</p> 19<img alt="" src="/images/feather.gif" /></div> 20<div class="up"><a href="./"><img title="<-" alt="<-" src="/images/left.gif" /></a></div> 21<div id="path"> 22<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.2</a> > <a href="./">Developer Documentation</a></div><div id="page-content"><div id="preamble"><h1>Apache 2.0 Hook Functions</h1> 23<div class="toplang"> 24<p><span>Available Languages: </span><a href="/en/developer/hooks.html" title="English"> en </a></p> 25</div> 26 27 <div class="warning"><h3>Warning</h3> 28 <p>This document is still in development and may be partially out of 29 date.</p> 30 </div> 31 32 <p>In general, a hook function is one that Apache will call at 33 some point during the processing of a request. Modules can 34 provide functions that are called, and specify when they get 35 called in comparison to other modules.</p> 36</div> 37<div id="quickview"><ul id="toc"><li><img alt="" src="/images/down.gif" /> <a href="#create">Creating a hook function</a></li> 38<li><img alt="" src="/images/down.gif" /> <a href="#hooking">Hooking the hook</a></li> 39</ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div> 40<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 41<div class="section"> 42<h2><a name="create" id="create">Creating a hook function</a></h2> 43 <p>In order to create a new hook, four things need to be 44 done:</p> 45 46 <h3><a name="create-declare" id="create-declare">Declare the hook function</a></h3> 47 <p>Use the <code>AP_DECLARE_HOOK</code> macro, which needs to be given 48 the return type of the hook function, the name of the hook, and the 49 arguments. For example, if the hook returns an <code>int</code> and 50 takes a <code>request_rec *</code> and an <code>int</code> and is 51 called <code>do_something</code>, then declare it like this:</p> 52 <div class="example"><p><code> 53 AP_DECLARE_HOOK(int, do_something, (request_rec *r, int n)) 54 </code></p></div> 55 56 <p>This should go in a header which modules will include if 57 they want to use the hook.</p> 58 59 60 <h3><a name="create-create" id="create-create">Create the hook structure</a></h3> 61 <p>Each source file that exports a hook has a private structure 62 which is used to record the module functions that use the hook. 63 This is declared as follows:</p> 64 65 <div class="example"><p><code> 66 APR_HOOK_STRUCT(<br /> 67 <span class="indent"> 68 APR_HOOK_LINK(do_something)<br /> 69 ...<br /> 70 </span> 71 ) 72 </code></p></div> 73 74 75 <h3><a name="create-implement" id="create-implement">Implement the hook caller</a></h3> 76 <p>The source file that exports the hook has to implement a 77 function that will call the hook. There are currently three 78 possible ways to do this. In all cases, the calling function is 79 called <code>ap_run_<var>hookname</var>()</code>.</p> 80 81 <h4>Void hooks</h4> 82 <p>If the return value of a hook is <code>void</code>, then all the 83 hooks are called, and the caller is implemented like this:</p> 84 85 <div class="example"><p><code> 86 AP_IMPLEMENT_HOOK_VOID(do_something, (request_rec *r, int n), (r, n)) 87 </code></p></div> 88 89 <p>The second and third arguments are the dummy argument 90 declaration and the dummy arguments as they will be used when 91 calling the hook. In other words, this macro expands to 92 something like this:</p> 93 94 <div class="example"><p><code> 95 void ap_run_do_something(request_rec *r, int n)<br /> 96 {<br /> 97 <span class="indent"> 98 ...<br /> 99 do_something(r, n);<br /> 100 </span> 101 } 102 </code></p></div> 103 104 105 <h4>Hooks that return a value</h4> 106 <p>If the hook returns a value, then it can either be run until 107 the first hook that does something interesting, like so:</p> 108 109 <div class="example"><p><code> 110 AP_IMPLEMENT_HOOK_RUN_FIRST(int, do_something, (request_rec *r, int n), (r, n), DECLINED) 111 </code></p></div> 112 113 <p>The first hook that does <em>not</em> return <code>DECLINED</code> 114 stops the loop and its return value is returned from the hook 115 caller. Note that <code>DECLINED</code> is the traditional 116 hook return value meaning "I didn't do anything", but it can be 117 whatever suits you.</p> 118 119 <p>Alternatively, all hooks can be run until an error occurs. 120 This boils down to permitting <em>two</em> return values, one of 121 which means "I did something, and it was OK" and the other 122 meaning "I did nothing". The first function that returns a 123 value other than one of those two stops the loop, and its 124 return is the return value. Declare these like so:</p> 125 126 <div class="example"><p><code> 127 AP_IMPLEMENT_HOOK_RUN_ALL(int, do_something, (request_rec *r, int n), (r, n), OK, DECLINED) 128 </code></p></div> 129 130 <p>Again, <code>OK</code> and <code>DECLINED</code> are the traditional 131 values. You can use what you want.</p> 132 133 134 135 <h3><a name="create-call" id="create-call">Call the hook callers</a></h3> 136 <p>At appropriate moments in the code, call the hook caller, 137 like so:</p> 138 139 <div class="example"><p><code> 140 int n, ret;<br /> 141 request_rec *r;<br /> 142 <br /> 143 ret=ap_run_do_something(r, n); 144 </code></p></div> 145 146</div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 147<div class="section"> 148<h2><a name="hooking" id="hooking">Hooking the hook</a></h2> 149 <p>A module that wants a hook to be called needs to do two 150 things.</p> 151 152 <h3><a name="hooking-implement" id="hooking-implement">Implement the hook function</a></h3> 153 <p>Include the appropriate header, and define a static function 154 of the correct type:</p> 155 156 <div class="example"><p><code> 157 static int my_something_doer(request_rec *r, int n)<br /> 158 {<br /> 159 <span class="indent"> 160 ...<br /> 161 return OK;<br /> 162 </span> 163 } 164 </code></p></div> 165 166 167 <h3><a name="hooking-add" id="hooking-add">Add a hook registering function</a></h3> 168 <p>During initialisation, the server will call each modules hook 169 registering function, which is included in the module 170 structure:</p> 171 172 <div class="example"><p><code> 173 static void my_register_hooks()<br /> 174 {<br /> 175 <span class="indent"> 176 ap_hook_do_something(my_something_doer, NULL, NULL, APR_HOOK_MIDDLE);<br /> 177 </span> 178 }<br /> 179 <br /> 180 mode MODULE_VAR_EXPORT my_module =<br /> 181 {<br /> 182 <span class="indent"> 183 ...<br /> 184 my_register_hooks /* register hooks */<br /> 185 </span> 186 }; 187 </code></p></div> 188 189 190 <h3><a name="hooking-order" id="hooking-order">Controlling hook calling order</a></h3> 191 <p>In the example above, we didn't use the three arguments in 192 the hook registration function that control calling order. 193 There are two mechanisms for doing this. The first, rather 194 crude, method, allows us to specify roughly where the hook is 195 run relative to other modules. The final argument control this. 196 There are three possible values: <code>APR_HOOK_FIRST</code>, 197 <code>APR_HOOK_MIDDLE</code> and <code>APR_HOOK_LAST</code>.</p> 198 199 <p>All modules using any particular value may be run in any 200 order relative to each other, but, of course, all modules using 201 <code>APR_HOOK_FIRST</code> will be run before <code>APR_HOOK_MIDDLE</code> 202 which are before <code>APR_HOOK_LAST</code>. Modules that don't care 203 when they are run should use <code>APR_HOOK_MIDDLE</code>. <em>These 204 values are spaced out, so that positions like <code>APR_HOOK_FIRST-2</code> 205 are possible to hook slightly earlier than other functions.</em></p> 206 207 <p>Note that there are two more values, 208 <code>APR_HOOK_REALLY_FIRST</code> and <code>APR_HOOK_REALLY_LAST</code>. These 209 should only be used by the hook exporter.</p> 210 211 <p>The other method allows finer control. When a module knows 212 that it must be run before (or after) some other modules, it 213 can specify them by name. The second (third) argument is a 214 NULL-terminated array of strings consisting of the names of 215 modules that must be run before (after) the current module. For 216 example, suppose we want "mod_xyz.c" and "mod_abc.c" to run 217 before we do, then we'd hook as follows:</p> 218 219 <div class="example"><p><code> 220 static void register_hooks()<br /> 221 {<br /> 222 <span class="indent"> 223 static const char * const aszPre[] = { "mod_xyz.c", "mod_abc.c", NULL };<br /> 224 <br /> 225 ap_hook_do_something(my_something_doer, aszPre, NULL, APR_HOOK_MIDDLE);<br /> 226 </span> 227 } 228 </code></p></div> 229 230 <p>Note that the sort used to achieve this is stable, so 231 ordering set by <code>APR_HOOK_<var>ORDER</var></code> is preserved, as far 232 as is possible.</p> 233 234 <p class="cite"><cite>Ben Laurie</cite>, 15th August 1999</p> 235 236</div></div> 237<div class="bottomlang"> 238<p><span>Available Languages: </span><a href="/en/developer/hooks.html" title="English"> en </a></p> 239</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> 240<script type="text/javascript"><!--//--><![CDATA[//><!-- 241var comments_shortname = 'httpd'; 242var comments_identifier = 'http://httpd.apache.org/docs/2.2/developer/hooks.html'; 243(function(w, d) { 244 if (w.location.hostname.toLowerCase() == "httpd.apache.org") { 245 d.write('<div id="comments_thread"><\/div>'); 246 var s = d.createElement('script'); 247 s.type = 'text/javascript'; 248 s.async = true; 249 s.src = 'https://comments.apache.org/show_comments.lua?site=' + comments_shortname + '&page=' + comments_identifier; 250 (d.getElementsByTagName('head')[0] || d.getElementsByTagName('body')[0]).appendChild(s); 251 } 252 else { 253 d.write('<div id="comments_thread">Comments are disabled for this page at the moment.<\/div>'); 254 } 255})(window, document); 256//--><!]]></script></div><div id="footer"> 257<p class="apache">Copyright 2013 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> 258<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[//><!-- 259if (typeof(prettyPrint) !== 'undefined') { 260 prettyPrint(); 261} 262//--><!]]></script> 263</body></html>
