home *** CD-ROM | disk | FTP | other *** search
/ Chip 2004 November / CMCD1104.ISO / Software / Complet / Apache / apache_2.0.52-win32-x86-no_ssl.msi / Data.Cab / F277209_apr_hooks.h < prev    next >
C/C++ Source or Header  |  2004-02-13  |  9KB  |  273 lines
  1. /* Copyright 2000-2004 The Apache Software Foundation
  2.  *
  3.  * Licensed under the Apache License, Version 2.0 (the "License");
  4.  * you may not use this file except in compliance with the License.
  5.  * You may obtain a copy of the License at
  6.  *
  7.  *     http://www.apache.org/licenses/LICENSE-2.0
  8.  *
  9.  * Unless required by applicable law or agreed to in writing, software
  10.  * distributed under the License is distributed on an "AS IS" BASIS,
  11.  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  12.  * See the License for the specific language governing permissions and
  13.  * limitations under the License.
  14.  */
  15.  
  16. #ifndef APR_HOOKS_H
  17. #define APR_HOOKS_H
  18.  
  19. #include "apu.h"
  20. /* For apr_array_header_t */
  21. #include "apr_tables.h"
  22.  
  23. /**
  24.  * @file apr_hooks.h
  25.  * @brief Apache hook functions
  26.  */
  27.  
  28. #ifdef __cplusplus
  29. extern "C" {
  30. #endif
  31. /**
  32.  * @defgroup APR_Util_Hook Hook Functions
  33.  * @ingroup APR_Util
  34.  * @{
  35.  */
  36. /** macro to return the prototype of the hook function */    
  37. #define APR_IMPLEMENT_HOOK_GET_PROTO(ns,link,name) \
  38. link##_DECLARE(apr_array_header_t *) ns##_hook_get_##name(void)
  39.  
  40. /** macro to declare the hook correctly */    
  41. #define APR_DECLARE_EXTERNAL_HOOK(ns,link,ret,name,args) \
  42. typedef ret ns##_HOOK_##name##_t args; \
  43. link##_DECLARE(void) ns##_hook_##name(ns##_HOOK_##name##_t *pf, \
  44.                                       const char * const *aszPre, \
  45.                                       const char * const *aszSucc, int nOrder); \
  46. link##_DECLARE(ret) ns##_run_##name args; \
  47. APR_IMPLEMENT_HOOK_GET_PROTO(ns,link,name); \
  48. typedef struct ns##_LINK_##name##_t \
  49.     { \
  50.     ns##_HOOK_##name##_t *pFunc; \
  51.     const char *szName; \
  52.     const char * const *aszPredecessors; \
  53.     const char * const *aszSuccessors; \
  54.     int nOrder; \
  55.     } ns##_LINK_##name##_t;
  56.  
  57. /** macro to declare the hook structure */    
  58. #define APR_HOOK_STRUCT(members) \
  59. static struct { members } _hooks;
  60.  
  61. /** macro to link the hook structure */
  62. #define APR_HOOK_LINK(name) \
  63.     apr_array_header_t *link_##name;
  64.  
  65. /** macro to implement the hook */
  66. #define APR_IMPLEMENT_EXTERNAL_HOOK_BASE(ns,link,name) \
  67. link##_DECLARE(void) ns##_hook_##name(ns##_HOOK_##name##_t *pf,const char * const *aszPre, \
  68.                                       const char * const *aszSucc,int nOrder) \
  69.     { \
  70.     ns##_LINK_##name##_t *pHook; \
  71.     if(!_hooks.link_##name) \
  72.     { \
  73.     _hooks.link_##name=apr_array_make(apr_hook_global_pool,1,sizeof(ns##_LINK_##name##_t)); \
  74.     apr_hook_sort_register(#name,&_hooks.link_##name); \
  75.     } \
  76.     pHook=apr_array_push(_hooks.link_##name); \
  77.     pHook->pFunc=pf; \
  78.     pHook->aszPredecessors=aszPre; \
  79.     pHook->aszSuccessors=aszSucc; \
  80.     pHook->nOrder=nOrder; \
  81.     pHook->szName=apr_hook_debug_current; \
  82.     if(apr_hook_debug_enabled) \
  83.     apr_hook_debug_show(#name,aszPre,aszSucc); \
  84.     } \
  85.     APR_IMPLEMENT_HOOK_GET_PROTO(ns,link,name) \
  86.     { \
  87.         return _hooks.link_##name; \
  88.     }
  89.  
  90. /**
  91.  * Implement a hook that has no return code, and therefore runs all of the
  92.  * registered functions
  93.  * @param ns The namespace prefix of the hook functions
  94.  * @param link The linkage declaration prefix of the hook
  95.  * @param name The name of the hook
  96.  * @param args_decl The declaration of the arguments for the hook
  97.  * @param args_use The names for the arguments for the hook
  98.  * @note The link prefix FOO corresponds to FOO_DECLARE() macros, which
  99.  * provide export linkage from the module that IMPLEMENTs the hook, and
  100.  * import linkage from external modules that link to the hook's module.
  101.  */
  102. #define APR_IMPLEMENT_EXTERNAL_HOOK_VOID(ns,link,name,args_decl,args_use) \
  103. APR_IMPLEMENT_EXTERNAL_HOOK_BASE(ns,link,name) \
  104. link##_DECLARE(void) ns##_run_##name args_decl \
  105.     { \
  106.     ns##_LINK_##name##_t *pHook; \
  107.     int n; \
  108. \
  109.     if(!_hooks.link_##name) \
  110.     return; \
  111. \
  112.     pHook=(ns##_LINK_##name##_t *)_hooks.link_##name->elts; \
  113.     for(n=0 ; n < _hooks.link_##name->nelts ; ++n) \
  114.     pHook[n].pFunc args_use; \
  115.     }
  116.  
  117. /* FIXME: note that this returns ok when nothing is run. I suspect it should
  118.    really return decline, but that breaks Apache currently - Ben
  119. */
  120. /**
  121.  * Implement a hook that runs until one of the functions returns something
  122.  * other than OK or DECLINE
  123.  * @param ns The namespace prefix of the hook functions
  124.  * @param link The linkage declaration prefix of the hook
  125.  * @param ret Type to return
  126.  * @param name The name of the hook
  127.  * @param args_decl The declaration of the arguments for the hook
  128.  * @param args_use The names for the arguments for the hook
  129.  * @param ok Success value
  130.  * @param decline Decline value
  131.  * @note The link prefix FOO corresponds to FOO_DECLARE() macros, which
  132.  * provide export linkage from the module that IMPLEMENTs the hook, and
  133.  * import linkage from external modules that link to the hook's module.
  134.  */
  135. #define APR_IMPLEMENT_EXTERNAL_HOOK_RUN_ALL(ns,link,ret,name,args_decl,args_use,ok,decline) \
  136. APR_IMPLEMENT_EXTERNAL_HOOK_BASE(ns,link,name) \
  137. link##_DECLARE(ret) ns##_run_##name args_decl \
  138.     { \
  139.     ns##_LINK_##name##_t *pHook; \
  140.     int n; \
  141.     ret rv; \
  142. \
  143.     if(!_hooks.link_##name) \
  144.     return ok; \
  145. \
  146.     pHook=(ns##_LINK_##name##_t *)_hooks.link_##name->elts; \
  147.     for(n=0 ; n < _hooks.link_##name->nelts ; ++n) \
  148.     { \
  149.     rv=pHook[n].pFunc args_use; \
  150. \
  151.     if(rv != ok && rv != decline) \
  152.         return rv; \
  153.     } \
  154.     return ok; \
  155.     }
  156.  
  157.  
  158. /**
  159.  * Implement a hook that runs until the first function returns something
  160.  * other than the value of decline
  161.  * @param ns The namespace prefix of the hook functions
  162.  * @param link The linkage declaration prefix of the hook
  163.  * @param name The name of the hook
  164.  * @param ret Type to return
  165.  * @param args_decl The declaration of the arguments for the hook
  166.  * @param args_use The names for the arguments for the hook
  167.  * @param decline Decline value
  168.  * @note The link prefix FOO corresponds to FOO_DECLARE() macros, which
  169.  * provide export linkage from the module that IMPLEMENTs the hook, and
  170.  * import linkage from external modules that link to the hook's module.
  171.  */
  172. #define APR_IMPLEMENT_EXTERNAL_HOOK_RUN_FIRST(ns,link,ret,name,args_decl,args_use,decline) \
  173. APR_IMPLEMENT_EXTERNAL_HOOK_BASE(ns,link,name) \
  174. link##_DECLARE(ret) ns##_run_##name args_decl \
  175.     { \
  176.     ns##_LINK_##name##_t *pHook; \
  177.     int n; \
  178.     ret rv; \
  179. \
  180.     if(!_hooks.link_##name) \
  181.     return decline; \
  182. \
  183.     pHook=(ns##_LINK_##name##_t *)_hooks.link_##name->elts; \
  184.     for(n=0 ; n < _hooks.link_##name->nelts ; ++n) \
  185.     { \
  186.     rv=pHook[n].pFunc args_use; \
  187. \
  188.     if(rv != decline) \
  189.         return rv; \
  190.     } \
  191.     return decline; \
  192.     }
  193.  
  194.     /* Hook orderings */
  195. /** run this hook first, before ANYTHING */
  196. #define APR_HOOK_REALLY_FIRST    (-10)
  197. /** run this hook first */
  198. #define APR_HOOK_FIRST        0
  199. /** run this hook somewhere */
  200. #define APR_HOOK_MIDDLE        10
  201. /** run this hook after every other hook which is defined*/
  202. #define APR_HOOK_LAST        20
  203. /** run this hook last, after EVERYTHING */
  204. #define APR_HOOK_REALLY_LAST    30
  205.  
  206. /**
  207.  * The global pool used to allocate any memory needed by the hooks.
  208.  */ 
  209. APU_DECLARE_DATA extern apr_pool_t *apr_hook_global_pool;
  210.  
  211. /** @deprecated @see apr_hook_global_pool */
  212. APU_DECLARE_DATA extern apr_pool_t *apr_global_hook_pool;
  213.  
  214. /**
  215.  * A global variable to determine if debugging information about the
  216.  * hooks functions should be printed
  217.  */ 
  218. APU_DECLARE_DATA extern int apr_hook_debug_enabled;
  219.  
  220. /** @deprecated @see apr_hook_debug_enabled */
  221. APU_DECLARE_DATA extern int apr_debug_module_hooks;
  222.  
  223. /**
  224.  * The name of the module that is currently registering a function
  225.  */ 
  226. APU_DECLARE_DATA extern const char *apr_hook_debug_current;
  227.  
  228. /** @deprecated @see apr_hook_debug_current */
  229. APU_DECLARE_DATA extern const char *apr_current_hooking_module;
  230.  
  231. /**
  232.  * Register a hook function to be sorted
  233.  * @param szHookName The name of the Hook the function is registered for
  234.  * @param aHooks The array which stores all of the functions for this hook
  235.  */
  236. APU_DECLARE(void) apr_hook_sort_register(const char *szHookName, 
  237.                                         apr_array_header_t **aHooks);
  238. /**
  239.  * Sort all of the registerd functions for a given hook
  240.  */
  241. APU_DECLARE(void) apr_hook_sort_all(void);
  242.  
  243. /** @deprecated @see apr_hook_sort_all */
  244. APU_DECLARE(void) apr_sort_hooks(void);
  245.  
  246. /**
  247.  * Print all of the information about the current hook.  This is used for
  248.  * debugging purposes.
  249.  * @param szName The name of the hook
  250.  * @param aszPre All of the functions in the predecessor array
  251.  * @param aszSucc All of the functions in the successor array
  252.  */
  253. APU_DECLARE(void) apr_hook_debug_show(const char *szName,
  254.                                       const char * const *aszPre,
  255.                                       const char * const *aszSucc);
  256.  
  257. /** @deprecated @see apr_hook_debug_show */
  258. APU_DECLARE(void) apr_show_hook(const char *szName,
  259.                                 const char * const *aszPre,
  260.                                 const char * const *aszSucc);
  261.  
  262. /**
  263.  * Remove all currently registered functions.
  264.  */
  265. APU_DECLARE(void) apr_hook_deregister_all(void);
  266.  
  267. /** @} */
  268. #ifdef __cplusplus
  269. }
  270. #endif
  271.  
  272. #endif /* APR_HOOKS_H */
  273.