名前¶

Net::NNTP - NNTPクライアント・クラス

概要¶

    use Net::NNTP;

    $nntp = Net::NNTP->new("some.host.name");
    $nntp->quit;

説明¶

Net::NNTPはPerlでのRFC977で記述されているNNTPクライアントの簡単な実装です。 Net::NNTPはNet::Cmdからの通信メソッドを継承します。

コンストラクタ¶

new ( [ HOST ] [, OPTIONS ])

これは新しいNet::NNTPオブジェクトのコンストラクタです。HOSTはNNTP接続に 必要とされるリモートホストです。与えられなければ、まずNNTPSERVER、 それからNEWSHOSTという2つの環境変数がチェックされます。そして Net::Configチェックされます。ホストが見つからなければ、newsが 使われます。

OPTIONSはキーと値の組というハッシュの形式で渡されます。 指定できるオプションは以下の通りです:

Timeout - NNTPサーバーからの応答を待つ、秒単位での最大時間。 0に設定されると全てのIOオペレーションはブロックされます。 (デフォルト: 120)

Debug - STDERRにデバッグ情報を出力することを有効にします。

Reader - もしリモート・サーバーがINNであれば、最初に nnrpdに接続し、デフォルトではNet::NNTPは リモートサーバーがinndになるよう、MODE READERコマンドを発行します。 もしReaderオプションが値0で与えられると、このコマンドは送信されず、 接続はnnrpdに話しかけるままになります。

メソッド¶

特に記述がなければ、全てのメソッドはtrueまたはfalseを返します。 trueが処理が成功したことを意味します。メソッドが値を返すと 宣言しているときには、失敗ではundefまたは空リストを返します。

article ( [ MSGID|MSGNUM ], [FH] )

指定された記事のヘッダ、空行、そして本文（テキスト）を取り出します。

FHが指定されると、それは適切なファイルハンドルであると予想され、 結果がそれに出力されます。成功したときにはtrue値が返されます。 FHが指定されなければ、成功したときの戻り値は、要求された 記事が入った配列へのリファレンスになります。配列の各エントリには 記事の行が入っています。

何も引数が渡されなければ、現在選択されているニューズグループでの 現在の記事が取り出されます。

MSGNUMは現在のニュースグループでの記事の数値による識別子で、 現在の記事のポインタを変更します。MSGIDは記事のヘッダに現れる メッセージIDです。それはクライアントがnewnewsコマンドによって 提供されたリストから、他の記事で取得された参照から、あるいは なんらか他のコマンドへの応答で提供されるメッセージIDから MSGIDを取得することが予想されます。

もしエラーがあれば、undefが返されます。

body ( [ MSGID|MSGNUM ], [FH] )

articleと同じですが、記事の本文だけを取り出します。

head ( [ MSGID|MSGNUM ], [FH] )

articleと同じですが、記事のヘッダだけを取り出します。

articlefh ( [ MSGID|MSGNUM ] )

bodyfh ( [ MSGID|MSGNUM ] )

headfh ( [ MSGID|MSGNUM ] )

これらはarticle(), body() そして head()に似ていますが、 要求されたデータを直接返すのではなく、記事をそこから読み込むための 結び付けられたファイルハンドルを返します。

nntpstat ( [ MSGID|MSGNUM ] )

nntpstatコマンドはarticleコマンドに似ていますが、何もテキストを 返しません。グループの中のメッセージ番号で選択すると、nntpstatコマンドは "現在の記事ポインタ"をテキストを送信することなく設定させます。

メッセージIDによって選択するためにnntpstatコマンドを使うことは適切ですが、 疑問が残ります。というのもメッセージIDによる選択は"現在の記事ポインタ"を 変更しないからです。

"現在の記事"のメッセージIDを返します。

group ( [ GROUP ] )

現在のグループを設定/取得します。もしGROUPが与えられなければ、現在のグループに 関する情報が返されます。

スカラー・コンテキストではグループ名を返します。

配列コンテキストではグループ内の記事の数、先頭の記事の番号、最後の記事の番号、 グループ名が入ったリストになります。

ihave ( MSGID [, MESSAGE ])

ihaveコマンドはクライアントがMSGIDというIDの 記事を持っていることをサーバーに伝えます。サーバーがその記事の コピーを求め、MESSAGEが与えられていれば、それは送信されます。

もし指定されていれば、サーバーがその記事を求めMESSAGEが正常に 送信されたならば、trueを返します。

MESSAGEが指定されなければ、メッセージはNet::Cmdからの datasendとdataendメソッドを使って送信されなければなりません。

MESSAGEは行の配列または配列のリファレンスのどちらにもすることができます。

last ()

"current article pointer"を現在のニュースグループでの前の記事に設定します。

その記事のメッセージIDを返します。

date ()

リモートサーバ上の日付を返します。この日付はUNIXの時刻フォーマット (1970年からの秒数)になります。

postok ()

サーバーの最初の応答がポストを許可することを示して入ればpostokは trueを返します。

authinfo ( USER, PASS )

list ()

全てのアクティブなニュースグループに関する情報を取得します。 結果はハッシュへのリファレンスになります。キーがグループ名、 それぞれの値が配列へのリファレンスになります。この配列の要素は:- そのグループでの最後の記事番号、グループでの先頭の記事番号、 そしてグループに関する情報フラグです。

newgroups ( SINCE [, DISTRIBUTIONS ])

SINCEは時刻の値、そしてDISTRIBUTIONSはディストリビューション・ パターンあるいはディトリビューション・パターンのリストへのリファレンスです。 結果はlistと同じです。しかし返されるグループは、指定されていれば SINCE以後、DISTRIBUTIONSの中のディストリビューション領域の １つに作成されたものに限定されます。

newnews ( SINCE [, GROUPS [, DISTRIBUTIONS ]])

SINCEは時刻の値。GROUPSはグループのパターンあるいはグループの パターンのリストへのリファレンスになります。DISTRIBUTIONSは ディストリビューション・パターンあるいはディストリビューション・パターンの リストへのリファレンスになります。

SINCE以降、GROUPSにマッチしたグループで、かつDISTRIBUTIONSに マッチするディストリビューションに、ポストされた全てのニュースの メッセージIDが入ったリストへのリファレンスを返します。

next ()

"現在の記事ポインタ"を現在のニュースグループでの次の記事に設定します。

その記事のメッセージIDを返します。

post ( [ MESSAGE ] )

ニュースサーバへ新しい記事をポストします。MESSAGEが指定され、ポストが 許可されていれば、そのメッセージは送信されます。

MESSAGEが指定されなければ、そのメッセージはNet::Cmdからの datasend と dataend メソッドを使って送信されなければなりません。

MESSAGEは行の配列あるいは配列へのリファレンスのどちかを設定することが できます。

postfh ()

結び付けられたファイルハンドルを使って新しい記事をニュースサーバーに ポストします。もしポストが許可されていれば、このメソッドは ポストする記事の内容をprint()することができる、結び付けられた ファイルハンドルを返します。記事のポストが完了したときには明示的に そのファイルハンドルをclose()しなければなりません。そしてclose() 呼び出しからの戻り値は、そのメッセージが正常にポストされたかを示します。

slave ()

リモートサーバーに自分がユーザ・クライアントではなく、おそらく他の ニュースサーバーであると伝えます。

quit ()

リモートサーバーを終了させ、ソケット接続を閉じます。

拡張メソッド¶

これらのメソッドはRFC977のドキュメントの中に入っていないコマンドを使います。 サーバーによってはこれらの全てはサポートしていないかもしれません。

newsgroups ( [ PATTERN ] )

キーがPATTERNにマッチする全てのグループ名、あるいはパターンが指定されなければ すべてのグループ名。そしてそれぞれの値には、そのグループの説明のテキストが入ります。 ハッシュへのリファレンスを返します。

distributions ()

キーが全ての可能なディストリビューション名、そして値がディストリビューションの 説明であるハッシュへのリファレンスを返します。

subscriptions ()

ニュース・ユーザーが参加することが勧められるグループのリストが入った リストへのリファレンスを返します。

overview_fmt ()

xoverによって返されるフィールドの名前が入った配列へのリファレンスを返します。

active_times ()

キーがグループ名、値がそのグループが作られた時刻と作成者のおそらくはEmailアドレス である識別子が入った配列へのリファレンスであるハッシュへのリファレンスを返します。

active ( [ PATTERN ] )

listと同様。ただしパターンにマッチするアクティブなグループだけが返されます。 PATTERNはグループパターンにすることができます。

xgtitle ( PATTERN )

キーがPATTERNにマッチする全てのグループ名、それぞれの値がそのグループの 説明であるハッシュへのリファレンスを返します。

xhdr ( HEADER, MESSAGE-SPEC )

指定された全てのメッセージのヘッダ・フィールドHEADERを取得します。

戻り値はキーがメッセージ番号、それぞれの値にはそのメッセージの要求されたヘッダ のテキストが入ったハッシュへのリファレンスになります。

xover ( MESSAGE-SPEC )

戻り値はキーがメッセージ番号、それぞれの値にはそのメッセージの概要(=overview) フィールドが入った配列へのリファレンスが入ったハッシュへのリファレンスになります。

フィールドの名前はoverview_fmtを呼び出すことによって取得することができます。

xpath ( MESSAGE-ID )

指定されたメッセージが入っているサーバー上のファイルへのパス名を返します。

xpat ( HEADER, PATTERN, MESSAGE-SPEC)

ヘッダのテキストがPATTERNにマッチするヘッダに制限されることを除けば 結果はxhdrと同じです。

xrover

XROVERコマンドは指定された記事の参照情報を返します。

キーがそのメッセージ番号、値がその記事からの行であるリファレンスであるハッシュ へのリファレンスを返します。

listgroup ( [ GROUP ] )

GROUPあるいはGROUPが指定されなければ現在のグループでの、 全てのアクティブなメッセージへのリファレンスを返します。

reader

サーバーにあなたがリーダーであり、他のサーバーではないことを伝えます。

これはいくつかのサーバーによっては必須です。 例えばINNサーバーに接続し、伝送許可を持っているならば、あなたの接続は NNTPデーモンではなく、INNサーバーと伝送デーモンに接続します。 このコマンドを発行すると、伝送デーモンに制御をNNTPデーモンに渡させます。

いくつかのサーバーは、このコマンドを理解しません。しかしこれを発行し、 その応答を無視しても害はありません。

未サポート¶

以下のNNTPコマンドはこのパッケージではサポートされていません。そして そうする計画もありません。

    AUTHINFO GENERIC
    XTHREAD
    XSEARCH
    XINDEX

定義¶

メッセージ指定(MESSAGE-SPEC)

メッセージ指定(MESSAGE-SPEC)はメッセージID、１つのメッセージ番号、あるいは 2つのメッセージ番号のリストへのリファレンスのいずれかになります。

MESSAGE-SPECが2つのメッセージ番号のリストへのリファレンスで、 範囲での2番目の番号が最初のもの以下であれば、範囲はそのグループでの 先頭のメッセージ番号以後の全てのメッセージを表します。

注意 Net::NNTPの以前のバージョンとの互換性のためだけに、メッセージ指定 は2つの番号のリストとして渡すことが出来ます。 これはもはや軽視されています。今はリストへのリファレンスを渡すべきです。

パターン

NNTPプロトコルはパターンにWILDMATフォーマットを使用します。 WILDMATフォーマットは、ファイル名を明確に表現するためのUNIX "find" コマンドで使われるフォーマットを元に、最初にRich Salzによって 開発されました。UNIXシェルがファイル名をマッチさせるのと同じ方法で パターンをマッチさせる単一のメカニズムを提供するよう開発されました。

マッチするかのテストのさい、パターンは暗黙のうちに、 各文字列の開始と終了に固定されます。

パターンとマッチがチェックされる元との間での厳格な1対1のマッチではなく、 5つのパターンマッチ演算子があります。

まず最初に0またはそれ以上の文字の任意の文字の並びにマッチする、 アスタリスク*です。

2番目が1つの文字にマッチするクエスチョン・マーク?。3番目は特定の 文字の集合を指定します。

集合は文字のリスト、あるいは範囲の開始と終了がマイナス（あるいはダッシュ）文字 によって区切られた文字の範囲、あるいはリストと範囲の任意の組み合わせ で指定されます。もし集合の始まりあるいは終わりであれば、ダッシュを 文字として集合に入れることも出来ます。この集合は角括弧(=[])で囲まれます。 集合の先頭の文字であれば、閉じ角括弧]を集合で使うこともできます。

4番目の演算子は3番目の演算子の否定(NOT)と論理的に同じで、 3番目のと同じ方法で指定される内容に加えて、テストする文字列の 開き角括弧のすぐ内側に先頭のキャラット文字^がつきます。

最後の演算子は開き角括弧[、アスタリスク、バックスラッシュ、あるいは クエスチョンマークの特別な意味を無効にするためバックスラッシュを使います。 並びの中での2つのバックスラッシュは、評価された中では 特別な意味を持たない文字としてのバックスラッシュになります。

例

[^]-]

閉じ角括弧(])、あるいはマイナス符号/ダッシュではない１つの文字に マッチします。

*bdc

文字列"bdc"(クォートは除く)含めて文字列"bdc"で終わる全ての 文字列にマッチします。

[0-9a-zA-Z]

印字可能な英数字のASCIIの１つの文字にマッチします。

a??d

aで始まり、dで終わる4文字の文字列にマッチします。

参考資料¶

Net::Cmd

作者¶

Graham Barr <gbarr@pobox.com>

著作権(COPYRIGHT)¶

Copyright (c) 1995-1997 Graham Barr. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

$Id$