From 558a1d5a03bce706b20758ea4d0f45a746c89a13 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9=20Malo?= Date: Sat, 5 Apr 2003 02:58:03 +0000 Subject: new XML git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/branches/APACHE_2_0_BRANCH@99229 13f79535-47bb-0310-9956-ffa450edef68 --- docs/manual/developer/hooks.html | 199 --------------------------------------- 1 file changed, 199 deletions(-) delete mode 100644 docs/manual/developer/hooks.html (limited to 'docs/manual/developer/hooks.html') diff --git a/docs/manual/developer/hooks.html b/docs/manual/developer/hooks.html deleted file mode 100644 index f7a5575d16..0000000000 --- a/docs/manual/developer/hooks.html +++ /dev/null @@ -1,199 +0,0 @@ - - - - - - - Apache 2.0 Hook Functions - - - - - - -

Apache Hook Functions

- -

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

- -

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 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:

- 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
-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 - - - - -- cgit v1.2.1