Hook Functions

Collaboration diagram for Hook Functions:

Modules
	Hook probe capability
	Optional Hook Functions

Macros
#define	APR_IMPLEMENT_HOOK_GET_PROTO(ns, link, name)   link##_DECLARE(apr_array_header_t *) ns##_hook_get_##name(void)
#define	APR_DECLARE_EXTERNAL_HOOK(ns, link, ret, name, args)
#define	APR_HOOK_STRUCT(members)   static struct { members } _hooks;
#define	APR_HOOK_LINK(name)    apr_array_header_t *link_##name;
#define	APR_IMPLEMENT_EXTERNAL_HOOK_BASE(ns, link, name)
#define	APR_IMPLEMENT_EXTERNAL_HOOK_VOID(ns, link, name, args_decl, args_use)
#define	APR_IMPLEMENT_EXTERNAL_HOOK_RUN_ALL(ns, link, ret, name, args_decl, args_use, ok, decline)
#define	APR_IMPLEMENT_EXTERNAL_HOOK_RUN_FIRST(ns, link, ret, name, args_decl, args_use, decline)
#define	APR_HOOK_REALLY_FIRST   (-10)
#define	APR_HOOK_FIRST   0
#define	APR_HOOK_MIDDLE   10
#define	APR_HOOK_LAST   20
#define	APR_HOOK_REALLY_LAST   30

Functions
void	apr_hook_sort_register (const char *szHookName, apr_array_header_t **aHooks)
void	apr_hook_sort_all (void)
void	apr_hook_debug_show (const char *szName, const char *const *aszPre, const char *const *aszSucc)
void	apr_hook_deregister_all (void)

Variables
APR_DECLARE_DATA apr_pool_t *	apr_hook_global_pool
APR_DECLARE_DATA int	apr_hook_debug_enabled
APR_DECLARE_DATA const char *	apr_hook_debug_current

Detailed Description

Macro Definition Documentation

APR_DECLARE_EXTERNAL_HOOK

#define APR_DECLARE_EXTERNAL_HOOK	(		ns,
			link,
			ret,
			name,
			args
	)

Value:

typedef ret ns##_HOOK_##name##_t args; \
link##_DECLARE(void) ns##_hook_##name(ns##_HOOK_##name##_t *pf, \
                                      const char * const *aszPre, \
                                      const char * const *aszSucc, int nOrder); \
link##_DECLARE(ret) ns##_run_##name args; \
APR_IMPLEMENT_HOOK_GET_PROTO(ns,link,name); \
typedef struct ns##_LINK_##name##_t \
    { \
    ns##_HOOK_##name##_t *pFunc; \
    const char *szName; \
    const char * const *aszPredecessors; \
    const char * const *aszSuccessors; \
    int nOrder; \
    } ns##_LINK_##name##_t;

macro to declare the hook correctly

APR_HOOK_FIRST

#define APR_HOOK_FIRST   0

run this hook first

APR_HOOK_LAST

#define APR_HOOK_LAST   20

run this hook after every other hook which is defined

APR_HOOK_LINK

#define APR_HOOK_LINK

(

name

)

apr_array_header_t *link_##name;

macro to link the hook structure

APR_HOOK_MIDDLE

#define APR_HOOK_MIDDLE   10

run this hook somewhere

APR_HOOK_REALLY_FIRST

#define APR_HOOK_REALLY_FIRST   (-10)

run this hook first, before ANYTHING

APR_HOOK_REALLY_LAST

#define APR_HOOK_REALLY_LAST   30

run this hook last, after EVERYTHING

APR_HOOK_STRUCT

#define APR_HOOK_STRUCT

(

members

)

static struct { members } _hooks;

macro to declare the hook structure

APR_IMPLEMENT_EXTERNAL_HOOK_BASE

#define APR_IMPLEMENT_EXTERNAL_HOOK_BASE	(		ns,
			link,
			name
	)

Value:

link##_DECLARE(void) ns##_hook_##name(ns##_HOOK_##name##_t *pf,const char * const *aszPre, \
                                      const char * const *aszSucc,int nOrder) \
    { \
    ns##_LINK_##name##_t *pHook; \
    if(!_hooks.link_##name) \
    { \
        _hooks.link_##name=apr_array_make(apr_hook_global_pool,1,sizeof(ns##_LINK_##name##_t)); \
        apr_hook_sort_register(#name,&_hooks.link_##name); \
    } \
    pHook=apr_array_push(_hooks.link_##name); \
    pHook->pFunc=pf; \
    pHook->aszPredecessors=aszPre; \
    pHook->aszSuccessors=aszSucc; \
    pHook->nOrder=nOrder; \
    pHook->szName=apr_hook_debug_current; \
    if(apr_hook_debug_enabled) \
        apr_hook_debug_show(#name,aszPre,aszSucc); \
    } \
    APR_IMPLEMENT_HOOK_GET_PROTO(ns,link,name) \
    { \
        return _hooks.link_##name; \
    }

macro to implement the hook

APR_IMPLEMENT_EXTERNAL_HOOK_RUN_ALL

#define APR_IMPLEMENT_EXTERNAL_HOOK_RUN_ALL	(		ns,
			link,
			ret,
			name,
			args_decl,
			args_use,
			ok,
			decline
	)

Value:

APR_IMPLEMENT_EXTERNAL_HOOK_BASE(ns,link,name) \
link##_DECLARE(ret) ns##_run_##name args_decl \
    { \
    ns##_LINK_##name##_t *pHook; \
    int n; \
    ret rv = ok; \
    APR_HOOK_INT_DCL_UD; \
\
    APR_HOOK_PROBE_ENTRY(ud, ns, name, args_use); \
\
    if(_hooks.link_##name) \
        { \
        pHook=(ns##_LINK_##name##_t *)_hooks.link_##name->elts; \
        for(n=0 ; n < _hooks.link_##name->nelts ; ++n) \
            { \
            APR_HOOK_PROBE_INVOKE(ud, ns, name, (char *)pHook[n].szName, args_use); \
            rv=pHook[n].pFunc args_use; \
            APR_HOOK_PROBE_COMPLETE(ud, ns, name, (char *)pHook[n].szName, rv, args_use); \
            if(rv != ok && rv != decline) \
                break; \
            rv = ok; \
            } \
        } \
\
    APR_HOOK_PROBE_RETURN(ud, ns, name, rv, args_use); \
\
    return rv; \
    }

Implement a hook that runs until one of the functions returns something other than OK or DECLINE

Parameters

ns	The namespace prefix of the hook functions
link	The linkage declaration prefix of the hook
ret	Type to return
name	The name of the hook
args_decl	The declaration of the arguments for the hook
args_use	The names for the arguments for the hook
ok	Success value
decline	Decline value

Note

The link prefix FOO corresponds to FOO_DECLARE() macros, which provide export linkage from the module that IMPLEMENTs the hook, and import linkage from external modules that link to the hook's module.

APR_IMPLEMENT_EXTERNAL_HOOK_RUN_FIRST

#define APR_IMPLEMENT_EXTERNAL_HOOK_RUN_FIRST	(		ns,
			link,
			ret,
			name,
			args_decl,
			args_use,
			decline
	)

Value:

APR_IMPLEMENT_EXTERNAL_HOOK_BASE(ns,link,name) \
link##_DECLARE(ret) ns##_run_##name args_decl \
    { \
    ns##_LINK_##name##_t *pHook; \
    int n; \
    ret rv = decline; \
    APR_HOOK_INT_DCL_UD; \
\
    APR_HOOK_PROBE_ENTRY(ud, ns, name, args_use); \
\
    if(_hooks.link_##name) \
        { \
        pHook=(ns##_LINK_##name##_t *)_hooks.link_##name->elts; \
        for(n=0 ; n < _hooks.link_##name->nelts ; ++n) \
            { \
            APR_HOOK_PROBE_INVOKE(ud, ns, name, (char *)pHook[n].szName, args_use); \
            rv=pHook[n].pFunc args_use; \
            APR_HOOK_PROBE_COMPLETE(ud, ns, name, (char *)pHook[n].szName, rv, args_use); \
\
            if(rv != decline) \
                break; \
            } \
        } \
\
    APR_HOOK_PROBE_RETURN(ud, ns, name, rv, args_use); \
\
    return rv; \
    }

Implement a hook that runs until the first function returns something other than the value of decline

Parameters

ns	The namespace prefix of the hook functions
link	The linkage declaration prefix of the hook
name	The name of the hook
ret	Type to return
args_decl	The declaration of the arguments for the hook
args_use	The names for the arguments for the hook
decline	Decline value

Note

The link prefix FOO corresponds to FOO_DECLARE() macros, which provide export linkage from the module that IMPLEMENTs the hook, and import linkage from external modules that link to the hook's module.

APR_IMPLEMENT_EXTERNAL_HOOK_VOID

#define APR_IMPLEMENT_EXTERNAL_HOOK_VOID	(		ns,
			link,
			name,
			args_decl,
			args_use
	)

Value:

APR_IMPLEMENT_EXTERNAL_HOOK_BASE(ns,link,name) \
link##_DECLARE(void) ns##_run_##name args_decl \
    { \
    ns##_LINK_##name##_t *pHook; \
    int n; \
    APR_HOOK_INT_DCL_UD; \
\
    APR_HOOK_PROBE_ENTRY(ud, ns, name, args_use); \
\
    if(_hooks.link_##name) \
        { \
        pHook=(ns##_LINK_##name##_t *)_hooks.link_##name->elts; \
        for(n=0 ; n < _hooks.link_##name->nelts ; ++n) \
            { \
                APR_HOOK_PROBE_INVOKE(ud, ns, name, (char *)pHook[n].szName, args_use); \
                pHook[n].pFunc args_use; \
                APR_HOOK_PROBE_COMPLETE(ud, ns, name, (char *)pHook[n].szName, 0, args_use); \
            } \
        } \
\
    APR_HOOK_PROBE_RETURN(ud, ns, name, 0, args_use); \
\
    }

Implement a hook that has no return code, and therefore runs all of the registered functions

Parameters

ns	The namespace prefix of the hook functions
link	The linkage declaration prefix of the hook
name	The name of the hook
args_decl	The declaration of the arguments for the hook
args_use	The names for the arguments for the hook

Note

The link prefix FOO corresponds to FOO_DECLARE() macros, which provide export linkage from the module that IMPLEMENTs the hook, and import linkage from external modules that link to the hook's module.

APR_IMPLEMENT_HOOK_GET_PROTO

#define APR_IMPLEMENT_HOOK_GET_PROTO	(		ns,
			link,
			name
	)		link##_DECLARE(apr_array_header_t *) ns##_hook_get_##name(void)

macro to return the prototype of the hook function

Function Documentation

apr_hook_debug_show()

void apr_hook_debug_show	(	const char *	szName,
		const char *const *	aszPre,
		const char *const *	aszSucc
	)

Print all of the information about the current hook. This is used for debugging purposes.

Parameters

szName	The name of the hook
aszPre	All of the functions in the predecessor array
aszSucc	All of the functions in the successor array

apr_hook_deregister_all()

void apr_hook_deregister_all

(

void

)

Remove all currently registered functions.

apr_hook_sort_all()

void apr_hook_sort_all

(

void

)

Sort all of the registered functions for a given hook.

apr_hook_sort_register()

void apr_hook_sort_register	(	const char *	szHookName,
		apr_array_header_t **	aHooks
	)

Register a hook function to be sorted.

Parameters

szHookName	The name of the Hook the function is registered for
aHooks	The array which stores all of the functions for this hook

Variable Documentation

apr_hook_debug_current

APR_DECLARE_DATA const char* apr_hook_debug_current

extern

The name of the module that is currently registering a function.

apr_hook_debug_enabled

APR_DECLARE_DATA int apr_hook_debug_enabled

extern

A global variable to determine if debugging information about the hooks functions should be printed.

apr_hook_global_pool

APR_DECLARE_DATA apr_pool_t* apr_hook_global_pool

extern

The global pool used to allocate any memory needed by the hooks.