1 /* Licensed to the Apache Software Foundation (ASF) under one or more
2 * contributor license agreements. See the NOTICE file distributed with
3 * this work for additional information regarding copyright ownership.
4 * The ASF licenses this file to You under the Apache License, Version 2.0
5 * (the "License"); you may not use this file except in compliance with
6 * the License. You may obtain a copy of the License at
8 * http://www.apache.org/licenses/LICENSE-2.0
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
21 /* For apr_array_header_t */
22 #include "apr_tables.h"
26 * @brief Apache hook functions
33 * @defgroup APR_Util_Hook Hook Functions
39 * @defgroup apr_hook_probes Hook probe capability
40 * APR hooks provide a trace probe capability for capturing
41 * the flow of control and return values with hooks.
43 * In order to use this facility, the application must define
44 * the symbol APR_HOOK_PROBES_ENABLED and the four APR_HOOK_PROBE_
45 * macros described below before including apr_hooks.h in files
46 * that use the APR_IMPLEMENT_EXTERNAL_HOOK_* macros.
48 * This probe facility is not provided for APR optional hooks.
52 #ifdef APR_HOOK_PROBES_ENABLED
53 #define APR_HOOK_INT_DCL_UD void *ud = NULL
55 /** internal implementation detail to avoid the ud declaration when
56 * hook probes are not used
58 #define APR_HOOK_INT_DCL_UD
60 * User-defined hook probe macro that is invoked when the hook
61 * is run, before calling any hook functions.
62 * @param ud A void * user data field that should be filled in by
63 * this macro, and will be provided to the other hook probe macros.
64 * @param ns The namespace prefix of the hook functions
65 * @param name The name of the hook
66 * @param args The argument list to the hook functions, with enclosing
69 #define APR_HOOK_PROBE_ENTRY(ud,ns,name,args)
71 * User-defined hook probe macro that is invoked after the hook
73 * @param ud A void * user data field that was filled in by the user-
74 * provided APR_HOOK_PROBE_ENTRY().
75 * @param ns The namespace prefix of the hook functions
76 * @param name The name of the hook
77 * @param rv The return value of the hook, or 0 if the hook is void.
78 * @param args The argument list to the hook functions, with enclosing
81 #define APR_HOOK_PROBE_RETURN(ud,ns,name,rv,args)
83 * User-defined hook probe macro that is invoked before calling a
85 * @param ud A void * user data field that was filled in by the user-
86 * provided APR_HOOK_PROBE_ENTRY().
87 * @param ns The namespace prefix of the hook functions
88 * @param name The name of the hook
89 * @param src The value of apr_hook_debug_current at the time the function
90 * was hooked (usually the source file implementing the hook function).
91 * @param args The argument list to the hook functions, with enclosing
94 #define APR_HOOK_PROBE_INVOKE(ud,ns,name,src,args)
96 * User-defined hook probe macro that is invoked after calling a
98 * @param ud A void * user data field that was filled in by the user-
99 * provided APR_HOOK_PROBE_ENTRY().
100 * @param ns The namespace prefix of the hook functions
101 * @param name The name of the hook
102 * @param src The value of apr_hook_debug_current at the time the function
103 * was hooked (usually the source file implementing the hook function).
104 * @param rv The return value of the hook function, or 0 if the hook is void.
105 * @param args The argument list to the hook functions, with enclosing
108 #define APR_HOOK_PROBE_COMPLETE(ud,ns,name,src,rv,args)
113 /** macro to return the prototype of the hook function */
114 #define APR_IMPLEMENT_HOOK_GET_PROTO(ns,link,name) \
115 link##_DECLARE(apr_array_header_t *) ns##_hook_get_##name(void)
117 /** macro to declare the hook correctly */
118 #define APR_DECLARE_EXTERNAL_HOOK(ns,link,ret,name,args) \
119 typedef ret ns##_HOOK_##name##_t args; \
120 link##_DECLARE(void) ns##_hook_##name(ns##_HOOK_##name##_t *pf, \
121 const char * const *aszPre, \
122 const char * const *aszSucc, int nOrder); \
123 link##_DECLARE(ret) ns##_run_##name args; \
124 APR_IMPLEMENT_HOOK_GET_PROTO(ns,link,name); \
125 typedef struct ns##_LINK_##name##_t \
127 ns##_HOOK_##name##_t *pFunc; \
128 const char *szName; \
129 const char * const *aszPredecessors; \
130 const char * const *aszSuccessors; \
132 } ns##_LINK_##name##_t;
134 /** macro to declare the hook structure */
135 #define APR_HOOK_STRUCT(members) \
136 static struct { members } _hooks;
138 /** macro to link the hook structure */
139 #define APR_HOOK_LINK(name) \
140 apr_array_header_t *link_##name;
142 /** macro to implement the hook */
143 #define APR_IMPLEMENT_EXTERNAL_HOOK_BASE(ns,link,name) \
144 link##_DECLARE(void) ns##_hook_##name(ns##_HOOK_##name##_t *pf,const char * const *aszPre, \
145 const char * const *aszSucc,int nOrder) \
147 ns##_LINK_##name##_t *pHook; \
148 if(!_hooks.link_##name) \
150 _hooks.link_##name=apr_array_make(apr_hook_global_pool,1,sizeof(ns##_LINK_##name##_t)); \
151 apr_hook_sort_register(#name,&_hooks.link_##name); \
153 pHook=apr_array_push(_hooks.link_##name); \
155 pHook->aszPredecessors=aszPre; \
156 pHook->aszSuccessors=aszSucc; \
157 pHook->nOrder=nOrder; \
158 pHook->szName=apr_hook_debug_current; \
159 if(apr_hook_debug_enabled) \
160 apr_hook_debug_show(#name,aszPre,aszSucc); \
162 APR_IMPLEMENT_HOOK_GET_PROTO(ns,link,name) \
164 return _hooks.link_##name; \
168 * Implement a hook that has no return code, and therefore runs all of the
169 * registered functions
170 * @param ns The namespace prefix of the hook functions
171 * @param link The linkage declaration prefix of the hook
172 * @param name The name of the hook
173 * @param args_decl The declaration of the arguments for the hook
174 * @param args_use The names for the arguments for the hook
175 * @note The link prefix FOO corresponds to FOO_DECLARE() macros, which
176 * provide export linkage from the module that IMPLEMENTs the hook, and
177 * import linkage from external modules that link to the hook's module.
179 #define APR_IMPLEMENT_EXTERNAL_HOOK_VOID(ns,link,name,args_decl,args_use) \
180 APR_IMPLEMENT_EXTERNAL_HOOK_BASE(ns,link,name) \
181 link##_DECLARE(void) ns##_run_##name args_decl \
183 ns##_LINK_##name##_t *pHook; \
185 APR_HOOK_INT_DCL_UD; \
187 APR_HOOK_PROBE_ENTRY(ud, ns, name, args_use); \
189 if(_hooks.link_##name) \
191 pHook=(ns##_LINK_##name##_t *)_hooks.link_##name->elts; \
192 for(n=0 ; n < _hooks.link_##name->nelts ; ++n) \
194 APR_HOOK_PROBE_INVOKE(ud, ns, name, (char *)pHook[n].szName, args_use); \
195 pHook[n].pFunc args_use; \
196 APR_HOOK_PROBE_COMPLETE(ud, ns, name, (char *)pHook[n].szName, 0, args_use); \
200 APR_HOOK_PROBE_RETURN(ud, ns, name, 0, args_use); \
204 /* FIXME: note that this returns ok when nothing is run. I suspect it should
205 really return decline, but that breaks Apache currently - Ben
208 * Implement a hook that runs until one of the functions returns something
209 * other than OK or DECLINE
210 * @param ns The namespace prefix of the hook functions
211 * @param link The linkage declaration prefix of the hook
212 * @param ret Type to return
213 * @param name The name of the hook
214 * @param args_decl The declaration of the arguments for the hook
215 * @param args_use The names for the arguments for the hook
216 * @param ok Success value
217 * @param decline Decline value
218 * @note The link prefix FOO corresponds to FOO_DECLARE() macros, which
219 * provide export linkage from the module that IMPLEMENTs the hook, and
220 * import linkage from external modules that link to the hook's module.
222 #define APR_IMPLEMENT_EXTERNAL_HOOK_RUN_ALL(ns,link,ret,name,args_decl,args_use,ok,decline) \
223 APR_IMPLEMENT_EXTERNAL_HOOK_BASE(ns,link,name) \
224 link##_DECLARE(ret) ns##_run_##name args_decl \
226 ns##_LINK_##name##_t *pHook; \
229 APR_HOOK_INT_DCL_UD; \
231 APR_HOOK_PROBE_ENTRY(ud, ns, name, args_use); \
233 if(_hooks.link_##name) \
235 pHook=(ns##_LINK_##name##_t *)_hooks.link_##name->elts; \
236 for(n=0 ; n < _hooks.link_##name->nelts ; ++n) \
238 APR_HOOK_PROBE_INVOKE(ud, ns, name, (char *)pHook[n].szName, args_use); \
239 rv=pHook[n].pFunc args_use; \
240 APR_HOOK_PROBE_COMPLETE(ud, ns, name, (char *)pHook[n].szName, rv, args_use); \
241 if(rv != ok && rv != decline) \
247 APR_HOOK_PROBE_RETURN(ud, ns, name, rv, args_use); \
254 * Implement a hook that runs until the first function returns something
255 * other than the value of decline
256 * @param ns The namespace prefix of the hook functions
257 * @param link The linkage declaration prefix of the hook
258 * @param name The name of the hook
259 * @param ret Type to return
260 * @param args_decl The declaration of the arguments for the hook
261 * @param args_use The names for the arguments for the hook
262 * @param decline Decline value
263 * @note The link prefix FOO corresponds to FOO_DECLARE() macros, which
264 * provide export linkage from the module that IMPLEMENTs the hook, and
265 * import linkage from external modules that link to the hook's module.
267 #define APR_IMPLEMENT_EXTERNAL_HOOK_RUN_FIRST(ns,link,ret,name,args_decl,args_use,decline) \
268 APR_IMPLEMENT_EXTERNAL_HOOK_BASE(ns,link,name) \
269 link##_DECLARE(ret) ns##_run_##name args_decl \
271 ns##_LINK_##name##_t *pHook; \
274 APR_HOOK_INT_DCL_UD; \
276 APR_HOOK_PROBE_ENTRY(ud, ns, name, args_use); \
278 if(_hooks.link_##name) \
280 pHook=(ns##_LINK_##name##_t *)_hooks.link_##name->elts; \
281 for(n=0 ; n < _hooks.link_##name->nelts ; ++n) \
283 APR_HOOK_PROBE_INVOKE(ud, ns, name, (char *)pHook[n].szName, args_use); \
284 rv=pHook[n].pFunc args_use; \
285 APR_HOOK_PROBE_COMPLETE(ud, ns, name, (char *)pHook[n].szName, rv, args_use); \
292 APR_HOOK_PROBE_RETURN(ud, ns, name, rv, args_use); \
298 /** run this hook first, before ANYTHING */
299 #define APR_HOOK_REALLY_FIRST (-10)
300 /** run this hook first */
301 #define APR_HOOK_FIRST 0
302 /** run this hook somewhere */
303 #define APR_HOOK_MIDDLE 10
304 /** run this hook after every other hook which is defined*/
305 #define APR_HOOK_LAST 20
306 /** run this hook last, after EVERYTHING */
307 #define APR_HOOK_REALLY_LAST 30
310 * The global pool used to allocate any memory needed by the hooks.
312 APU_DECLARE_DATA extern apr_pool_t *apr_hook_global_pool;
315 * A global variable to determine if debugging information about the
316 * hooks functions should be printed.
318 APU_DECLARE_DATA extern int apr_hook_debug_enabled;
321 * The name of the module that is currently registering a function.
323 APU_DECLARE_DATA extern const char *apr_hook_debug_current;
326 * Register a hook function to be sorted.
327 * @param szHookName The name of the Hook the function is registered for
328 * @param aHooks The array which stores all of the functions for this hook
330 APU_DECLARE(void) apr_hook_sort_register(const char *szHookName,
331 apr_array_header_t **aHooks);
333 * Sort all of the registered functions for a given hook.
335 APU_DECLARE(void) apr_hook_sort_all(void);
338 * Print all of the information about the current hook. This is used for
339 * debugging purposes.
340 * @param szName The name of the hook
341 * @param aszPre All of the functions in the predecessor array
342 * @param aszSucc All of the functions in the successor array
344 APU_DECLARE(void) apr_hook_debug_show(const char *szName,
345 const char * const *aszPre,
346 const char * const *aszSucc);
349 * Remove all currently registered functions.
351 APU_DECLARE(void) apr_hook_deregister_all(void);
358 #endif /* APR_HOOKS_H */