Apache2
 All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Apache Hooks
Collaboration diagram for Apache Hooks:

Functions

int mpm (apr_pool_t *pconf, apr_pool_t *plog, server_rec *server_conf)
 
void child_status (server_rec *s, pid_t pid, ap_generation_t gen, int slot, mpm_child_status state)
 
void end_generation (server_rec *s, ap_generation_t gen)
 
int header_parser (request_rec *r)
 
int pre_config (apr_pool_t *pconf, apr_pool_t *plog, apr_pool_t *ptemp)
 
int check_config (apr_pool_t *pconf, apr_pool_t *plog, apr_pool_t *ptemp, server_rec *s)
 
void test_config (apr_pool_t *pconf, server_rec *s)
 
int post_config (apr_pool_t *pconf, apr_pool_t *plog, apr_pool_t *ptemp, server_rec *s)
 
int open_logs (apr_pool_t *pconf, apr_pool_t *plog, apr_pool_t *ptemp, server_rec *s)
 
void child_init (apr_pool_t *pchild, server_rec *s)
 
int handler (request_rec *r)
 
int quick_handler (request_rec *r, int lookup_uri)
 
void optional_fn_retrieve (void)
 
apr_status_t open_htaccess (request_rec *r, const char *dir_name, const char *access_name, ap_configfile_t **conffile, const char **full_name)
 
int get_mgmt_items (apr_pool_t *p, const char *val, apr_hash_t *ht)
 
void error_log (const ap_errorlog_info *info, const char *errstr)
 
int generate_log_id (const conn_rec *c, const request_rec *r, const char **id)
 
void insert_error_filter (request_rec *r)
 
int create_request (request_rec *r)
 
int translate_name (request_rec *r)
 
int map_to_storage (request_rec *r)
 
int check_user_id (request_rec *r)
 
int fixups (request_rec *r)
 
int type_checker (request_rec *r)
 
int access_checker (request_rec *r)
 
int access_checker_ex (request_rec *r)
 
int auth_checker (request_rec *r)
 
void insert_filter (request_rec *r)
 
int post_perdir_config (request_rec *r)
 
int force_authn (request_rec *r)
 
apr_status_t dirwalk_stat (apr_finfo_t *finfo, request_rec *r, apr_int32_t wanted)
 
int monitor (apr_pool_t *p, server_rec *s)
 
int mpm_query (int query_code, int *result, apr_status_t *rv)
 
apr_status_t mpm_register_timed_callback (apr_time_t t, ap_mpm_callback_fn_t *cbfn, void *baton)
 
apr_status_t mpm_register_poll_callback (apr_array_header_t *pds, ap_mpm_callback_fn_t *cbfn, void *baton)
 
apr_status_t mpm_unregister_poll_callback (apr_array_header_t *pds)
 
apr_status_t mpm_resume_suspended (conn_rec *)
 
const char * mpm_get_name (void)
 
int output_pending (conn_rec *c)
 
int input_pending (conn_rec *c)
 
void suspend_connection (conn_rec *c, request_rec *r)
 
void resume_connection (conn_rec *c, request_rec *r)
 
int pre_mpm (apr_pool_t *p, ap_scoreboard_e sb_type)
 

Detailed Description

Function Documentation

int access_checker ( request_rec r)

This hook is used to apply additional access control to this resource. It runs before a user is authenticated, so this hook is really to apply additional restrictions independent of a user. It also runs independent of 'Require' directive usage. This hook should be registered with ap_hook_check_access().

Parameters
rthe current request
Returns
OK, DECLINED, or HTTP_...
See Also
ap_hook_check_access
int access_checker_ex ( request_rec r)

This hook is used to apply additional access control and/or bypass authentication for this resource. It runs before a user is authenticated, but after the access_checker hook. This hook should be registered with ap_hook_check_access_ex(). If "Satisfy any" is in effect, this hook may be skipped.

Parameters
rthe current request
Returns
OK (allow acces), DECLINED (let later modules decide), or HTTP_... (deny access)
See Also
ap_hook_check_access_ex
int auth_checker ( request_rec r)

This hook is used to check to see if the resource being requested is available for the authenticated user (r->user and r->ap_auth_type). It runs after the access_checker and check_user_id hooks. Note that it will only be called if Apache determines that access control has been applied to this resource (through a 'Require' directive). This hook should be registered with ap_hook_check_authz(). If "Satisfy any" is in effect, this hook may be skipped.

Parameters
rthe current request
Returns
OK, DECLINED, or HTTP_...
See Also
ap_hook_check_authz
int check_config ( apr_pool_t pconf,
apr_pool_t plog,
apr_pool_t ptemp,
server_rec s 
)

Run the check_config function for each module

Parameters
pconfThe config pool
plogThe logging streams pool
ptempThe temporary pool
sthe server to operate upon
Returns
OK or DECLINED on success anything else is a error
int check_user_id ( request_rec r)

This hook is used to analyze the request headers, authenticate the user, and set the user information in the request record (r->user and r->ap_auth_type). This hook is only run when Apache determines that authentication/authorization is required for this resource (as determined by the 'Require' directive). It runs after the access_checker hook, and before the auth_checker hook. This hook should be registered with ap_hook_check_authn(). If "Satisfy any" is in effect, this hook may be skipped.

Parameters
rThe current request
Returns
OK, DECLINED, or HTTP_...
See Also
ap_hook_check_authn
void child_init ( apr_pool_t pchild,
server_rec s 
)

Run the child_init functions for each module

Parameters
pchildThe child pool
sThe list of server_recs in this server
void child_status ( server_rec s,
pid_t  pid,
ap_generation_t  gen,
int  slot,
mpm_child_status  state 
)

Allow a module to remain aware of MPM child process state changes, along with the generation and scoreboard slot of the process changing state.

With some MPMs (event and worker), an active MPM child process may lose its scoreboard slot if the child process is exiting and the scoreboard slot is needed by other processes. When this occurs, the hook will be called with the MPM_CHILD_LOST_SLOT state.

Parameters
sThe main server_rec.
pidThe id of the MPM child process.
genThe server generation of that child process.
slotThe scoreboard slot number, or -1. It will be -1 when an MPM child process exits, and that child had previously lost its scoreboard slot.
stateOne of the mpm_child_status values. Modules should ignore unrecognized values.
int create_request ( request_rec r)

Gives modules a chance to create their request_config entry when the request is created.

Parameters
rThe current request
apr_status_t dirwalk_stat ( apr_finfo_t finfo,
request_rec r,
apr_int32_t  wanted 
)

This hook allows modules to handle/emulate the apr_stat() calls needed for directory walk.

Parameters
finfowhere to put the stat data
rThe current request
wantedAPR_FINFO_* flags to pass to apr_stat()
Returns
apr_status_t or AP_DECLINED (let later modules decide)
void end_generation ( server_rec s,
ap_generation_t  gen 
)

Allow a module to be notified when the last child process of a generation exits.

Parameters
sThe main server_rec.
genThe server generation which is now completely finished.
void error_log ( const ap_errorlog_info info,
const char *  errstr 
)

hook method to log error messages

Parameters
infopointer to ap_errorlog_info struct which contains all the details
errstrthe (unformatted) message to log
Warning
Allocating from the usual pools (pool, info->c->pool, info->p->pool) must be avoided because it can cause memory leaks. Use a subpool if necessary.
int fixups ( request_rec r)

Allows modules to perform module-specific fixing of header fields. This is invoked just before any content-handler

Parameters
rThe current request
Returns
OK, DECLINED, or HTTP_...
int force_authn ( request_rec r)

This hook allows a module to force authn to be required when processing a request. This hook should be registered with ap_hook_force_authn().

Parameters
rThe current request
Returns
OK (force authn), DECLINED (let later modules decide)
int generate_log_id ( const conn_rec c,
const request_rec r,
const char **  id 
)

hook method to generate unique id for connection or request

Parameters
cthe conn_rec of the connections
rthe request_req (may be NULL)
idthe place where to store the unique id
Returns
OK or DECLINE
int get_mgmt_items ( apr_pool_t p,
const char *  val,
apr_hash_t ht 
)

This hook provdes a way for modules to provide metrics/statistics about their operational status.

Parameters
pA pool to use to create entries in the hash table
valThe name of the parameter(s) that is wanted. This is tree-structured would be in the form ('*' is all the tree, 'module.*' all of the module , 'module.foo.*', or 'module.foo.bar' )
htThe hash table to store the results. Keys are item names, and the values point to ap_mgmt_item_t structures.
int handler ( request_rec r)

Run the handler functions for each module

Parameters
rThe request_rec
Remarks
non-wildcard handlers should HOOK_MIDDLE, wildcard HOOK_LAST
int header_parser ( request_rec r)

Run the header parser functions for each module

Parameters
rThe current request
Returns
OK or DECLINED
int input_pending ( conn_rec c)

Hook called to determine whether any data is pending in the input filters.

Parameters
cThe current connection
Returns
OK if we can read without blocking, DECLINED if a read would block.
void insert_error_filter ( request_rec r)

This hook allows modules to insert filters for the current error response

Parameters
rthe current request
void insert_filter ( request_rec r)

This hook allows modules to insert filters for the current request

Parameters
rthe current request
int map_to_storage ( request_rec r)

This hook allow modules to set the per_dir_config based on their own context (such as "<Proxy>" sections) and responds to contextless requests such as TRACE that need no security or filesystem mapping. based on the filesystem.

Parameters
rThe current request
Returns
DONE (or HTTP_) if this contextless request was just fulfilled (such as TRACE), OK if this is not a file, and DECLINED if this is a file. The core map_to_storage (HOOK_RUN_REALLY_LAST) will directory_walk and file_walk the r->filename.
int monitor ( apr_pool_t p,
server_rec s 
)

This hook allows modules to be called at intervals by some MPMs in the parent process. IOW, this is not portable to all platforms or MPMs.

Parameters
pThe pconf pool
sThe main server
Returns
OK or DECLINED (errors are ignored)
int mpm ( apr_pool_t pconf,
apr_pool_t plog,
server_rec server_conf 
)

Pass control to the MPM for steady-state processing. It is responsible for controlling the parent and child processes. It will run until a restart/shutdown is indicated.

Parameters
pconfthe configuration pool, reset before the config file is read
plogthe log pool, reset after the config file is read
server_confthe global server config.
Returns
DONE for shutdown OK otherwise.
const char* mpm_get_name ( void  )

Get MPM name (e.g., "prefork" or "event")

int mpm_query ( int  query_code,
int result,
apr_status_t rv 
)

implement the ap_mpm_query() function The MPM should return OK+APR_ENOTIMPL for any unimplemented query codes; modules which intercede for specific query codes should DECLINE for others.

apr_status_t mpm_register_poll_callback ( apr_array_header_t pds,
ap_mpm_callback_fn_t cbfn,
void baton 
)

register the specified callback

apr_status_t mpm_register_timed_callback ( apr_time_t  t,
ap_mpm_callback_fn_t cbfn,
void baton 
)

register the specified callback

apr_status_t mpm_resume_suspended ( conn_rec )

Resume the suspended connection

apr_status_t mpm_unregister_poll_callback ( apr_array_header_t pds)

Unregister the specified callback

apr_status_t open_htaccess ( request_rec r,
const char *  dir_name,
const char *  access_name,
ap_configfile_t **  conffile,
const char **  full_name 
)

Allow modules to open htaccess files or perform operations before doing so

Parameters
rThe current request
dir_nameThe directory for which the htaccess file should be opened
access_nameThe filename for which the htaccess file should be opened
conffileWhere the pointer to the opened ap_configfile_t must be stored
full_nameWhere the full file name of the htaccess file must be stored.
Returns
APR_SUCCESS on success, APR_ENOENT or APR_ENOTDIR if no htaccess file exists, AP_DECLINED to let later modules do the opening, any other error code on error.
int open_logs ( apr_pool_t pconf,
apr_pool_t plog,
apr_pool_t ptemp,
server_rec s 
)

Run the open_logs functions for each module

Parameters
pconfThe config pool
plogThe logging streams pool
ptempThe temporary pool
sThe list of server_recs
Returns
OK or DECLINED on success anything else is a error
void optional_fn_retrieve ( void  )

Retrieve the optional functions for each module. This is run immediately before the server starts. Optional functions should be registered during the hook registration phase.

int output_pending ( conn_rec c)

Hook called to determine whether we should stay within the write completion phase.

Parameters
cThe current connection
Returns
OK if write completion should continue, DECLINED if write completion should end gracefully, or a positive error if we should begin to linger.
int post_config ( apr_pool_t pconf,
apr_pool_t plog,
apr_pool_t ptemp,
server_rec s 
)

Run the post_config function for each module

Parameters
pconfThe config pool
plogThe logging streams pool
ptempThe temporary pool
sThe list of server_recs
Returns
OK or DECLINED on success anything else is a error
int post_perdir_config ( request_rec r)

This hook allows modules to affect the request immediately after the per-directory configuration for the request has been generated.

Parameters
rThe current request
Returns
OK (allow acces), DECLINED (let later modules decide), or HTTP_... (deny access)
int pre_config ( apr_pool_t pconf,
apr_pool_t plog,
apr_pool_t ptemp 
)

Run the pre_config function for each module

Parameters
pconfThe config pool
plogThe logging streams pool
ptempThe temporary pool
Returns
OK or DECLINED on success anything else is a error
int pre_mpm ( apr_pool_t p,
ap_scoreboard_e  sb_type 
)

Hook for post scoreboard creation, pre mpm.

Parameters
pApache pool to allocate from.
sb_type
Returns
OK or DECLINE on success; anything else is a error
int quick_handler ( request_rec r,
int  lookup_uri 
)

Run the quick handler functions for each module. The quick_handler is run before any other requests hooks are called (location_walk, directory_walk, access checking, et. al.). This hook was added to provide a quick way to serve content from a URI keyed cache.

Parameters
rThe request_rec
lookup_uriControls whether the caller actually wants content or not. lookup is set when the quick_handler is called out of ap_sub_req_lookup_uri()
void resume_connection ( conn_rec c,
request_rec r 
)

Notification that connection handling is resuming (associating with a thread)

Parameters
cThe current connection
rThe current request, or NULL if there is no active request
See Also
ap_hook_suspend_connection
Note
This hook is not implemented by MPMs like Prefork and Worker which handle all processing of a particular connection on the same thread.
This hook will be called on the thread that will resume processing the connection.
This hook is not called at the beginning of connection processing. This hook only notifies a module when processing resumes for a previously-suspended connection.
Resumption and subsequent suspension of a connection solely to perform I/O by the MPM, with no execution of non-MPM code, may not necessarily result in a call to this hook.
void suspend_connection ( conn_rec c,
request_rec r 
)

Notification that connection handling is suspending (disassociating from the current thread)

Parameters
cThe current connection
rThe current request, or NULL if there is no active request
See Also
ap_hook_resume_connection
Note
This hook is not implemented by MPMs like Prefork and Worker which handle all processing of a particular connection on the same thread.
This hook will be called on the thread that was previously processing the connection.
This hook is not called at the end of connection processing. This hook only notifies a module when processing of an active connection is suspended.
Resumption and subsequent suspension of a connection solely to perform I/O by the MPM, with no execution of non-MPM code, may not necessarily result in a call to this hook.
void test_config ( apr_pool_t pconf,
server_rec s 
)

Run the test_config function for each module; this hook is run only if the server was invoked to test the configuration syntax.

Parameters
pconfThe config pool
sThe list of server_recs
Note
To avoid reordering problems due to different buffering, hook functions should only apr_file_*() to print to stdout/stderr and not simple printf()/fprintf().
int translate_name ( request_rec r)

This hook allow modules an opportunity to translate the URI into an actual filename. If no modules do anything special, the server's default rules will be followed.

Parameters
rThe current request
Returns
OK, DECLINED, or HTTP_...
int type_checker ( request_rec r)

This routine is called to determine and/or set the various document type information bits, like Content-type (via r->content_type), language, et cetera.

Parameters
rthe current request
Returns
OK, DECLINED, or HTTP_...