2006年08月04日

[補足記事]Apache 2.0 の hook 一覧(apache module 開発事初め その3-3)

はてなブックマークに登録

先日この記事において hook の呼び出しに関してコメントを頂きました.
実際のところよく分かってない部分もあったので,hook に関してまとめてみました.

このページの記述について

このページの内容に関して
英語の文章は,全て Apache 2.0.58 のソースコード中から集めてきた原文ママです.
全ての hook に関して調べ尽くした訳じゃないので間違いもあると思います.間違いに気づかれた方はコメントで指摘いただければ幸いです m(_ _)m
hook の呼び出し順序に関して
hook が呼び出される順序は,「設定初期化」「プロセス初期化」「コネクション」「リクエスト」に関しては記述した順序で呼び出されるようです.
RUN_ALL,RUN_FIRST について
RUN_FIRST の hook は,呼び出した hook 処理関数が OK や DECLINE エラーを返した場合,その次の hook 処理関数を呼び出しません.
RUN_ALL の hook は,呼び出した hook 処理関数がエラーを返さない限り,登録されている全ての hook 処理関数を呼び出します.
hook 登録関数 ap_hook_xxx() の引数について
ap_hook_xxx() への引数は全て同じです.内容については,こちらを参照ください.
登録する hook 処理関数のプロトタイプは,各 hook 登録関数の説明の下に併記しています.

Index

設定初期化
RUN_ALLap_hook_pre_config()
RUN_ALLap_hook_open_logs()
RUN_ALLap_hook_post_config()
VOIDap_hook_optional_fn_retrieve()
プロセス初期化
RUN_ALLap_hook_pre_mpm()
VOIDap_hook_child_init()
コネクション
RUN_FIRSTap_hook_create_connection()
RUN_ALLap_hook_pre_connection()
RUN_FIRSTap_hook_process_connection()
リクエスト
RUN_ALLap_hook_create_request()
RUN_ALLap_hook_post_read_request()
RUN_FIRSTap_hook_quick_handler()
RUN_FIRSTap_hook_translate_name()
RUN_FIRSTap_hook_map_to_storage()
RUN_ALLap_hook_header_parser()
RUN_ALLap_hook_access_checker()
RUN_FIRSTap_hook_check_user_id()
RUN_FIRSTap_hook_auth_checker()
RUN_FIRSTap_hook_type_checker()
RUN_ALLap_hook_fixups()
VOIDap_hook_insert_filter()
RUN_FIRSTap_hook_handler()
RUN_ALLap_hook_log_transaction()
エラー
VOIDap_hook_insert_error_filter()
VOIDap_hook_error_log()
必要時
RUN_FIRSTap_hook_default_port()
RUN_FIRSTap_hook_http_method()
任意のタイミング?
RUN_ALLap_hook_fatal_exception()
RUN_ALLap_hook_get_mgmt_items()
RUN_FIRSTap_hook_uexec_identity()

説明

ap_hook_pre_config() RUN_ALL
Run the pre_config function for each module
int x_pre_config(apr_pool_t *pconf,
                 apr_pool_t *plog,
                 apr_pool_t *ptemp)
return OK or DECLINED on success anything else is a error
pconf The config pool
plog The logging streams pool
ptemp The temporary pool
ap_hook_open_logs() RUN_ALL
Run the open_logs functions for each module
int x_open_logs(apr_pool_t *pconf,
                apr_pool_t *plog,
                apr_pool_t *ptemp,
                server_rec *s)
return OK or DECLINED on success anything else is a error
pconf The config pool
plog The logging streams pool
ptemp The temporary pool
s The list of server_recs
ap_hook_post_config() RUN_ALL
Run the post_config function for each module
int x_post_config(apr_pool_t *pconf,
                  apr_pool_t *plog,
                  apr_pool_t *ptemp,
                  server_rec *s)
return OK or DECLINED on success anything else is a error
pconf The config pool
plog The logging streams pool
ptemp The temporary pool
s The list of server_recs
ap_hook_optional_fn_retrieve()
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.
void x_optional_fn_retrieve(void)
ap_hook_pre_mpm() RUN_ALL
Hook for post scoreboard creation, pre mpm.
int x_pre_mpm(apr_pool_t *p,
              ap_scoreboard_e sb_type)
return OK or DECLINE on success; anything else is a error
p Apache pool to allocate from.
sb_type
ap_hook_child_init()
Run the child_init functions for each module
void x_child_init(apr_pool_t *pchild,
                  server_rec *s)
pchild The child pool
s The list of server_recs in this server
ap_hook_create_connection() RUN_FIRST
create_connection is a RUN_FIRST hook which allows modules to create connections. In general, you should not install filters with the create_connection hook. If you require vhost configuration information to make filter installation decisions, you must use the pre_connection or install_network_transport hook. This hook should close the connection if it encounters a fatal error condition.
conn_rec * x_create_connection(apr_pool_t *p,
                               server_rec *server,
                               apr_socket_t *csd,
                               long conn_id,
                               void *sbh,
                               apr_bucket_alloc_t *alloc)
return An allocated connection record or NULL.
server
p The pool from which to allocate the connection record
csd The socket that has been accepted
conn_id A unique identifier for this connection. The ID only needs to be unique at that time, not forever.
sbh A handle to scoreboard information for this connection.
alloc
ap_hook_pre_connection() RUN_ALL
This hook gives protocol modules an opportunity to set everything up before calling the protocol handler. All pre-connection hooks are run until one returns something other than ok or decline
Apache の付属文書によれば,accept()直後に呼ばれる
int x_pre_connection(conn_rec *c,
                     void *csd)
return OK or DECLINED
c The connection on which the request has been received.
csd The mechanism on which this connection is to be read. Most times this will be a socket, but it is up to the module that accepts the request to determine the exact type.
ap_hook_process_connection() RUN_FIRST
This hook implements different protocols. After a connection has been established, the protocol module must read and serve the request. This function does that for each protocol module. The first protocol module to handle the request is the last module run.
int x_process_connection(conn_rec *c)
return OK or DECLINED
c The connection on which the request has been received.
ap_hook_create_request() RUN_ALL
Gives modules a chance to create their request_config entry when the request is created.
int x_create_request(request_rec *r)
return OK or DECLINED
r The current request
ap_hook_post_read_request() RUN_ALL
This hook allows modules to affect the request immediately after the request has been read, and before any other phases have been processes. This allows modules to make decisions based upon the input header fields
int x_post_read_request(request_rec *r)
return OK or DECLINED
r The current request
ap_hook_quick_handler() RUN_FIRST
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.
Apache の付属文書によれば,キャッシュモジュールが使用している.
int x_quick_handler(request_rec *r,
                    int lookup_uri)
r The request_rec
lookup_uri Controls whether the caller actually wants content or not. lookup is set when the quick_handler is called out of ap_sub_req_lookup_uri()
ap_hook_translate_name() RUN_FIRST
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.
int x_translate_name(request_rec *r)
return OK, DECLINED, or HTTP_...
r The current request
ap_hook_map_to_storage() RUN_FIRST
This hook allow modules to set the per_dir_config based on their own context (such as sections) and responds to contextless requests such as TRACE that need no security or filesystem mapping. based on the filesystem.
int x_map_to_storage(request_rec *r)
return 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.
r The current request
ap_hook_header_parser() RUN_ALL
Run the header parser functions for each module
int x_header_parser(request_rec *r)
return OK or DECLINED
r The current request
ap_hook_access_checker() RUN_ALL
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.
int x_access_checker(request_rec *r)
return OK, DECLINED, or HTTP_...
r the current request
ap_hook_check_user_id() RUN_FIRST
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.
int x_check_user_id(request_rec *r)
return OK, DECLINED, or HTTP_...
r The current request
ap_hook_auth_checker() RUN_FIRST
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).
int x_auth_checker(request_rec *r)
return OK, DECLINED, or HTTP_...
r the current request
ap_hook_type_checker() RUN_FIRST
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.
int x_type_checker(request_rec *r)
return OK, DECLINED, or HTTP_...
r the current request
ap_hook_fixups() RUN_ALL
Allows modules to perform module-specific fixing of header fields. This is invoked just before any content-handler
int x_fixups(request_rec *r)
return OK, DECLINED, or HTTP_...
r The current request
ap_hook_insert_filter()
This hook allows modules to insert filters for the current request
void x_insert_filter(request_rec *r)
r the current request
ap_hook_handler() RUN_FIRST
Run the handler functions for each module non-wildcard handlers should HOOK_MIDDLE, wildcard HOOK_LAST
int x_handler(request_rec *r)
r The request_rec
ap_hook_log_transaction() RUN_ALL
This hook allows modules to perform any module-specific logging activities over and above the normal server things.
int x_log_transaction(request_rec *r)
return OK, DECLINED, or HTTP_...
r The current request
ap_hook_insert_error_filter()
This hook allows modules to insert filters for the current error response
void x_insert_error_filter(request_rec *r)
r the current request
ap_hook_error_log()
void x_error_log(const char *file,
                 int line,
                 int level,
                 apr_status_t status,
                 const server_rec *s,
                 const request_rec *r,
                 apr_pool_t *pool,
                 const char *errstr)
ap_hook_default_port() RUN_FIRST
Return the default port from the current request
apr_port_t x_default_port(const request_rec *r)
return The current port
r The current request
ap_hook_http_method() RUN_FIRST
This hook allows modules to retrieve the http method from a request. This allows Apache modules to easily extend the methods that Apache understands
ここで言う"method" は scheme の間違いのようです.実際,Apache 2.2 では ap_hook_http_scheme() に変更されています.
const char * x_http_method(const request_rec *r)
return The http method from the request
r The current request
ap_hook_fatal_exception() RUN_ALL
int x_fatal_exception(ap_exception_info_t *ei)
ap_hook_get_mgmt_items() RUN_ALL
This hook provdes a way for modules to provide metrics/statistics about their operational status.
int x_get_mgmt_items(apr_pool_t *p,
                     const char * val,
                     apr_hash_t *ht)
p A pool to use to create entries in the hash table
val The 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' )
ht The hash table to store the results. Keys are item names, and the values point to ap_mgmt_item_t structures.
ap_hook_get_suexec_identity() RUN_FIRST
ap_unix_identity_t * x_get_suexec_identity(const request_rec *r)

klab_gijutsu2 at 21:11│Comments(2)TrackBack(1)apache | 開発

トラックバックURL

この記事へのトラックバック

Apacheモジュールを開発する際にフックをかけるタイミングがたくさんあります...

この記事へのコメント

1. Posted by ありあり   2007年11月27日 15:32
RUN_FIRSTの場合、DECLINE(D)を返した場合は、次のフック関数を実行します。

以下、apr_hooks.h

#define APR_IMPLEMENT_EXTERNAL_HOOK_RUN_FIRST(ns,link,ret,name,args_decl,args_use,decline) \
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; \
\
if(!_hooks.link_##name) \
return decline; \
\
pHook=(ns##_LINK_##name##_t *)_hooks.link_##name->elts; \
for(n=0 ; n < _hooks.link_##name->nelts ; ++n) \
{ \
rv=pHook[n].pFunc args_use; \
\
if(rv != decline) \
return rv; \
} \
return decline; \
}
2. Posted by かつみ   2007年11月27日 16:35
ありありさんコメントありがとうございます.

挙げていただいたマクロ定義は,apache が hook を定義するためのマクロですね.RUN_ALL の hook も同様のマクロを使って定義されています.

で,ご指摘の頂いているのはこの記事での説明で,RUN_FIRST 用の hook 処理関数が DECLINE を返したときの動作に関しての事かと思います.

確認してみたところ確かに間違っておりましたので,修正いたしました.
ご指摘ありがとうございました.

この記事にコメントする

名前:
URL:
  情報を記憶: 評価: 顔   
 
 
 
Blog内検索
Archives
このブログについて
DSASとは、KLab が構築し運用しているコンテンツサービス用のLinuxベースのインフラです。現在5ヶ所のデータセンタにて構築し、運用していますが、我々はDSASをより使いやすく、より安全に、そしてより省力で運用できることを目指して、日々改良に勤しんでいます。
このブログでは、そんな DSAS で使っている技術の紹介や、実験してみた結果の報告、トラブルに巻き込まれた時の経験談など、広く深く、色々な話題を織りまぜて紹介していきたいと思います。
最新コメント
「最新トラックバック」は提供を終了しました。