=encoding utf-8

=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;
    ... 

=cut

=head1 FUNCTIONS

(関数)

=over

=item shutdown

  shutdown(\*SOCKET, $mode)

=begin original

Calls to the main shutdown() don't work with tied sockets created with this
module.  This shutdown should be able to distinquish between tied and untied
sockets and do the right thing.

=end original

メインの shutdown() は、このモジュールで作成した tie された
ソケットに対しては正しく動作しません。
この shutdown は tie されたソケットとそれ以外を区別し、
正しいことをします。

=cut

=item debug

  my $debug = Net::SSLeay::Handle->debug()
  Net::SSLeay::Handle->debug(1)

=begin original

Get/set debuging mode. Always returns the debug value before the function call.
if an additional argument is given the debug option will be set to this value.

=end original

デバッグモードを取得/設定する。
常に、関数呼び出しの前のデバッグモードを返します。
追加の引数が与えられると、デバッグオプションはこの値に設定されます。

=cut

=item make_socket

  my $sock = Net::SSLeay::Handle->make_socket($host, $port);

=begin original

Creates a socket that is connected to $post using $port. It uses
$Net::SSLeay::proxyhost and proxyport if set and authentificates itself against
this proxy depending on $Net::SSLeay::proxyauth. It also turns autoflush on for
the created socket.

=end original

$port を使って $host に接続されたソケットを作ります。
設定されていれば、$Net::SSLeay::proxyhost と proxyport を使い、
$Net::SSLeay::proxyauth に依存してこのプロキシに対して認証します。
また、作られたソケットの自動フラッシュを有効にします。

=cut

=back

=cut

=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

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

=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

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

=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) でなければなりません。
また二つのグロブは違うものでなければなりません。
私が同じグロブを使おうとしたときには、コアダンプになりました。

=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

ファイル head1 によりキーが付けられたハッシュのハッシュを作ることにより、
(上記の *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 に同時に複数の
ハンドルにアクセスさせるために作られます。

=head1 AUTHOR

Jim Bowlin jbowlin@linklint.org

=head1 SEE ALSO

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

=begin meta

Translate: hippo2000
Update: SHIRAKATA Kentaro <argrath@ub32.org> (1.36-)
Status: completed

=end meta

=cut