In general, a hook function is one that Apache will call at - some point during the processing of a request. Modules can - provide functions that are called, and specify when they get - called in comparison to other modules.

Creating a hook function

Declare the hook function

Use the AP_DECLARE_HOOK macro, which needs to be given the - return type of the hook function, the name of the hook, and the - arguments. For example, if the hook returns an int and - takes a request_rec * and an int and is - called "do_something", then declare it like this:

This should go in a header which modules will include if - they want to use the hook.

Create the hook structure

Each source file that exports a hook has a private structure - which is used to record the module functions that use the hook. - This is declared as follows:

Implement the hook caller

The source file that exports the hook has to implement a - function that will call the hook. There are currently three - possible ways to do this. In all cases, the calling function is - called ap_run_hookname().

Void hooks

If the return value of a hook is void, then all the - hooks are called, and the caller is implemented like this:

The second and third arguments are the dummy argument - declaration and the dummy arguments as they will be used when - calling the hook. In other words, this macro expands to - something like this:

Hooks that return a value

If the hook returns a value, then it can either be run until - the first hook that does something interesting, like so:

The first hook that doesn't return DECLINED - stops the loop and its return value is returned from the hook - caller. Note that DECLINED is the tradition Apache - hook return meaning "I didn't do anything", but it can be - whatever suits you.

Alternatively, all hooks can be run until an error occurs. - This boils down to permitting two return values, one of - which means "I did something, and it was OK" and the other - meaning "I did nothing". The first function that returns a - value other than one of those two stops the loop, and its - return is the return value. Declare these like so:

Again, OK and DECLINED are the traditional - values. You can use what you want.

Call the hook callers

Hooking the hook

Implement the hook function

Include the appropriate header, and define a static function - of the correct type:

Add a hook registering function

During initialisation, Apache will call each modules hook - registering function, which is included in the module - structure:

Controlling hook calling order

In the example above, we didn't use the three arguments in - the hook registration function that control calling order. - There are two mechanisms for doing this. The first, rather - crude, method, allows us to specify roughly where the hook is - run relative to other modules. The final argument control this. - There are three possible values:

All modules using any particular value may be run in any - order relative to each other, but, of course, all modules using - HOOK_FIRST will be run before HOOK_MIDDLE - which are before HOOK_LAST. Modules that don't care - when they are run should use HOOK_MIDDLE. (I spaced - these out so people could do stuff like HOOK_FIRST-2 - to get in slightly earlier, but is this wise? - Ben)

Note that there are two more values, - HOOK_REALLY_FIRST and HOOK_REALLY_LAST. These - should only be used by the hook exporter.

The other method allows finer control. When a module knows - that it must be run before (or after) some other modules, it - can specify them by name. The second (third) argument is a - NULL-terminated array of strings consisting of the names of - modules that must be run before (after) the current module. For - example, suppose we want "mod_xyz.c" and "mod_abc.c" to run - before we do, then we'd hook as follows:

Note that the sort used to achieve this is stable, so - ordering set by HOOK_ORDER is preserved, as far - as is possible.

Apache 2.0 Hook Functions

Warning

This document is still in development and may be partially out of + date.

+ +

In general, a hook function is one that Apache will call at + some point during the processing of a request. Modules can + provide functions that are called, and specify when they get + called in comparison to other modules.

Creating a hook function
Hooking the hook

Creating a hook function

In order to create a new hook, four things need to be + done:

+ +

Declare the hook function

Use the AP_DECLARE_HOOK macro, which needs to be given + the return type of the hook function, the name of the hook, and the + arguments. For example, if the hook returns an int and + takes a request_rec * and an int and is + called do_something, then declare it like this:

+ AP_DECLARE_HOOK(int, do_something, (request_rec *r, int n)) +

+ +

This should go in a header which modules will include if + they want to use the hook.

+ + +

Create the hook structure

Each source file that exports a hook has a private structure + which is used to record the module functions that use the hook. + This is declared as follows:

+ +

+ APR_HOOK_STRUCT( + + APR_HOOK_LINK(do_something) + ... + + ) +

+ + +

Implement the hook caller

The source file that exports the hook has to implement a + function that will call the hook. There are currently three + possible ways to do this. In all cases, the calling function is + called ap_run_hookname().

+ +

Void hooks

If the return value of a hook is void, then all the + hooks are called, and the caller is implemented like this:

+ +

+ AP_IMPLEMENT_HOOK_VOID(do_something, (request_rec *r, int n), (r, n)) +

+ +

The second and third arguments are the dummy argument + declaration and the dummy arguments as they will be used when + calling the hook. In other words, this macro expands to + something like this:

+ +

+ void ap_run_do_something(request_rec *r, int n) + { + + ... + do_something(r, n); + + } +

+ + +

Hooks that return a value

If the hook returns a value, then it can either be run until + the first hook that does something interesting, like so:

+ +

+ AP_IMPLEMENT_HOOK_RUN_FIRST(int, do_something, (request_rec *r, int n), (r, n), DECLINED) +

+ +

The first hook that does not return DECLINED + stops the loop and its return value is returned from the hook + caller. Note that DECLINED is the tradition Apache + hook return meaning "I didn't do anything", but it can be + whatever suits you.

+ +

Alternatively, all hooks can be run until an error occurs. + This boils down to permitting two return values, one of + which means "I did something, and it was OK" and the other + meaning "I did nothing". The first function that returns a + value other than one of those two stops the loop, and its + return is the return value. Declare these like so:

+ +

+ AP_IMPLEMENT_HOOK_RUN_ALL(int, do_something, (request_rec *r, int n), (r, n), OK, DECLINED) +

+ +

Again, OK and DECLINED are the traditional + values. You can use what you want.

+ + + +

Call the hook callers

At appropriate moments in the code, call the hook caller, + like so:

+ +

+ int n, ret; + request_rec *r; + + ret=ap_run_do_something(r, n); +

+ +

Hooking the hook

A module that wants a hook to be called needs to do two + things.

+ +

Implement the hook function

Include the appropriate header, and define a static function + of the correct type:

+ +

+ static int my_something_doer(request_rec *r, int n) + { + + ... + return OK; + + } +

+ + +

Add a hook registering function

During initialisation, Apache will call each modules hook + registering function, which is included in the module + structure:

+ +

+ static void my_register_hooks() + { + + ap_hook_do_something(my_something_doer, NULL, NULL, HOOK_MIDDLE); + + } + + mode MODULE_VAR_EXPORT my_module = + { + + ... + my_register_hooks /* register hooks */ + + }; +

+ + +

Controlling hook calling order

In the example above, we didn't use the three arguments in + the hook registration function that control calling order. + There are two mechanisms for doing this. The first, rather + crude, method, allows us to specify roughly where the hook is + run relative to other modules. The final argument control this. + There are three possible values: HOOK_FIRST, + HOOK_MIDDLE and HOOK_LAST.

+ +

All modules using any particular value may be run in any + order relative to each other, but, of course, all modules using + HOOK_FIRST will be run before HOOK_MIDDLE + which are before HOOK_LAST. Modules that don't care + when they are run should use HOOK_MIDDLE. (I spaced + these out so people could do stuff like HOOK_FIRST-2 + to get in slightly earlier, but is this wise? - Ben)

+ +

Note that there are two more values, + HOOK_REALLY_FIRST and HOOK_REALLY_LAST. These + should only be used by the hook exporter.

+ +

The other method allows finer control. When a module knows + that it must be run before (or after) some other modules, it + can specify them by name. The second (third) argument is a + NULL-terminated array of strings consisting of the names of + modules that must be run before (after) the current module. For + example, suppose we want "mod_xyz.c" and "mod_abc.c" to run + before we do, then we'd hook as follows:

+ +

+ static void register_hooks() + { + + static const char * const aszPre[] = { "mod_xyz.c", "mod_abc.c", NULL }; + + ap_hook_do_something(my_something_doer, aszPre, NULL, HOOK_MIDDLE); + + } +

+ +

Note that the sort used to achieve this is stable, so + ordering set by HOOK_ORDER is preserved, as far + as is possible.

+ +

Ben Laurie, 15th August 1999

+ +

Apache Hook Functions

Creating a hook function

Declare the hook function

Create the hook structure

Implement the hook caller

Void hooks

Hooks that return a value

Call the hook callers

Hooking the hook

Implement the hook function

Add a hook registering function

Controlling hook calling order

Apache 2.0 Hook Functions

Warning

Void hooks

Hooks that return a value