=encoding utf8

=head1 NAME

CGI::Upload - ブラウザ・ファイル・アップロードをハンドリングするためのCGIクラス

=head1 SYNOPSIS

 use CGI::Upload;

 my $upload = CGI::Upload->new;

 my $file_name = $upload->file_name('field');
 my $file_type = $upload->file_type('field');

 $upload->mime_magic('/path/to/mime.types');
 my $mime_type = $upload->mime_type('field');

 my $file_handle = $upload->file_handle('field');

=head1 DESCRIPTION

このモジュールは、Webブラウザを介したmultipart/form-dataリクエスト中のアップロードされたファイルを扱う簡単で安全な作法を提供するために書かれています。このモジュールの、既存モジュールに対する第一の利点は、アップロードされたファイルに対してもっとも頻繁に必要とされる情報を提供する、作法に沿ったシングル・インターフェースです。

このモジュールはB<CGI>とB<File::MMagic>モジュール上に組み上げられ、multipart/form-dataリクエストによりアップロードされたファイルのハンドリングのためのきちんとした簡潔なメソッドを提供します。

=head1 METHODS

CGIスクリプト中で、以下のメソッドをこのモジュールを介して利用することができ、リクエストに応じて呼び出し名前空間にエクスポートすることができます。

=over 4

=item B<new>

新しいB<CGI::Upload>オブジェクトを生成して返すオブジェクト・コンストラクタ・メソッドです。B<CGI::Upload>の以前のバージョンでは、使用されるB<CGI>オブジェクトは必須の引数として要求されました。これはB<CGI>オブジェクトのシングルトンの自然性から、必要ではなくなりました。

実験的に、現在、CGI.pmライクな任意のモジュールを使用できます。要求事項は、->paramメソッドと、ファイルハンドルを返す->uploadメソッドをサポートすることです。この機能は、モジュール名を与えるか、既存のオブジェクトを与える二通りの方法で使えます。定型的な場合、CGI::UploadはそのモジュールのI<require>を試み、モジュールをロードできなかった時はI<croak>します。これはCGI.pmとCGI::Simpleでテストされました。

テストはCGI::Simpleの0.075版で行いました。

0.071版のCGI::Simpleでは壊れることが知られていますので、そのケースでは自らdieするように関連付けています。

Examples:

 use CGI::Upload;
 CGI::Upload->new({ query => "CGI::Simple"});

or

 use CGI::Upload;
 use CGI::Simple;
 $CGI::Simple::DISABLE_UPLOADS = 0;   # これはインスタンス生成前にセットする必要があります
 my $q = new CGI::Simple;
 CGI::Upload->new({ query => $q});

=item B<query>

B<CGI::Upload>クラスで使用されるB<CGI>オブジェクトを返します。

=item B<file_handle('field')>

このメソッドは、'field'という名前のフォーム・インプット・フィールドからアップロードされたファイルが格納された一時ファイルの、ファイルハンドルを返します。この一時ファイルは可能であれば、本質的には無名でB<IO::File>のB<new_tmpfile>メソッドを使って生成されます。

=item B<file_name('field')>

このメソッドは、'field'という名前のフォーム・インプット・フィールドからアップロードされたファイルのファイル名を返します - このファイル名はアップロードされたファイルのローカルの一時ファイル名ではなく、クライアント・ウェブ・ブラウザから与えられたファイル名を反映したものです。

=item B<file_type('field')>

このメソッドは、アップロードされたファイルのファイルタイプを、ファイル名の拡張子から特定して返します - これは必ずしもアップロードされたファイルの本質を反映していないことには注意が必要ですが、CGIスクリプトがとりあえずアップロードされたファイルのファイルタイプでのバリデーションを行うことができるでしょう。

=item B<mime_magic('/path/to/mime.types')>

このメソッドは、B<mime_type>メソッドでファイルを識別するのに使われる、外部のmagic mime typesファイルを（セットして）返します。デフォルトでは、MIME識別はB<File::MMagic>で定義された内部mime typesに基づいて行われます。

See L<File::MMagic> for further details.

=item B<mime_type('field')>

このメソッドは、MIMEタイプ
このメソッドは、'field'という名前のフォーム・インプット・フィールドからアップロードされたファイルのMIMEタイプを、ファイルのマジック・ナンバーを元に特定して返します。アップロードされたファイルの内容でバリデートするという意味でこれがベストです。

この詳細はL<File::MMagic>を参照してください。

=back

=head1 BUGS

バグはRTに報告してください: L<http://rt.cpan.org/NoAuth/Bugs.html?Dist=CGI-Upload>

=head1 TODO

なぜテスト・カバレッジが100%ではないのか説明する...

より良いMIMEマジックサポートの追加（RT上のリクエストを参照）

複数ファイルアップロードのサポート状況のテストと、問題があればFix

Apache::Requestのサポート

CGI::Minimalのサポート

Mark Stosbergによるコードの例 (CGI::Uploader):

  if ($q->isa('CGI::Simple') ) {
           $fh = $q->upload($filename); 
           $mt = $q->upload_info($filename, 'mime' );

           if (!$fh && $q->cgi_error) {
                   warn $q->cgi_error && return undef;
           }
   }
   elsif ( $q->isa('Apache::Request') ) {
            my $upload = $q->upload($file_field);
                $fh = $upload->fh;
                $mt = $upload->type;
   }
   # default to CGI.pm behavior
   else {
           $fh = $q->upload($file_field);
           $mt = $q->uploadInfo($fh)->{'Content-Type'} if $q->uploadInfo($fh);

           if (!$fh && $q->cgi_error) {
                   warn $q->cgi_error && return undef;
           }
   }


=head1 SEE ALSO

L<CGI>, L<File::MMagic>, L<HTTP::File>


=head1 COPYRIGHT

Copyright 2002-2004, Rob Casey, rob.casey@bluebottle.com

=head1 AUTHOR

Original author: Rob Casey, rob.casey@bluebottle.com 

Current mainainer: Gabor Szabo, gabor@pti.co.il

Thanks to

Mark Stosberg for suggestions.

and to the CPAN Testers for testing.

=head1 LICENSE

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

=head1 DOCUMENT TRANSLATION

Makio Tsukamoto, tsukamoto@gmail.com

=cut