名前¶

HTTP::Cookies - クッキー容器

概要¶

  use HTTP::Cookies;
  $cookie_jar = HTTP::Cookies->new(
    file => "$ENV{'HOME'}/lwp_cookies.dat',
    autosave => 1,
  );

  use LWP;
  my $browser = LWP::UserAgent->new;
  $browser->cookie_jar($cookie_jar);

あるいは、空の容器や一時的クッキー容器の場合は:

  use LWP;
  my $browser = LWP::UserAgent->new;
  $browser->cookie_jar( {} );

説明¶

このクラスは、「クッキー容器」-- これは、与えられた LWP::UserAgent オブジェクトが知っている全ての HTTP クッキーのデータベース -- を表現するためのオブジェクトのためのものです。

クッキー (Cookie) は、サーバー側の接続が接続のクライアント側に情報を格納し、 取り出すという両方が出来る一般的な機能です。 クッキーについてのさらなる情報は <URL:http://wp.netscape.com/newsref/std/cookie_spec.html> と <URL:http://www.cookiecentral.com/> をご覧下さい。 このモジュールは RFC 2965 で記述されている新しい形式のクッキーも実装します。 クッキーの二つの変数は幸せに共存できるものと想定されます。

HTTP::Cookies クラスのインスタンスは Set-Cookie2: と Set-Cookie: ヘッダの集まりを格納することができ、この情報を HTTP::Request オブジェクトの Cookie ヘッダを初期化するために 使うことが出来ます。 HTTP::Cookies オブジェクトの状態はファイルに格納でき、ファイルから 取得することができます。

メソッド¶

以下のメソッドが提供されます:

$cookie_jar = HTTP::Cookies->new

The constructor takes hash style parameters. The following parameters are recognized:

コンストラクタはハッシュ形式のパラメータを取ります。 以下のパラメータが理解されます:

  file:            name of the file to restore cookies from and save cookies to
  autosave:        save during destruction (bool)
  ignore_discard:  save even cookies that are requested to be discarded (bool)
  hide_cookie2:    do not add Cookie2 header to requests

  file:            クッキーが取り出され、保存されるファイルの名前
  autosave:        オブジェクトのデストラクション処理中に保存する (bool) 
  ignore_discard:  廃棄するように要求されたクッキーであっても保存する (bool) 
  hide_cookie2:    リクエストに Cookie2 ヘッダを追加しない

Future parameters might include (not yet implemented):

将来以下のパラメータが入ります (まだ実装されていません):

  max_cookies               300
  max_cookies_per_domain    20
  max_cookie_size           4096

  no_cookies   list of domain names that we never return cookies to

$cookie_jar->add_cookie_header( $request )

The add_cookie_header() method will set the appropriate Cookie:-header for the HTTP::Request object given as argument. The $request must have a valid url attribute before this method is called.

add_cookie_header() メソッドは適切な Cookie:-ヘッダ を引数として 与えられた HTTP::Request オブジェクトに設定します。 このメソッドが呼ばれる前に、$request は適切な url 属性を 持たなければなりません。

$cookie_jar->extract_cookies( $response )

The extract_cookies() method will look for Set-Cookie: and Set-Cookie2: headers in the HTTP::Response object passed as argument. Any of these headers that are found are used to update the state of the $cookie_jar.

extract_cookies() メソッドは Set-Cookie: と Set-Cookie2: を引数として 渡された HTTP::Response から探します。 見つかったこれらのヘッダはすべて、$cookie_jar の状態を更新するために 使われます。

$cookie_jar->set_cookie( $version, $key, $val, $path, $domain, $port, $path_spec, $secure, $maxage, $discard, \%rest )

The set_cookie() method updates the state of the $cookie_jar. The $key, $val, $domain, $port and $path arguments are strings. The $path_spec, $secure, $discard arguments are boolean values. The $maxage value is a number indicating number of seconds that this cookie will live. A value <= 0 will delete this cookie. %rest defines various other attributes like "Comment" and "CommentURL".

set_cookie() メソッドは $cookie_jar の状態を更新します。 $key, $val, $domain, $port, $path 引数は文字列です。 $path_spec, $secure, $discard 引数はブール値です。 $maxage はこのクッキーが生きている秒数を示します。 値が <=0 はこのクッキーを削除します。 %rest は "Comment" や "CommentURL" のような他の様々な属性を定義します。

$cookie_jar->save

$cookie_jar->save( $file )

This method file saves the state of the $cookie_jar to a file. The state can then be restored later using the load() method. If a filename is not specified we will use the name specified during construction. If the attribute ignore_discard is set, then we will even save cookies that are marked to be discarded.

このメソッドは $cookie_jar の状態をファイルに保存します。 この状態は load() メソッドを使って取り出すことが出来ます。 もしファイル名が指定されなければ、コンストラクタで指定された 名前を使用します。 属性 ignore_discared が設定されれば、廃棄するように印のついた クッキーも保存します。

The default is to save a sequence of "Set-Cookie3" lines. "Set-Cookie3" is a proprietary LWP format, not known to be compatible with any browser. The HTTP::Cookies::Netscape sub-class can be used to save in a format compatible with Netscape.

デフォルトは "Set-Cookie3" の行の並びを保存します。 "Set-Cookie3" は LWP 専用のフォーマットです、他のブラウザとの互換性は 分かりません。 HTTP::Cookies::Netscape サブクラスは Netscape と互換性のある フォーマットで保存するために使われます。

$cookie_jar->load

$cookie_jar->load( $file )

This method reads the cookies from the file and adds them to the $cookie_jar. The file must be in the format written by the save() method.

このメソッドはファイルからクッキーを読みこみ、$cookie_jar に追加します。 ファイルは save() メソッドにより書かれたフォーマットでなければなりません。

$cookie_jar->revert

This method empties the $cookie_jar and re-loads the $cookie_jar from the last save file.

このメソッドは $cookie_jar を空とし、最後に保存したファイルから $cookie_jar をリロードします。

$cookie_jar->clear

$cookie_jar->clear( $domain )

$cookie_jar->clear( $domain, $path )

$cookie_jar->clear( $domain, $path, $key )

Invoking this method without arguments will empty the whole $cookie_jar. If given a single argument only cookies belonging to that domain will be removed. If given two arguments, cookies belonging to the specified path within that domain are removed. If given three arguments, then the cookie with the specified key, path and domain is removed.

引数無しでこのメソッドを呼び出すと $cookie_jar 全体を空にします。 もし一つの引数だけが与えられれば、そのドメインに所属するクッキーだけが 削除されます。 引数が二つ与えられると、指定されたドメインにあるそのパスに所属する クッキーだけが削除されます。 三つの引数が与えられると指定されたキー、パスそしてドメインをもつ クッキーが削除されます。

$cookie_jar->clear_temporary_cookies

Discard all temporary cookies. Scans for all cookies in the jar with either no expire field or a true discard flag. To be called when the user agent shuts down according to RFC 2965.

全ての一時的クッキーを破棄します。 容器の中から、有効期限フィールドがないか、discard フラグが真の クッキーを探します。 RFC 2965 によれば、ユーザーエージェントがシャットダウンするときに 呼び出されます。

$cookie_jar->scan( \&callback )

The argument is a subroutine that will be invoked for each cookie stored in the $cookie_jar. The subroutine will be invoked with the following arguments:

引数はクッキーが $cookie_jar に格納されるたびに呼び出される サブルーチンです。 サブルーチンは以下の引数で呼び出されます:

  0  version
  1  key
  2  val
  3  path
  4  domain
  5  port
  6  path_spec
  7  secure
  8  expires
  9  discard
 10  hash

  0  バージョン (version)
  1  キー (key) 
  2  値 (val) 
  3  パス (path) 
  4  ドメイン (domain) 
  5  ポート (port) 
  6  パス指定 (path_spec) 
  7  セキュリティ (secure) 
  8  終了 (expires) 
  9  廃棄 (discard) 
 10  ハッシュ (hash) 

$cookie_jar->as_string

$cookie_jar->as_string( $skip_discardables )

The as_string() method will return the state of the $cookie_jar represented as a sequence of "Set-Cookie3" header lines separated by "\n". If $skip_discardables is TRUE, it will not return lines for cookies with the Discard attribute.

as_string() メソッドは "\n" で区切られた "Set-Cookie3" ヘッダ行の並びで 表された $cookie_jar の状態を返します。 $skip_discard が TRUE であれば、Discard 属性を持ったクッキーのための行は 返しません。

SEE ALSO¶

HTTP::Cookies::Netscape, HTTP::Cookies::Microsoft

コピーライト¶

Copyright 1997-2002 Gisle Aas

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