1251876Speter/* Licensed to the Apache Software Foundation (ASF) under one or more 2251876Speter * contributor license agreements. See the NOTICE file distributed with 3251876Speter * this work for additional information regarding copyright ownership. 4251876Speter * The ASF licenses this file to You under the Apache License, Version 2.0 5251876Speter * (the "License"); you may not use this file except in compliance with 6251876Speter * the License. You may obtain a copy of the License at 7251876Speter * 8251876Speter * http://www.apache.org/licenses/LICENSE-2.0 9251876Speter * 10251876Speter * Unless required by applicable law or agreed to in writing, software 11251876Speter * distributed under the License is distributed on an "AS IS" BASIS, 12251876Speter * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13251876Speter * See the License for the specific language governing permissions and 14251876Speter * limitations under the License. 15251876Speter */ 16251876Speter 17251876Speter#ifndef APR_HOOKS_H 18251876Speter#define APR_HOOKS_H 19251876Speter 20251876Speter#include "apu.h" 21251876Speter/* For apr_array_header_t */ 22251876Speter#include "apr_tables.h" 23251876Speter 24251876Speter/** 25251876Speter * @file apr_hooks.h 26251876Speter * @brief Apache hook functions 27251876Speter */ 28251876Speter 29251876Speter#ifdef __cplusplus 30251876Speterextern "C" { 31251876Speter#endif 32251876Speter/** 33251876Speter * @defgroup APR_Util_Hook Hook Functions 34251876Speter * @ingroup APR_Util 35251876Speter * @{ 36251876Speter */ 37251876Speter 38251876Speter/** 39251876Speter * @defgroup apr_hook_probes Hook probe capability 40251876Speter * APR hooks provide a trace probe capability for capturing 41251876Speter * the flow of control and return values with hooks. 42251876Speter * 43251876Speter * In order to use this facility, the application must define 44251876Speter * the symbol APR_HOOK_PROBES_ENABLED and the four APR_HOOK_PROBE_ 45251876Speter * macros described below before including apr_hooks.h in files 46251876Speter * that use the APR_IMPLEMENT_EXTERNAL_HOOK_* macros. 47251876Speter * 48251876Speter * This probe facility is not provided for APR optional hooks. 49251876Speter * @{ 50251876Speter */ 51251876Speter 52251876Speter#ifdef APR_HOOK_PROBES_ENABLED 53251876Speter#define APR_HOOK_INT_DCL_UD void *ud = NULL 54251876Speter#else 55251876Speter/** internal implementation detail to avoid the ud declaration when 56251876Speter * hook probes are not used 57251876Speter */ 58251876Speter#define APR_HOOK_INT_DCL_UD 59251876Speter/** 60251876Speter * User-defined hook probe macro that is invoked when the hook 61251876Speter * is run, before calling any hook functions. 62251876Speter * @param ud A void * user data field that should be filled in by 63251876Speter * this macro, and will be provided to the other hook probe macros. 64251876Speter * @param ns The namespace prefix of the hook functions 65251876Speter * @param name The name of the hook 66251876Speter * @param args The argument list to the hook functions, with enclosing 67251876Speter * parens. 68251876Speter */ 69251876Speter#define APR_HOOK_PROBE_ENTRY(ud,ns,name,args) 70251876Speter/** 71251876Speter * User-defined hook probe macro that is invoked after the hook 72251876Speter * has run. 73251876Speter * @param ud A void * user data field that was filled in by the user- 74251876Speter * provided APR_HOOK_PROBE_ENTRY(). 75251876Speter * @param ns The namespace prefix of the hook functions 76251876Speter * @param name The name of the hook 77251876Speter * @param rv The return value of the hook, or 0 if the hook is void. 78251876Speter * @param args The argument list to the hook functions, with enclosing 79251876Speter * parens. 80251876Speter */ 81251876Speter#define APR_HOOK_PROBE_RETURN(ud,ns,name,rv,args) 82251876Speter/** 83251876Speter * User-defined hook probe macro that is invoked before calling a 84251876Speter * hook function. 85251876Speter * @param ud A void * user data field that was filled in by the user- 86251876Speter * provided APR_HOOK_PROBE_ENTRY(). 87251876Speter * @param ns The namespace prefix of the hook functions 88251876Speter * @param name The name of the hook 89251876Speter * @param src The value of apr_hook_debug_current at the time the function 90251876Speter * was hooked (usually the source file implementing the hook function). 91251876Speter * @param args The argument list to the hook functions, with enclosing 92251876Speter * parens. 93251876Speter */ 94251876Speter#define APR_HOOK_PROBE_INVOKE(ud,ns,name,src,args) 95251876Speter/** 96251876Speter * User-defined hook probe macro that is invoked after calling a 97251876Speter * hook function. 98251876Speter * @param ud A void * user data field that was filled in by the user- 99251876Speter * provided APR_HOOK_PROBE_ENTRY(). 100251876Speter * @param ns The namespace prefix of the hook functions 101251876Speter * @param name The name of the hook 102251876Speter * @param src The value of apr_hook_debug_current at the time the function 103251876Speter * was hooked (usually the source file implementing the hook function). 104251876Speter * @param rv The return value of the hook function, or 0 if the hook is void. 105251876Speter * @param args The argument list to the hook functions, with enclosing 106251876Speter * parens. 107251876Speter */ 108251876Speter#define APR_HOOK_PROBE_COMPLETE(ud,ns,name,src,rv,args) 109251876Speter#endif 110251876Speter 111251876Speter/** @} */ 112251876Speter 113251876Speter/** macro to return the prototype of the hook function */ 114251876Speter#define APR_IMPLEMENT_HOOK_GET_PROTO(ns,link,name) \ 115251876Speterlink##_DECLARE(apr_array_header_t *) ns##_hook_get_##name(void) 116251876Speter 117251876Speter/** macro to declare the hook correctly */ 118251876Speter#define APR_DECLARE_EXTERNAL_HOOK(ns,link,ret,name,args) \ 119251876Spetertypedef ret ns##_HOOK_##name##_t args; \ 120251876Speterlink##_DECLARE(void) ns##_hook_##name(ns##_HOOK_##name##_t *pf, \ 121251876Speter const char * const *aszPre, \ 122251876Speter const char * const *aszSucc, int nOrder); \ 123251876Speterlink##_DECLARE(ret) ns##_run_##name args; \ 124251876SpeterAPR_IMPLEMENT_HOOK_GET_PROTO(ns,link,name); \ 125251876Spetertypedef struct ns##_LINK_##name##_t \ 126251876Speter { \ 127251876Speter ns##_HOOK_##name##_t *pFunc; \ 128251876Speter const char *szName; \ 129251876Speter const char * const *aszPredecessors; \ 130251876Speter const char * const *aszSuccessors; \ 131251876Speter int nOrder; \ 132251876Speter } ns##_LINK_##name##_t; 133251876Speter 134251876Speter/** macro to declare the hook structure */ 135251876Speter#define APR_HOOK_STRUCT(members) \ 136251876Speterstatic struct { members } _hooks; 137251876Speter 138251876Speter/** macro to link the hook structure */ 139251876Speter#define APR_HOOK_LINK(name) \ 140251876Speter apr_array_header_t *link_##name; 141251876Speter 142251876Speter/** macro to implement the hook */ 143251876Speter#define APR_IMPLEMENT_EXTERNAL_HOOK_BASE(ns,link,name) \ 144251876Speterlink##_DECLARE(void) ns##_hook_##name(ns##_HOOK_##name##_t *pf,const char * const *aszPre, \ 145251876Speter const char * const *aszSucc,int nOrder) \ 146251876Speter { \ 147251876Speter ns##_LINK_##name##_t *pHook; \ 148251876Speter if(!_hooks.link_##name) \ 149251876Speter { \ 150251876Speter _hooks.link_##name=apr_array_make(apr_hook_global_pool,1,sizeof(ns##_LINK_##name##_t)); \ 151251876Speter apr_hook_sort_register(#name,&_hooks.link_##name); \ 152251876Speter } \ 153251876Speter pHook=apr_array_push(_hooks.link_##name); \ 154251876Speter pHook->pFunc=pf; \ 155251876Speter pHook->aszPredecessors=aszPre; \ 156251876Speter pHook->aszSuccessors=aszSucc; \ 157251876Speter pHook->nOrder=nOrder; \ 158251876Speter pHook->szName=apr_hook_debug_current; \ 159251876Speter if(apr_hook_debug_enabled) \ 160251876Speter apr_hook_debug_show(#name,aszPre,aszSucc); \ 161251876Speter } \ 162251876Speter APR_IMPLEMENT_HOOK_GET_PROTO(ns,link,name) \ 163251876Speter { \ 164251876Speter return _hooks.link_##name; \ 165251876Speter } 166251876Speter 167251876Speter/** 168251876Speter * Implement a hook that has no return code, and therefore runs all of the 169251876Speter * registered functions 170251876Speter * @param ns The namespace prefix of the hook functions 171251876Speter * @param link The linkage declaration prefix of the hook 172251876Speter * @param name The name of the hook 173251876Speter * @param args_decl The declaration of the arguments for the hook 174251876Speter * @param args_use The names for the arguments for the hook 175251876Speter * @note The link prefix FOO corresponds to FOO_DECLARE() macros, which 176251876Speter * provide export linkage from the module that IMPLEMENTs the hook, and 177251876Speter * import linkage from external modules that link to the hook's module. 178251876Speter */ 179251876Speter#define APR_IMPLEMENT_EXTERNAL_HOOK_VOID(ns,link,name,args_decl,args_use) \ 180251876SpeterAPR_IMPLEMENT_EXTERNAL_HOOK_BASE(ns,link,name) \ 181251876Speterlink##_DECLARE(void) ns##_run_##name args_decl \ 182251876Speter { \ 183251876Speter ns##_LINK_##name##_t *pHook; \ 184251876Speter int n; \ 185251876Speter APR_HOOK_INT_DCL_UD; \ 186251876Speter\ 187251876Speter APR_HOOK_PROBE_ENTRY(ud, ns, name, args_use); \ 188251876Speter\ 189251876Speter if(_hooks.link_##name) \ 190251876Speter { \ 191251876Speter pHook=(ns##_LINK_##name##_t *)_hooks.link_##name->elts; \ 192251876Speter for(n=0 ; n < _hooks.link_##name->nelts ; ++n) \ 193251876Speter { \ 194251876Speter APR_HOOK_PROBE_INVOKE(ud, ns, name, (char *)pHook[n].szName, args_use); \ 195251876Speter pHook[n].pFunc args_use; \ 196251876Speter APR_HOOK_PROBE_COMPLETE(ud, ns, name, (char *)pHook[n].szName, 0, args_use); \ 197251876Speter } \ 198251876Speter } \ 199251876Speter\ 200251876Speter APR_HOOK_PROBE_RETURN(ud, ns, name, 0, args_use); \ 201251876Speter\ 202251876Speter } 203251876Speter 204251876Speter/* FIXME: note that this returns ok when nothing is run. I suspect it should 205251876Speter really return decline, but that breaks Apache currently - Ben 206251876Speter*/ 207251876Speter/** 208251876Speter * Implement a hook that runs until one of the functions returns something 209251876Speter * other than OK or DECLINE 210251876Speter * @param ns The namespace prefix of the hook functions 211251876Speter * @param link The linkage declaration prefix of the hook 212251876Speter * @param ret Type to return 213251876Speter * @param name The name of the hook 214251876Speter * @param args_decl The declaration of the arguments for the hook 215251876Speter * @param args_use The names for the arguments for the hook 216251876Speter * @param ok Success value 217251876Speter * @param decline Decline value 218251876Speter * @note The link prefix FOO corresponds to FOO_DECLARE() macros, which 219251876Speter * provide export linkage from the module that IMPLEMENTs the hook, and 220251876Speter * import linkage from external modules that link to the hook's module. 221251876Speter */ 222251876Speter#define APR_IMPLEMENT_EXTERNAL_HOOK_RUN_ALL(ns,link,ret,name,args_decl,args_use,ok,decline) \ 223251876SpeterAPR_IMPLEMENT_EXTERNAL_HOOK_BASE(ns,link,name) \ 224251876Speterlink##_DECLARE(ret) ns##_run_##name args_decl \ 225251876Speter { \ 226251876Speter ns##_LINK_##name##_t *pHook; \ 227251876Speter int n; \ 228251876Speter ret rv = ok; \ 229251876Speter APR_HOOK_INT_DCL_UD; \ 230251876Speter\ 231251876Speter APR_HOOK_PROBE_ENTRY(ud, ns, name, args_use); \ 232251876Speter\ 233251876Speter if(_hooks.link_##name) \ 234251876Speter { \ 235251876Speter pHook=(ns##_LINK_##name##_t *)_hooks.link_##name->elts; \ 236251876Speter for(n=0 ; n < _hooks.link_##name->nelts ; ++n) \ 237251876Speter { \ 238251876Speter APR_HOOK_PROBE_INVOKE(ud, ns, name, (char *)pHook[n].szName, args_use); \ 239251876Speter rv=pHook[n].pFunc args_use; \ 240251876Speter APR_HOOK_PROBE_COMPLETE(ud, ns, name, (char *)pHook[n].szName, rv, args_use); \ 241251876Speter if(rv != ok && rv != decline) \ 242251876Speter break; \ 243251876Speter rv = ok; \ 244251876Speter } \ 245251876Speter } \ 246251876Speter\ 247251876Speter APR_HOOK_PROBE_RETURN(ud, ns, name, rv, args_use); \ 248251876Speter\ 249251876Speter return rv; \ 250251876Speter } 251251876Speter 252251876Speter 253251876Speter/** 254251876Speter * Implement a hook that runs until the first function returns something 255251876Speter * other than the value of decline 256251876Speter * @param ns The namespace prefix of the hook functions 257251876Speter * @param link The linkage declaration prefix of the hook 258251876Speter * @param name The name of the hook 259251876Speter * @param ret Type to return 260251876Speter * @param args_decl The declaration of the arguments for the hook 261251876Speter * @param args_use The names for the arguments for the hook 262251876Speter * @param decline Decline value 263251876Speter * @note The link prefix FOO corresponds to FOO_DECLARE() macros, which 264251876Speter * provide export linkage from the module that IMPLEMENTs the hook, and 265251876Speter * import linkage from external modules that link to the hook's module. 266251876Speter */ 267251876Speter#define APR_IMPLEMENT_EXTERNAL_HOOK_RUN_FIRST(ns,link,ret,name,args_decl,args_use,decline) \ 268251876SpeterAPR_IMPLEMENT_EXTERNAL_HOOK_BASE(ns,link,name) \ 269251876Speterlink##_DECLARE(ret) ns##_run_##name args_decl \ 270251876Speter { \ 271251876Speter ns##_LINK_##name##_t *pHook; \ 272251876Speter int n; \ 273251876Speter ret rv = decline; \ 274251876Speter APR_HOOK_INT_DCL_UD; \ 275251876Speter\ 276251876Speter APR_HOOK_PROBE_ENTRY(ud, ns, name, args_use); \ 277251876Speter\ 278251876Speter if(_hooks.link_##name) \ 279251876Speter { \ 280251876Speter pHook=(ns##_LINK_##name##_t *)_hooks.link_##name->elts; \ 281251876Speter for(n=0 ; n < _hooks.link_##name->nelts ; ++n) \ 282251876Speter { \ 283251876Speter APR_HOOK_PROBE_INVOKE(ud, ns, name, (char *)pHook[n].szName, args_use); \ 284251876Speter rv=pHook[n].pFunc args_use; \ 285251876Speter APR_HOOK_PROBE_COMPLETE(ud, ns, name, (char *)pHook[n].szName, rv, args_use); \ 286251876Speter\ 287251876Speter if(rv != decline) \ 288251876Speter break; \ 289251876Speter } \ 290251876Speter } \ 291251876Speter\ 292251876Speter APR_HOOK_PROBE_RETURN(ud, ns, name, rv, args_use); \ 293251876Speter\ 294251876Speter return rv; \ 295251876Speter } 296251876Speter 297251876Speter /* Hook orderings */ 298251876Speter/** run this hook first, before ANYTHING */ 299251876Speter#define APR_HOOK_REALLY_FIRST (-10) 300251876Speter/** run this hook first */ 301251876Speter#define APR_HOOK_FIRST 0 302251876Speter/** run this hook somewhere */ 303251876Speter#define APR_HOOK_MIDDLE 10 304251876Speter/** run this hook after every other hook which is defined*/ 305251876Speter#define APR_HOOK_LAST 20 306251876Speter/** run this hook last, after EVERYTHING */ 307251876Speter#define APR_HOOK_REALLY_LAST 30 308251876Speter 309251876Speter/** 310251876Speter * The global pool used to allocate any memory needed by the hooks. 311251876Speter */ 312251876SpeterAPU_DECLARE_DATA extern apr_pool_t *apr_hook_global_pool; 313251876Speter 314251876Speter/** 315251876Speter * A global variable to determine if debugging information about the 316258602Speter * hooks functions should be printed. 317251876Speter */ 318251876SpeterAPU_DECLARE_DATA extern int apr_hook_debug_enabled; 319251876Speter 320251876Speter/** 321258602Speter * The name of the module that is currently registering a function. 322251876Speter */ 323251876SpeterAPU_DECLARE_DATA extern const char *apr_hook_debug_current; 324251876Speter 325251876Speter/** 326258602Speter * Register a hook function to be sorted. 327251876Speter * @param szHookName The name of the Hook the function is registered for 328251876Speter * @param aHooks The array which stores all of the functions for this hook 329251876Speter */ 330251876SpeterAPU_DECLARE(void) apr_hook_sort_register(const char *szHookName, 331251876Speter apr_array_header_t **aHooks); 332251876Speter/** 333258602Speter * Sort all of the registered functions for a given hook. 334251876Speter */ 335251876SpeterAPU_DECLARE(void) apr_hook_sort_all(void); 336251876Speter 337251876Speter/** 338251876Speter * Print all of the information about the current hook. This is used for 339251876Speter * debugging purposes. 340251876Speter * @param szName The name of the hook 341251876Speter * @param aszPre All of the functions in the predecessor array 342251876Speter * @param aszSucc All of the functions in the successor array 343251876Speter */ 344251876SpeterAPU_DECLARE(void) apr_hook_debug_show(const char *szName, 345251876Speter const char * const *aszPre, 346251876Speter const char * const *aszSucc); 347251876Speter 348251876Speter/** 349251876Speter * Remove all currently registered functions. 350251876Speter */ 351251876SpeterAPU_DECLARE(void) apr_hook_deregister_all(void); 352251876Speter 353251876Speter/** @} */ 354251876Speter#ifdef __cplusplus 355251876Speter} 356251876Speter#endif 357251876Speter 358251876Speter#endif /* APR_HOOKS_H */ 359