名前

HTTP::Lite - 軽量なHTTP実装

利用例

    use HTTP::Lite;
    $http = new HTTP::Lite;
    $req = $http->request("http://www.cpan.org/") 
        or die "Unable to get document: $!";
    print $http->body();

説明

    HTTP::LiteはPerlのための、単体で動作する、軽量なHTTP/1.1の
    実装です。これは十全の機能をもち、LWPの代わりとなって
    置き換えるようなものではありません。かわりに、HTTPをサポート
    するためにアーカイブにインストールするモジュールが最小である
    ことが好ましい状況、プロセッサが遅く、CPUにとってLWPが良い
    候補とならない状況で役立つものであろうと考えています。
    HTTP::Liteは、通常は有意にLWPより高速です。

    HTTP::LiteはCGI（やmod_perl）プログラムでの利用に、あるいは
    HTTP GETおよびPOST機能だけが不可欠なより大きなパッケージへの
    バンドルには理想的です。

    HTTP::Liteは基本的なPOSTおよびGET操作だけをサポートします。
    0.2.1では、HTTP::LiteはHTTP/1.1をサポートし、名前ベースの
    バーチャル・ホストに不可欠なHOSTヘッダーを受け入れます。
    加えて、HTTP::Liteは現在、プロキシをサポートします。

    2.0.0になり、HTTP::Liteは現在ではリクエストデータを
    受け取ってすぐに処理できるように、コールバックをサポート
    しました。これは、十分なメモリなしで巨大なファイルを
    取り扱うのに役立ちます。

    もし、FTPやHTTPSといったより以上の機能的な要求があれば、
    libwwwperl (LWP)をご覧下さい。 LWPはHTTP::Liteより実に良く、
    包括的なパッケージで、利用できるのであればHTTP::Liteの
    代わりに使うべきです。

コンストラクタ

new
HTTP::Liteのコンストラクタです。これは現在のところ引数をとりません。将来のバージョンのHTTP::Liteはパラメータを受け入れるでしょう。

メソッド

request ( $url, $data_callback, $cbargs )
指定されたURLでリクエストを初期化します。

I/Oエラーが起こるとundefが、そうでなければHTTPステータスコードが返されます。200番台のステータスコードは成功を、300は一時的なエラーを、400は恒久的なエラーを、500はサーバーエラーをあらわします。

HTTPステータスコードの詳細は http://www.w3.org/Protocols/HTTP/HTRESP.html を参照してください。

$data_callbackパラメータは、使用された場合、受信データへのフィルタや、大きな転送量をハンドルする方法になります。これは関数へのリファレンスである必要があり、この関数は以下を渡されます : callbackしたhttpリクエストインスタンスへのリファレンス、 bodyに追加されようとしているデータブロックへのリファレンス、それから$cbargsパラメータ（何かしら指定されていれば）。これは、ドキュメントのボディに追加するデータへのリファレンスか、undefのどちらかを返さなければいけません。

set_callbackが使用された場合、$data_callbackと$cbargsは使われません。 $cbargsはスカラーとリファレンスのどちらでも構いません。

data_callbackは次のように呼び出されます: &$data_callback( $self, $dataref, $cbargs )

ドキュメントをファイルに保存するための例です :
```
  # ファイルハンドル$cbargsへデータを書き出し
  sub savetofile {
    my ($self,$phase,$dataref,$cbargs) = @_;
    print $cbargs $$dataref;
    return undef;
  }
```
```
  $url = "$testpath/bigbinary.dat";
  open OUT, ">bigbinary.dat";
  $res = $http->request($url, \&savetofile, OUT);
  close OUT;
```

set_callback ( $functionref, $dataref )

リクエストの種々のステージにおいて、コールバックをリクエストの状態監視や振る舞いの変更のために使うことができます。これらの動作はrequest()への $data_callbackパラメータに似ていますが、より用途の広い(訳者注)ものです。 set_callbackはrequest()での$data_callbackを無効にします。

callbacksは次のように呼び出されます: callback ( $self, $phase, $dataref, $cbargs )

現在、次のphasesがあります:

  connect - コネクションが確立され、ヘッダーが送信されようとしています。

  content-length - 返り値がcontent-lengthとして使われます。未指定時には、
            prepare_post()が使用されている場合にはコンテンツ長は算出
            されます。

  done-headers - 全ヘッダー送信完了時点です。

  content - 返り値がコンテントとして扱われ、クライアントに送信されます。
            prepare_post()で内部的に定義されたコンテントを使用するには
            undefを返します。
            
  content-done - コンテントの転送が成功した時です。

  data - データを1ブロック分受信した時です。データは$datarefで参照
            されます。返り値として渡された参照値で、最初に渡された
            コンテントが置き換えられます。大きなドキュメントでメモリが
            使用されるのを避けるにはundefを返します。

  done - リクエスト終了時です。

※訳者注:verstaileとあったがversatileとみなして訳した。

prepare_post ( $hashref )
POSTフォームに含めるアップロードしたい値の連想配列へのリファレンスを取ります。HTTPボディを生成し、メソッドを POSTに設定します。
http11_mode ( 0 | 1 )
HTTP/1.1サポートのOn/Offを切り替えます。壊れたHTTP/1.1サーバに対応するため、デフォルトではoffです。 HTTP/1.1サポートを有効にするには、1にしてください。
add_req_header ( $header, $value )
get_req_header ( $header )
delete_req_header ( $header )
HTTPリクエストヘッダを追加、削除、または取得します。この関数はどのヘッダでも上書きを許します。現在は、HTTP::LiteモジュールによりあらかじめHost、User-Agent、Content-Type、Accept、そして Connectionが定義されます。 HostやConnection、あるいはAcceptは上書きしない方が良いでしょう。

（プロキシ）認証を提供するには、以下を使います :
```
    use HTTP::Lite;
    use MIME::Base64;
    $http = new HTTP::Lite;
    $encoded = encode_base64('username:password');
    $http->add_req_header("Authorization", $encoded);
```
注意: 現在の実装では、どのヘッダも１つのインスタンスに制限されます。
body
リモートサーバーから返されたドキュメントのボディを返します。
headers_array
リモートホストから返されたHTTPヘッダーを配列で返します。
headers_string
リモートホストから返されたHTTPヘッダーを文字列表現で返します。
get_header ( $header )
リクエストヘッダーを配列で返します。

注意: HTTPリクエストはヘッダごとのインスタンスになるような制限がありません。このため、すべてのヘッダに１つ以上のエントリが入るかもしれません。
protocol
リモートサーバから告げられたHTTPプロトコル標識を返します。これは一般に、HTTP/1.0かHTTP/1.1のどちらかです。
proxy ( $proxy_server )
次のリクエストで使用するプロキシのURLまたはホストネームです。
status
サーバから返されたHTTPステータスコードを返します。これは通常、 request()の返り値です。
status_message
サーバーから返されたステータスコードの、テキストによる記述を返します。ステータス文字列は特定のフォーマットの遵守を求められませんが、大半のHTTPサーバーは標準的な記述のセットを使います。
reset
これはHTTP::Liteハンドルを再利用する前に実行します。そうしないと、結果は不確定です。
local_addr ( $ip )
ローカルIPアドレスを明示的に選択します。0.0.0.0（デフォルト）はシステムによる選択を許します。
local_port ( $port )
ローカルポートを明示的に選択します。0（デフォルトかつ推奨）はシステムによる選択を許します。
method ( $method )
メソッドを明示的に選択します。prepare_postまたはresetを使用するとこの設定は上書きされます。通常選択できるのはGET、POST、PUT、HEADです。

例

    # CPANホームページのヘッダーとボディーを取得し、出力する
    use HTTP::Lite;
    $http = new HTTP::Lite;
    $req = $http->request("http://www.cpan.org/")
        or die "Unable to get document: $!";
    die "Request failed ($req): ".$http->status_message()
      if $req ne "200";
    @headers = $http->headers_array();
    $body = $http->body();
    foreach $header (@headers)
    {
      print "$header$CRLF";
    }
    print "$CRLF";
    print "$body$CRLF";

    # dejanews USENET検索エンジンにリクエストをポストする
    use HTTP::Lite;
    $http = new HTTP::Lite;
    %vars = (
             "QRY" => "perl",
             "ST" => "MS",
             "svcclass" => "dncurrent",
             "DBS" => "2"
            );
    $http->prepare_post(\%vars);
    $req = $http->request("http://www.deja.com/dnquery.xp")
      or die "Unable to get document: $!";
    print "req: $req\n";
    print $http->body();

未実装の機能

    - FTP
    - HTTPS (SSL)
    - Authenitcation/Authorizaton/Proxy-Authorizationは直接は
      サポートしておらず、MIME::Base64が必要です。 
    - リダイレクト（Location）は自動的に追跡されません。 
    - multipart/form-dataのPOSTは直接サポートされてはません。
      （これはファイルアップロードには不可欠です）

バグ

    正しく動作しないHTTP/1.1サーバーはファイル転送時に、不正確な
    サイズを送ります。HTTP/1.1モードは現在、デフォルトでは無効に
    してあります。

作者

Roy Hooper <rhooper@thetoybox.org>

参照

LWP RFC 2068 - HTTP/1.1 -http://www.w3.org/

著作権

このプログラムはフリーウェアです; Perlそれ自体と同じ文言の元で改変と/あるいは再配布を行うことができます。

翻訳者

塚本牧生 <walrus@digit.que.ne.jp>