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 */ 163