libapreq-1.0 > Apache::Request
libapreq-1.0
CPANで確認する
Source
編集

名前

Apache::Request - クライアントからのリクエストを扱う

概要

    use Apache::Request ();
    my $apr = Apache::Request->new($r);

説明

Apache::Request は Apache クラスのサブクラスであり、Content-type が application/x-www-form-urlencoded もしくは multipart/form-data の GET リクエスト、 POST リクエストをパースします。 詳細は libapreq(3) を参照して下さい。

Apache::Request METHODS

インターフェースは CGI.pm のパラメーター解析ルーチンを模倣してデザイン されています。 主な違いとしては

  • Apache::Request::new は Apache オブジェクトを(二番目の)引数としてとります。

  • クエリーパラメータは Apache::Table オブジェクトとして保持され、大文字小文字を区別しないキーを使用してパースされます。

  • -attr => $val スタイルの引数はサポートされてません。

  • たとえ POST リクエストであってもクエリーストリングは常にパースされます。

new

新しい Apache::Request オブジェクトを Apache request_rec オブジェクトより生成します。

    my $apr = Apache::Request->new($r);

Apache クラスの全てのメソッドは継承されます。

以下の引数がオプションとして使用出来ます。

POST_MAX

POST データのサイズを制限します(バイト単位です)。 制限に達した場合 Apache::Request::parse メソッドはエラーコードを返します。

 my $apr = Apache::Request->new($r, POST_MAX => 1024);
 my $status = $apr->parse;

 if ($status) {
     my $errmsg = $apr->notes("error-notes");
     ...
     return $status;
 }
DISABLE_UPLOADS

ファイルアップロードを禁止します。 ファイルアップロードが行なわれようとした場合 Apache::Request::parse メソッドはエラーコードを返します。

 my $apr = Apache::Request->new($r, DISABLE_UPLOADS => 1);
 my $status = $apr->parse;

 if ($status) {
     my $errmsg = $apr->notes("error-notes");
     ...
     return $status;
 }
TEMP_DIR

アップロードされたファイルがスプールされるディレクトリを設定します。 *nix 系の link(2) システムコールをサポートした OS においては TEMP_DIR は最終的に保存するファイルと同じファイルシステム上に無ければいけません。

 my $apr = Apache::Request->new($r, TEMP_DIR => "/home/httpd/tmp");
 my $upload = $apr->upload('file');
 $upload->link("/home/user/myfile") || warn "link failed: $!";
HOOK_DATA

付加的な設定情報をアップロードフックに渡します。 次に記された UPLOAD_HOOK の説明を見て下さい。

UPLOAD_HOOK

ファイルアップロードされたデータが読まれる際に常に走るコールバックを設定します。 このコールバックはアップロードの進行状況メーターを提供するのに使用出来ます。 Apache はフックの終了後も自動的に $upload->fh にデータを書き込み続けます。

 my $transparent_hook = sub {
   my ($upload, $buf, $len, $hook_data) = @_;
   warn "$hook_data: got $len bytes for " . $upload->name;
 };

 my $apr = Apache::Request->new($r, 
                                HOOK_DATA => "Note",
                                UPLOAD_HOOK => $transparent_hook,
                               );
 $apr->parse;

instance

instance() クラスメソッドにより Apache::Request をシングルトン化する事が出来ます。 つまり、Apache::Request->instance() を一回のリクエスト中で呼び出す限り、 常に同じインスタンスを取得する事が出来ます。 これにより、同じリクエスト中で Apache::Request オブジェクトを二回生成 する際の問題を解決します。 問題の症状として、二つ目の Apache::Request オブジェクトでは既にパラメータが読みこみ、解析されているためパラメータを含まないでしょう。

  my $apr = Apache::Request->instance($r, DISABLE_UPLOADS => 1);

instance() は new() と同じ引数を受けとって呼びだされますが、一つの リクエスト中で最初に呼ばれたときのみ、引数は意味を持つという事を気にと めておいて下さい。 任意の引数は同じリクエスト中において、後で instance() が呼びだされた際には無視されます。

サブリクエストは instance() メソッドが呼ばれた場合、新しい Apache::Request オブジェクトを受けとります。親リクエストの Apache::Request オブジェクトは サブリクエストにコピーされません。

また、instance() メソッドを使用しているときに parse() メソッドを使 うのは得策ではありません。なぜなら結局二度呼んでしまうかもしれませんし、 何も無かったといってエラーを検知するかもしれません。

parse

parse メソッドは実際のリクエストの解析を行ないます。 このメソッドはアクセサメソッドによって呼ばれるため必須ではありませんが エラーが発生した際によりユーザーフレンドリーなメッセージを提供する事に 有用です。

    my $r = shift;
    my $apr = Apache::Request->new($r); 
 
    my $status = $apr->parse; 
    unless ($status == OK) { 
        $apr->custom_response($status, $apr->notes("error-notes")); 
        return $status; 
    }

param

リクエストのパラメータを CGI::param のオブジェクト指向的インターフェースに 似た方法で取得もしくは設定します。(大文字小文字を区別しないキーを使用します) CGI.pm と違い Apache::Request の param メソッドはとても早く、mod_perl 組み込み の Apache->args メソッドよりも高速です。 しかし, CGI.pm の -attr => $val スタイルの引数はサポートしていません。

    # CGI.pm と同じです。

    my $value = $apr->param('foo');
    my @values = $apr->param('foo');
    my @params = $apr->param;

    # 下記は CGI.pm と少し違います。

    # foo に複数の値を設定する。
    $apr->param('foo' => [qw(one two three)]);

    # Apache::Teable オブジェクトへの参照を返します。
    my $table = $apr->param; # $apr->parms と同じです。- 下記参照

parms

Apache::Requet オブジェクトの基本のパラメータテーブルを 取得もしくは設定します。 引数無しで呼びだされた場合、parms は Apache::Request オブジェクトのパラメータテーブルに結びつけられた Apache::Table オブジェクトを返します。 Apache::Table の参照を引数として呼ばれた場合、Apache::Request オブジェクトのパラメータテーブルは引数として渡されたテーブルで置きかえられます。

   # $apache_table は Apache::Table オブジェクトを参照しています。
   $apr->parms($apache_table); # $apr のパラメータテーブルを設定

   # $apache_table によって提供された Apache::Table オジェクトの参照を返す。
   my $table = $apr->parms;

upload

スカラーコンテキストの際は一つの、リストコンテキストの際は全ての Apache::Upload オブジェクトを返します。

    my $upload = $apr->upload;
    my $fh = $upload->fh;
    my $lines = 0; 
    while(<$fh>) { 
        ++$lines; 
        ...
    }

付加的な name パラメータを渡して、その名前に関連づいたApache::Upload オブジェクトのみを取得出来ます。

    my $upload = $apr->upload($name);

Apache::Upload METHODS

name

filefield のパラメータ名:

    my $name = $upload->name;

filename

アップロードされたファイルのファイル名:

    my $filename = $upload->filename;

fh

アップロードされたファイルを差すファイルハンドル:

    my $fh = $upload->fh;
    while (<$fh>) {
        ...
    }

size

ファイルサイズをバイトで表わす:

    my $size = $upload->size;

info

アップロードされたファイルの付加的なヘッダ情報 Apache::Table クラスに結びつけられたハッシュリファレンスを返します。 任意の key 引数により、ハッシュリファレンスでは無く、値が返されます。

例:

    my $info = $upload->info;
    while (my($key, $val) = each %$info) {
        ...
    }

    my $val = $upload->info("Content-type");

type

Apache::Upload オブジェクトの Content-Type を返します。

    my $type = $upload->type;
    #same as
    my $type = $upload->info("Content-Type");

next

Upload オブジェクトは libapreq では linked list として実装されています。 next メソッドは Apache::Request upload メソッドをリストコンテキ ストで使用する方法の代替となります。

    for (my $upload = $apr->upload; $upload; $upload = $upload->next) {
        ...
    }

    # 機能としては以下と同じです。

    for my $upload ($apr->upload) {
        ...
    }

tempname

スプールファイルの名前を提供します。 このメソッドはデバッグ用に実装されており、将来のバージョンの Apache::Request では変更される可能性があります。

*nix 系のシステムにおいて、スプールファイルの再コピーを避けるために ハードリンクを作成します。

  my $upload = $apr->upload('file');
  $upload->link("/path/to/newfile") or
      die sprintf "link from '%s' failed: $!", $upload->tempname;

一般に新しい名前のファイルはスプールファイルと同じファイルシステム 上にある必要があります。 詳細についてはあなたのシステムの link(2) を参照して下さい。

SEE ALSO

libapreq(3), Apache::Table(3)

CREDITS

インターフェースは Lincoln Stein による pure Perl バージョンを基にしている。

作者

Doug MacEachern, updated for v1.0 by Joe Schaefer

Powered by Amon2, 翻訳, サイト. Operated by Japan Perl Association