<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE manualpage SYSTEM "./style/manualpage.dtd">
<?xml-stylesheet type="text/xsl" href="./style/manual.ja.xsl"?>
<!-- English Revision: 1334033:1673563 (outdated) -->

<!--
 Licensed to the Apache Software Foundation (ASF) under one or more
 contributor license agreements.  See the NOTICE file distributed with
 this work for additional information regarding copyright ownership.
 The ASF licenses this file to You under the Apache License, Version 2.0
 (the "License"); you may not use this file except in compliance with
 the License.  You may obtain a copy of the License at

     http://www.apache.org/licenses/LICENSE-2.0

 Unless required by applicable law or agreed to in writing, software
 distributed under the License is distributed on an "AS IS" BASIS,
 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 See the License for the specific language governing permissions and
 limitations under the License.
-->

<manualpage metafile="handler.xml.meta">

  <title>Apache のハンドラの使用</title>

  <summary>
    <p>Apache のハンドラの使用に関して記述しています。</p>
  </summary>

  <section id="definition">
    <title>ハンドラとは</title>
    <related>
      <modulelist>
        <module>mod_actions</module>
        <module>mod_asis</module>
        <module>mod_cgi</module>
        <module>mod_imagemap</module>
        <module>mod_info</module>
        <module>mod_mime</module>
        <module>mod_negotiation</module>
        <module>mod_status</module>
     </modulelist>
      <directivelist>
        <directive module="mod_actions">Action</directive>
        <directive module="mod_mime">AddHandler</directive>
        <directive module="mod_mime">RemoveHandler</directive>
        <directive module="core">SetHandler</directive>
      </directivelist>
    </related>


    <p>「ハンドラ」とは、ファイルが呼ばれたときに実行される動作の
    Apache における内部表現です。
    通常、ファイルはファイルタイプ<transnote>MIME-type</transnote
    >に基づいた暗黙のハンドラがあります。
    普通はすべてのファイルは単にサーバに扱われますが、
    ファイルタイプの中には別に「ハンドル」<transnote>扱う</transnote>
    されるものもあります。</p>

    <p>ファイルの拡張子や置いている場所に基づいてファイルタイプと関係なく、
    ハンドラを明示的に設定することもできます。
    これはより優雅な解決法という点と、ファイルにタイプ<strong>と</strong
    >ハンドラの両方を関連付けることができるという点で優れています。
    (<a href="mod/mod_mime.html#multipleext"
    >複数の拡張子のあるファイル</a>も参照してください)。</p>

    <p>ハンドラはサーバに組み込んだり、モジュールとして含めたり、
    <directive module="mod_actions">Action</directive>
    ディレクティブとして追加したりすることができます。
    以下は標準配布に組み込まれているハンドラです。
    </p>

    <ul>
      <li><strong>default-handler</strong>:<code>default_handelr()</code>
      を使ってファイルを送ります。
      静的なコンテンツを扱うときにデフォルトで使用されるハンドラです。
      (<module>core</module>)</li>

      <li><strong>send-as-is</strong>:
      HTTP ヘッダのあるファイルをそのまま送ります。
      (<module>mod_asis</module>)</li>

      <li><strong>cgi-script</strong>: ファイルを CGI
      スクリプトとして扱います。
      (<module>mod_cgi</module>)</li>

      <li><strong>imap-file</strong>:
      イメージマップのルールファイルとして解析します。
      (<module>mod_imagemap</module>)</li>

      <li><strong>server-info</strong>: サーバの設定情報を取得します。
      (<module>mod_info</module>)</li>

      <li><strong>server-status</strong>: サーバの状態報告を取得します。
      (<module>mod_status</module>)</li>

      <li><strong>type-map</strong>:
      コンテントネゴシエーションのためのタイプマップとして解析します。
      (<module>mod_negotiation</module>)</li>
    </ul>
  </section>
  <section id="examples">
    <title>例</title>

    <section id="example1">
      <title>CGI スクリプトを用いて静的なコンテンツを変更する</title>

      <p>以下のディレクティブによって、拡張子が <code>html</code>
      であるファイルは <code>footer.pl</code>
      CGI スクリプトを起動するようになります。</p>

      <highlight language="config">
Action add-footer /cgi-bin/footer.pl
AddHandler add-footer .html
      </highlight>

      <p>CGI スクリプトは希望の修正や追加を行なって、元々要求された文書
      (環境変数 <code>PATH_TRANSLATED</code>
      で指されています) を送る責任があります。
      </p>

    </section>
    <section id="example2">
      <title>HTTP ヘッダのあるファイル</title>

      <p>以下のディレクティブは <code>send-as-is</code>
      ハンドラを使用するように指示します。このハンドラは自分自身の HTTP
      ヘッダを持っているファイルに使用されます。ここでは、拡張子に関わらず、
      <code>/web/htdocs/asis</code> ディレクトリにある全てのファイルは
      <code>send-as-is</code> ハンドラによって扱われます。</p>

      <highlight language="config">
&lt;Directory /web/htdocs/asis&gt;
    SetHandler send-as-is
&lt;/Directory&gt;
      </highlight>

    </section>
  </section>
  <section id="programmer">
    <title>プログラマ向けのメモ</title>

    <p>ハンドラの機能を実装するために、利用すると便利かもしれないものが
    <a href="developer/API.html">Apache API</a>
    に追加されました。詳しく言うと、<code>request_rec</code>
    構造体に新しいレコードが追加されたということです。</p>

    <highlight language="c">
      char *handler
    </highlight>

    <p>もしモジュールがハンドラに関わりたい場合、
    やらなければならないことは、リクエストが <code>invoke_handler</code>
    ステージに達する以前に <code>r-&gt;handler</code>
    を設定することだけです。ハンドラはコンテントタイプの代わりに
    ハンドラ名を使うようになっていること以外は、以前と同じように実装されています。
    必ず要求されているわけではありませんが、メディアタイプ
    の名前空間を侵さないように、ハンドラの名前にはスラッシュを含まない、
    ダッシュ<transnote>"-"</transnote>で分離された名前を付ける習慣になっています。</p>
  </section>
</manualpage>
