Net-SSLeay-1.20/SSLeay/Handle.pod


=encoding euc-jp

=head1 NAME

=begin original

Net::SSLeay::Handle - Perl module that lets SSL (HTTPS) sockets be
handled as standard file handles.

=end original

Net::SSLeay::Handle - SSL (HTTPS)ソケットを標準のファイルハンドルとして
扱わせるPerlモジュール

=head1 SYNOPSIS

  use Net::SSLeay::Handle qw/shutdown/;
  my ($host, $port) = ("localhost", 443);

  tie(*SSL, "Net::SSLeay::Handle", $host, $port);

  print SSL "GET / HTTP/1.0\r\n";
  shutdown(\*SSL, 1);
  print while (<SSL>);
  close SSL;                                                       
  

=head1 DESCRIPTION

=begin original

Net::SSLeay::Handle allows you to request and receive HTTPS web pages
using "old-fashion" file handles as in:

=end original

Net::SSLeay::HandleはHTTPS webページを"昔ながらの"ファイルハンドルを
使って以下のように、リクエストしたり、受け取ることを可能にします:

    print SSL "GET / HTTP/1.0\r\n";

=begin original

and

=end original

そして

    print while (<SSL>);

=begin original

If you export the shutdown routine, then the only extra code that
you need to add to your program is the tie function as in:

=end original

shutdownルーチンをエクスポートすると、あなたのプログラムに追加する
必要がある特別なコードは、以下のようなtie関数だけになります:

    my $socket;
    if ($scheme eq "https") {
        tie(*S2, "Net::SSLeay::Handle", host, $port);
        $socket = \*S2;
    else {
        $socket = Net::SSLeay::Handle->make_socket(host, $port);
    }
    print $socket $request_headers;
    ... 

=head2 USING EXISTING SOCKETS

(既存のソケットを利用する)

=begin original

One of the motivations for writing this module was to avoid
duplicating socket creation code (which is mostly error handling).
The calls to tie() above where it is passed a $host and $port is
provided for convenience testing.  If you already have a socket
connected to the right host and port, S1, then you can do something
like:

=end original

このモジュールを作った動機の一つは、ソケットを作るコードが重複する
ことを避けることでした(そのほとんどはエラーの取り扱いになります)。
上記の$hostと$portが渡されるところでtie()を呼び出すことは、
便宜上、テストのために提供されています。正しいホストとポートに
接続されたソケットS1を既に持っているのであれば、以下のように
することができます:

    my $socket \*S1;
    if ($scheme eq "https") {
        tie(*S2, "Net::SSLeay::Handle", $socket);
        $socket = \*S2;
    }
    my $last_sel = select($socket); $| = 1; select($last_sel);
    print $socket $request_headers;
    ... 

=begin original

Note: As far as I know you must be careful with the globs in the tie()
function.  The first parameter must be a glob (*SOMETHING) and the
last parameter must be a reference to a glob (\*SOMETHING_ELSE) or a
scaler that was assigned to a reference to a glob (as in the example
above)

=end original

注意: 私が知る限り、tie()関数ではグロブの取り扱いには注意しなければ
なりません。最初のパラメータはグロブ(*SOMETHING)でなければなりません。
そして最後のパラメータはグロブへのリファレンス(\*SOMETHING_ELSE)あるいは
(上記の例のように)グロブへのリファレンスが代入されたスカラーでなければ
なりません。

=begin original

Also, the two globs must be different.  When I tried to use the same
glob, I got a core dump.

=end original

また2つのグロブは違うものでなければなりません。私が同じグロブを使おうと
したときには、コアダンプになりました。

=head2 EXPORT

=begin original

None by default.

=end original

デフォルトでは何もありません。

=begin original

You can export the shutdown() function.

=end original

shutodown()関数をエクスポートすることができます。

=begin original

It is suggested that you do export shutdown() or use the fully
qualified Net::SSLeay::Handle::shutdown() function to shutdown SSL
sockets.  It should be smart enough to distinguish between SSL and
non-SSL sockets and do the right thing.

=end original

SSLソケットをシャットダウンするためには、shutdown()をエスクポートするか、
完全に修飾されたNet::SSLeay::Handle::shutdown()関数を使うことを提案します。
SSLと非SSLソケットを区別し、正しいことを行うのに十分スマートです。

=head1 EXAMPLES

  use Net::SSLeay::Handle qw/shutdown/;
  my ($host, $port) = ("localhost", 443);

  tie(*SSL, "Net::SSLeay::Handle", $host, $port);

  print SSL "GET / HTTP/1.0\r\n";
  shutdown(\*SSL, 1);
  print while (<SSL>);
  close SSL; 

=head1 TODO

=begin original

Better error handling.  Callback routine?

=end original

よりよいエラーの取り扱い、コールバックルーチン？

=head1 CAVEATS

=begin original

Tying to a file handle is a little tricky (for me at least).

=end original

ファイルハンドルを使おうとすることは少しトリッキーです(少なくとも私にとっては）。

=begin original

The first parameter to tie() must be a glob (*SOMETHING) and the last
parameter must be a reference to a glob (\*SOMETHING_ELSE) or a scaler
that was assigned to a reference to a glob ($s = \*SOMETHING_ELSE).
Also, the two globs must be different.  When I tried to use the same
glob, I got a core dump.

=end original

tie()への最初のパラメータはグロブ(*SOMETHING)で、最後のパラメータは
グロブへのリファレンス(\*SOMETHING_ELSE)か、グロブへのリファレンスが
代入されたスカラー($s = \*SOMETHING_ELSE)でなければなりません。
また2つのグロブは違うものでなければなりません。私が同じグロブを使おうと
したときには、コアダンプになりました。

=begin original

I was able to associate attributes to globs created by this module
(like *SSL above) by making a hash of hashes keyed by the file head1.

=end original

ファイルヘッド1によりキーが付けられたハッシュのハッシュを作ることにより、
このモジュールにより作成されたグロブに属性を関連付けることができました
(上記の*SSLのように)。

=begin original

Support for old perls may not be 100%. If in trouble try 5.6.0 or
newer.

=end original

古いperlのサポートは100%ではないかもしれません。障害時には5.6.0以上を
お試しください。

=head1 CHANGES

=begin original

Please see Net-SSLeay-Handle-0.50/Changes file.

=end original

Net-SSLeay-Handle-0.50/Changesファイルをご覧ください。

=head1 KNOWN BUGS

=begin original

If you let this module construct sockets for you with Perl versions
below v.5.6 then there is a slight memory leak.  Other upgrade your
Perl, or create the sockets yourself.  The leak was created to let
these older versions of Perl access more than one Handle at a time.

=end original

Perlバージョンv5.6以前で、このモジュールにあなた用のソケットを作る
よう命令すると、少しメモリリークを起こします。Perlをアップグレードするか、
あなた自身でソケットを作成してください。そのリークは、これらの古い
バージョンのPerlに同時に1つ以上のハンドルにアクセスさせるために
作られます。

=head1 AUTHOR

Jim Bowlin jbowlin@linklint.org

=head1 SEE ALSO

Net::SSLeay, perl(1), http://openssl.org/

=cut
