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