granicus.if.org Git - apache/blob - include/ap_hooks.h

   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
   7  *
   8  *     http://www.apache.org/licenses/LICENSE-2.0
   9  *
  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.
  15  */
  16
  17 /**
  18  * @file ap_hooks.h
  19  * @brief ap hook functions and macros
  20  */
  21
  22 #ifndef AP_HOOKS_H
  23 #define AP_HOOKS_H
  24
  25 /* Although this file doesn't declare any hooks, declare the hook group here */
  26 /**
  27  * @defgroup hooks Apache Hooks
  28  * @ingroup  APACHE_CORE
  29  */
  30
  31 #if defined(AP_HOOK_PROBES_ENABLED) && !defined(APR_HOOK_PROBES_ENABLED)
  32 #define APR_HOOK_PROBES_ENABLED 1
  33 #endif
  34
  35 #ifdef APR_HOOK_PROBES_ENABLED
  36 #include "ap_hook_probes.h"
  37 #endif
  38
  39 #include "apr.h"
  40 #include "apr_hooks.h"
  41 #include "apr_optional_hooks.h"
  42
  43 #ifdef DOXYGEN
  44 /* define these just so doxygen documents them */
  45
  46 /**
  47  * AP_DECLARE_STATIC is defined when including Apache's Core headers,
  48  * to provide static linkage when the dynamic library may be unavailable.
  49  *
  50  * @see AP_DECLARE_EXPORT
  51  *
  52  * AP_DECLARE_STATIC and AP_DECLARE_EXPORT are left undefined when
  53  * including Apache's Core headers, to import and link the symbols from the
  54  * dynamic Apache Core library and assure appropriate indirection and calling
  55  * conventions at compile time.
  56  */
  57 # define AP_DECLARE_STATIC
  58 /**
  59  * AP_DECLARE_EXPORT is defined when building the Apache Core dynamic
  60  * library, so that all public symbols are exported.
  61  *
  62  * @see AP_DECLARE_STATIC
  63  */
  64 # define AP_DECLARE_EXPORT
  65
  66 #endif /* def DOXYGEN */
  67
  68 /**
  69  * Declare a hook function
  70  * @param ret The return type of the hook
  71  * @param name The hook's name (as a literal)
  72  * @param args The arguments the hook function takes, in brackets.
  73  */
  74 #define AP_DECLARE_HOOK(ret,name,args) \
  75         APR_DECLARE_EXTERNAL_HOOK(ap,AP,ret,name,args)
  76
  77 /** @internal */
  78 #define AP_IMPLEMENT_HOOK_BASE(name) \
  79         APR_IMPLEMENT_EXTERNAL_HOOK_BASE(ap,AP,name)
  80
  81 /**
  82  * Implement an Apache core hook that has no return code, and
  83  * therefore runs all of the registered functions. The implementation
  84  * is called ap_run_<i>name</i>.
  85  *
  86  * @param name The name of the hook
  87  * @param args_decl The declaration of the arguments for the hook, for example
  88  * "(int x,void *y)"
  89  * @param args_use The arguments for the hook as used in a call, for example
  90  * "(x,y)"
  91  * @note If IMPLEMENTing a hook that is not linked into the Apache core,
  92  * (e.g. within a dso) see APR_IMPLEMENT_EXTERNAL_HOOK_VOID.
  93  */
  94 #define AP_IMPLEMENT_HOOK_VOID(name,args_decl,args_use) \
  95         APR_IMPLEMENT_EXTERNAL_HOOK_VOID(ap,AP,name,args_decl,args_use)
  96
  97 /**
  98  * Implement an Apache core hook that runs until one of the functions
  99  * returns something other than ok or decline. That return value is
 100  * then returned from the hook runner. If the hooks run to completion,
 101  * then ok is returned. Note that if no hook runs it would probably be
 102  * more correct to return decline, but this currently does not do
 103  * so. The implementation is called ap_run_<i>name</i>.
 104  *
 105  * @param ret The return type of the hook (and the hook runner)
 106  * @param name The name of the hook
 107  * @param args_decl The declaration of the arguments for the hook, for example
 108  * "(int x,void *y)"
 109  * @param args_use The arguments for the hook as used in a call, for example
 110  * "(x,y)"
 111  * @param ok The "ok" return value
 112  * @param decline The "decline" return value
 113  * @return ok, decline or an error.
 114  * @note If IMPLEMENTing a hook that is not linked into the Apache core,
 115  * (e.g. within a dso) see APR_IMPLEMENT_EXTERNAL_HOOK_RUN_ALL.
 116  */
 117 #define AP_IMPLEMENT_HOOK_RUN_ALL(ret,name,args_decl,args_use,ok,decline) \
 118         APR_IMPLEMENT_EXTERNAL_HOOK_RUN_ALL(ap,AP,ret,name,args_decl, \
 119                                             args_use,ok,decline)
 120
 121 /**
 122  * Implement a hook that runs until a function returns something other than
 123  * decline. If all functions return decline, the hook runner returns decline.
 124  * The implementation is called ap_run_<i>name</i>.
 125  *
 126  * @param ret The return type of the hook (and the hook runner)
 127  * @param name The name of the hook
 128  * @param args_decl The declaration of the arguments for the hook, for example
 129  * "(int x,void *y)"
 130  * @param args_use The arguments for the hook as used in a call, for example
 131  * "(x,y)"
 132  * @param decline The "decline" return value
 133  * @return decline or an error.
 134  * @note If IMPLEMENTing a hook that is not linked into the Apache core
 135  * (e.g. within a dso) see APR_IMPLEMENT_EXTERNAL_HOOK_RUN_FIRST.
 136  */
 137 #define AP_IMPLEMENT_HOOK_RUN_FIRST(ret,name,args_decl,args_use,decline) \
 138         APR_IMPLEMENT_EXTERNAL_HOOK_RUN_FIRST(ap,AP,ret,name,args_decl, \
 139                                               args_use,decline)
 140
 141 /* Note that the other optional hook implementations are straightforward but
 142  * have not yet been needed
 143  */
 144
 145 /**
 146  * Implement an optional hook. This is exactly the same as a standard hook
 147  * implementation, except the hook is optional.
 148  * @see AP_IMPLEMENT_HOOK_RUN_ALL
 149  */
 150 #define AP_IMPLEMENT_OPTIONAL_HOOK_RUN_ALL(ret,name,args_decl,args_use,ok, \
 151                                            decline) \
 152         APR_IMPLEMENT_OPTIONAL_HOOK_RUN_ALL(ap,AP,ret,name,args_decl, \
 153                                             args_use,ok,decline)
 154
 155 /**
 156  * Hook an optional hook. Unlike static hooks, this uses a macro instead of a
 157  * function.
 158  */
 159 #define AP_OPTIONAL_HOOK(name,fn,pre,succ,order) \
 160         APR_OPTIONAL_HOOK(ap,name,fn,pre,succ,order)
 161
 162 #endif /* AP_HOOKS_H */