From: Yoshiki Hayashi Date: Wed, 10 Jul 2002 07:03:22 +0000 (+0000) Subject: New Japanese translation. X-Git-Tag: 2.0.40~282 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=87405dd5e6044a1645c1121fe62d14b32eda6f50;p=apache New Japanese translation. Submitted by: KUSANO Takayuki Reviewd by: Hiroaki KAWAI , Yoshiki Hayashi git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@96000 13f79535-47bb-0310-9956-ffa450edef68 --- diff --git a/docs/manual/developer/modules.html b/docs/manual/developer/modules.html deleted file mode 100644 index 259e27defe..0000000000 --- a/docs/manual/developer/modules.html +++ /dev/null @@ -1,258 +0,0 @@ - - - - - - - Converting Modules from Apache 1.3 to Apache 2.0 - - - - - - -

From Apache 1.3 to Apache 2.0
- Modules

- -

This is a first attempt at writing the lessons I learned - when trying to convert the mod_mmap_static module to Apache - 2.0. It's by no means definitive and probably won't even be - correct in some ways, but it's a start.

- -

The easier changes...

- -

Cleanup Routines

- -

These now need to be of type apr_status_t and return a value - of that type. Normally the return value will be APR_SUCCESS - unless there is some need to signal an error in the cleanup. Be - aware that even though you signal an error not all code yet - checks and acts upon the error.

- -

Initialisation Routines

- -

These should now be renamed to better signify where they sit - in the overall process. So the name gets a small change from - mmap_init to mmap_post_config. The arguments passed have - undergone a radical change and now look like

- -

apr_pool_t *p,
apr_pool_t *plog,
apr_pool_t *ptemp,
server_rec *s

- -

Data Types

- -

A lot of the data types have been moved into the APR. This - means that some have had a name change, such as the one shown - above. The following is a brief list of some of the changes - that you are likely to have to make.

- -

pool becomes apr_pool_t
table becomes apr_table_t

- -

The messier changes...

- -

Register Hooks

- -

The new architecture uses a series of hooks to provide for - calling your functions. These you'll need to add to your module - by way of a new function, static void register_hooks(void). The - function is really reasonably straightforward once you - understand what needs to be done. Each function that needs - calling at some stage in the processing of a request needs to - be registered, handlers do not. There are a number of phases - where functions can be added, and for each you can specify with - a high degree of control the relative order that the function - will be called in.

- -

This is the code that was added to mod_mmap_static:

-static void register_hooks(void)
-{
-    static const char * const aszPre[]={ "http_core.c",NULL };
-    ap_hook_post_config(mmap_post_config,NULL,NULL,HOOK_MIDDLE);
-    ap_hook_translate_name(mmap_static_xlat,aszPre,NULL,HOOK_LAST);
-};
-

- -

This registers 2 functions that need to be called, one in - the post_config stage (virtually every module will need this - one) and one for the translate_name phase. note that while - there are different function names the format of each is - identical. So what is the format?

- -

ap_hook_[phase_name](function_name, predecessors, - successors, position);

- -

There are 3 hook positions defined...

- -

HOOK_FIRST
HOOK_MIDDLE
HOOK_LAST

- -

To define the position you use the position and then modify - it with the predecessors and successors. Each of the modifiers - can be a list of functions that should be called, either before - the function is run (predecessors) or after the function has - run (successors).

- -

In the mod_mmap_static case I didn't care about the - post_config stage, but the mmap_static_xlat MUST be called - after the core module had done it's name translation, hence the - use of the aszPre to define a modifier to the position - HOOK_LAST.

- -

Module Definition

- -

There are now a lot fewer stages to worry about when - creating your module definition. The old defintion looked - like

-module MODULE_VAR_EXPORT [module_name]_module =
-{
-    STANDARD_MODULE_STUFF,
-    /* initializer */
-    /* dir config creater */
-    /* dir merger --- default is to override */
-    /* server config */
-    /* merge server config */
-    /* command handlers */
-    /* handlers */
-    /* filename translation */
-    /* check_user_id */
-    /* check auth */
-    /* check access */
-    /* type_checker */
-    /* fixups */
-    /* logger */
-    /* header parser */
-    /* child_init */
-    /* child_exit */
-    /* post read-request */
-};
-

- -

The new structure is a great deal simpler...

-module MODULE_VAR_EXPORT [module_name]_module =
-{
-    STANDARD20_MODULE_STUFF,
-    /* create per-directory config structures */
-    /* merge per-directory config structures  */
-    /* create per-server config structures    */
-    /* merge per-server config structures     */
-    /* command handlers */
-    /* handlers */
-    /* register hooks */
- };
-

- -

Some of these read directly across, some don't. I'll try to - summarise what should be done below.

- -

The stages that read directly across :

- -

/* dir config creater */ ==> /* create per-directory - config structures */
/* server config */ ==> /* create per-server config - structures */
/* dir merger */ ==> /* merge per-directory config - structures */
/* merge server config */ ==> /* merge per-server - config structures */
/* command table */ ==> /* command apr_table_t */
/* handlers */ ==> /* handlers */

- -

The remainder of the old functions should be registered as - hooks. There are the following hook stages defined so - far...

- -

ap_hook_post_config (this is where the old _init - routines get registered)
ap_hook_http_method (retrieve the http method from a - request. (legacy))
ap_hook_open_logs (open any specified logs)
ap_hook_auth_checker (check if the resource requires - authorization)
ap_hook_access_checker (check for module-specific - restrictions)
ap_hook_check_user_id (check the user-id and - password)
ap_hook_default_port (retrieve the default port for - the server)
ap_hook_pre_connection (do any setup required just - before processing, but after accepting)
ap_hook_process_connection (run the correct - protocol)
ap_hook_child_init (call as soon as the child is - started)
ap_hook_create_request (??)
ap_hook_fixups (last chance to modify things before - generating content)
ap_hook_handler (generate the content)
ap_hook_header_parser (let's modules look at the - headers, not used by most modules, because they use - post_read_request for this.)
ap_hook_insert_filter (to insert filters into the - filter chain)
ap_hook_log_transaction (log information about the - request)
ap_hook_optional_fn_retrieve (retrieve any functions - registered as optional)
ap_hook_post_read_request (called after reading the - request, before any other phase)
ap_hook_quick_handler (??)
ap_hook_translate_name (translate the URI into a - filename)
ap_hook_type_checker (determine and/or set the doc - type) -

- - - diff --git a/docs/manual/developer/modules.html.ja.jis b/docs/manual/developer/modules.html.ja.jis new file mode 100644 index 0000000000..ba621705f7 --- /dev/null +++ b/docs/manual/developer/modules.html.ja.jis @@ -0,0 +1,240 @@ + + + + + + + モジュールの Apache 1.3 から Apache 2.0 への移植 + + + + + + + +

モジュールを Apache 1.3 から Apache 2.0 へ

+ +

この文書は mod_mmap_static モジュールを Apache 2.0 用に移植した時に + 学んだ経験をもとに書いた、最初の手引き書です。まだまだ完全じゃないし、 + ひょっとすると間違っている部分もあるかもしれませんが、 + 取っ掛りにはなるでしょう。

+ +

簡単な変更点…

+ +

クリーンナップルーチン

+ +

クリーンナップルーチンは apr_status_t 型である必要があります。 + そして、apr_status_t 型の値を返さなくてはなりません。 + クリーンナップ中のエラーを通知する必要がなければ、返り値は普通、 + ARP_SUCCESS です。たとえエラーを通知したとしても、 + すべてのコードがその通知をチェックしたり、 + エラーに応じた動作をするわけではないことに気をつけてください。

+ +

初期化ルーチン

+ +

初期化ルーチンは処理全体から見てしっくりくるような意味を表すように、 + 名前が変更されました。ですから、mmap_init から mmap_post_config + のようにちょっと変更されました。 + 渡される引数は大幅に変更され、次のようになりました。

+ +

apr_pool_t *p,
apr_pool_t *plog,
apr_pool_t *ptemp,
server_rec *s

+ +

データ型

+ +

データ型のほとんどは APR に移されました。つまり、 + いくつかの名前が前述のように変更されています。 + 施すべき変更点の簡単な一覧を以下に示します。

+ +

pool は apr_pool_t になります
table は apr_table_t になります

+ +

もっと厄介な変更点…

+ +

フックの登録

+ +

新しいアーキテクチャでは作成した関数を呼び出すのに + 一連のフックを使用します。このフックは、新しい関数 + static void register_hooks(void) を使って登録するよう、 + モジュールに書き足さなくてはなりません。 + この関数は、なにをすべきか一旦理解してしまえば、 + 十分にわかりやすいものです。 + リクエストの処理のあるステージで呼び出さなくてはならない + 関数は登録する必要があります。ハンドラは登録する必要はありません。 + 関数を登録できるフェーズはたくさんあります。 + それぞれのフェーズで、関数を呼び出す相対的な順番は、 + かなりの程度制御できます。

+ +

以下は、mod_mmap_static に追加したコードです:

+ +

+static void register_hooks(void)
+{
+    static const char * const aszPre[]={ "http_core.c",NULL };
+    ap_hook_post_config(mmap_post_config,NULL,NULL,HOOK_MIDDLE);
+    ap_hook_translate_name(mmap_static_xlat,aszPre,NULL,HOOK_LAST);
+};
+

+ +

ここでは呼びだすべき二つの関数を登録しています。一つは + post_config ステージ用 (ほとんどすべてのモジュールはこれが必要です) で、 + もう一つは translate_name フェーズ用です。 + それぞれの関数は名前は違うけれども形式は同じであることに注意してください。 + それでは、形式はどのようになっているでしょうか?

+ +

ap_hook_[フェーズ名](関数名, 先行, 後行, 位置);

+ +

3つの位置が定義されています…

+ +

HOOK_FIRST
HOOK_MIDDLE
HOOK_LAST

+ +

位置を定義するには、上記の「位置」を指定し、 + 修飾子である「先行」と「後行」で手を加えます。 + 「先行」「後行」は、呼ばれるべき関数のリストです。 + 「先行」は関数の実行前に呼ばれるもので、 + 「後行」は実行後に呼ばれるものです。

+ +

mod_mmap_static の場合、post_config ステージでは必要ありませんが、 + mmap_static_xlat が core モジュールが名前の変換を実行した後に + 呼ばれなければなりません。 + そこで aszPre を使って HOOK_LAST の修飾子を定義しています。

+ +

モジュールの定義

+ +

モジュールの定義を作成する際に注意しなければならない + ステージの数は激減しています。古い定義は次のようになっていました。

+ +

+module MODULE_VAR_EXPORT [モジュール名]_module =
+{
+    STANDARD_MODULE_STUFF,
+    /* 初期化関数 */
+    /* ディレクトリ設定作成関数 */
+    /* ディレクトリ設定マージ関数 ― デフォルトは「上書き」 */
+    /* サーバ設定作成関数 */
+    /* サーバ設定マージ関数 */
+    /* コマンド・ハンドラ */
+    /* ハンドラ */
+    /* ファイル名変換 */
+    /* check_user_id */
+    /* 認証チェック */
+    /* アクセス制限チェック */
+    /* MIME 型チェック */
+    /* 調整 */
+    /* ログ出力 */
+    /* ヘッダパーサ */
+    /* 子プロセス初期化 */
+    /* 子プロセス終了 */
+    /* read-request 後 */
+};
+

+ +

新しい構造体はとってもシンプルです…

+ +

+module MODULE_VAR_EXPORT [モジュール名]_module =
+{
+    STANDARD20_MODULE_STUFF,
+    /* ディレクトリ毎設定構造体作成 */
+    /* ディレクトリ毎設定構造体マージ */
+    /* サーバ毎設定構造体作成 */
+    /* サーバ毎設定構造体作成マージ */
+    /* コマンド・ハンドラ */
+    /* ハンドラ */
+    /* フック登録 */
+ };
+

+ +

このうちのいくつかは古いものから新しいものに直接読み替えられるもので、 + いくつかはそうではありません。どうすればいいのかを要約してみます。

+ +

直接読み替えられるステージ:

+ +

/* ディレクトリ設定作成関数 */ ==> + /* ディレクトリ毎設定構造体作成 */
/* サーバ設定作成関数 */ ==> /* サーバ毎設定構造体作成 */
/* ディレクトリ設定マージ関数 */ ==> + /* ディレクトリ毎設定構造体マージ */
/* サーバ設定マージ関数 */ ==> + /* サーバ毎設定構造体作成マージ */
/* コマンド・テーブル */ ==> /* コマンド apr_table_t */
/* ハンドラ */ ==> /* ハンドラ */

+ +

古い関数の残りのものはフックとして登録されるべきです。 + 現時点で次のようなフック・ステージが定義されています…

+ +

ap_hook_post_config (以前の _init ルーチンが登録されるべき場所です)
ap_hook_http_method (リクエストから HTTP メソッドを取得します (互換用))
ap_hook_open_logs (特定のログのオープン)
ap_hook_auth_checker (リソースが権限を必要とするかどうかの確認)
ap_hook_access_checker (モジュール固有の制約の確認)
ap_hook_check_user_id (ユーザ ID とパスワードの確認)
ap_hook_default_port (サーバのデフォルト・ポートの取得)
ap_hook_pre_connection (処理の直前に必要なことを実行。ただし accept 直後に呼ばれる)
ap_hook_process_connection (プロトコルの処理)
ap_hook_child_init (子プロセル起動直後)
ap_hook_create_request (??)
ap_hook_fixups (応答内容の生成を変更するラスト・チャンス)
ap_hook_handler (応答内容の生成)
ap_hook_header_parser (モジュールにヘッダの照会をさせる。ほとんどのモジュールでは使われません。post_read_request を使います)
ap_hook_insert_filter (フィルタ・チェインにフィルタを挿入)
ap_hook_log_transaction (リクエストについての情報を記録する)
ap_hook_optional_fn_retrieve (オプションとして登録された関数の取得)
ap_hook_post_read_request (リクエストを読みこんだ後、他のフェーズの前に呼ばれる)
ap_hook_quick_handler (??)
ap_hook_translate_name (URI をファイル名に変換する)
ap_hook_type_checker (文書型の決定と設定。あるいはその片方)

+ + + +

From Apache 1.3 to Apache 2.0 - Modules