Net::NNTP

(原始碼, CPAN)

版本 3.15

#名稱

Net::NNTP - NNTP 客户端類別

#語法

use Net::NNTP;

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

# start with SSL, e.g. nntps
$nntp = Net::NNTP->new("some.host.name", SSL => 1);

# start with plain and upgrade to SSL
$nntp = Net::NNTP->new("some.host.name");
$nntp->starttls;

#說明

Net::NNTP 是一個類別，它在 Perl 中實作一個簡單的 NNTP 客户端，如 RFC977 和 RFC4642 所述。透過安裝 IO::Socket::SSL，它也提供對隱式和明確 TLS 加密的支援，例如 NNTPS 或 NNTP+STARTTLS。

Net::NNTP 類別是 Net::Cmd 的子類別，以及（視可用性而定）IO::Socket::IP、IO::Socket::INET6 或 IO::Socket::INET 的子類別。

#類別方法

#new([$host][, %options])

這是新的 Net::NNTP 物件的建構函式。$host 是需要 NNTP 連線的遠端主機名稱。如果未提供，則可以將其作為下面所述的 Host 選項傳遞。如果未傳遞主機，則會檢查兩個環境變數，首先是 NNTPSERVER，然後是 NEWSHOST，然後檢查 Net::Config，如果找不到主機，則使用 news。

%options 以雜湊方式傳遞，使用鍵值對。可能的選項為

Host - 要連線的 NNTP 主機。它可以是單一純量，如 IO::Socket::INET 中 PeerAddr 選項所定義的，或參考一個陣列，其中包含要依序嘗試的主機。 "host" 方法將傳回用於連線到主機的值。

埠 - 要連線的埠。預設值 - 119 為一般 NNTP，563 為立即 SSL (nntps)。

SSL - 如果連線應從開始就使用 SSL，與稍後使用 starttls 升級相反。您可以使用 IO::Socket::SSL 中記載的 SSL 引數，但通常會自動使用正確的引數。

逾時 - 從 NNTP 伺服器等待回應的最長時間（以秒為單位），值為零會導致所有 IO 作業封鎖。（預設值：120）

偵錯 - 啟用偵錯資訊列印至 STDERR

讀取器 - 如果遠端伺服器是 INN，則最初連線會到 innd，預設情況下 Net::NNTP 會發出 MODE READER 指令，讓遠端伺服器變成 nnrpd。如果 Reader 選項給定的值為零，則不會傳送此指令，且連線將保持與 innd 通訊。

LocalAddr 和 LocalPort - 這些參數會直接傳遞給 IO::Socket，以允許將 socket 繫結到特定的本機位址和埠。

網域 - 這個參數會直接傳遞給 IO::Socket，即使使用 IO::Socket::IP 作為超級類別，也能強制執行 IPv4 連線。或者可以使用 Family。

#物件方法

除非另有說明，否則所有方法都會傳回 true 或 false 值，其中 true 表示作業成功。當方法指出它會傳回值時，失敗會傳回 undef 或空清單。

Net::NNTP 繼承自 Net::Cmd，因此在 Net::Cmd 中定義的方法可用於將指令傳送至遠端 NNTP 伺服器，除了此處所記錄的方法外。

#host()

傳回建構函式所使用的值，並傳遞至 IO::Socket::INET，以連線至主機。

#starttls()

將現有的純文字連線升級為 SSL。任何 SSL 所需的引數都必須已在 new 中提供。

#article([{$msgid|$msgnum}[, $fh]])

擷取標頭、空白行，然後是指定文章的主體 (文字)。

如果指定 $fh，則預期它是一個有效的檔案句柄，結果將列印至其中，成功時會傳回 true 值。如果未指定 $fh，則成功時傳回值會是包含所要求文章的陣列參考，陣列中的每個項目都將包含文章的一行。

如果未傳遞任何引數，則會擷取目前選取新聞群組中的目前文章。

$msgnum 是目前新聞群組中某篇文章的數字 ID，且會變更目前文章指標。$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 指令用於設定「目前文章指標」，而不傳送文字。

使用 nntpstat 指令依訊息 ID 選取是有效的，但價值可疑，因為依訊息 ID 選取不會變更「目前文章指標」。

傳回「目前文章」的訊息 ID。

#group([$group])

設定和/或取得目前的群組。如果未提供 $group，則傳回目前群組的資訊。

在純量內容中，它會傳回群組名稱。

在陣列內容中，傳回值會是一個清單，其中包含群組中的文章數、第一篇文章的編號、最後一篇文章的編號和群組名稱。

#help()

從伺服器要求說明文字（此實作可理解的指令的簡要摘要）。傳回文字或在失敗時傳回未定義。

#ihave($msgid[, $message])

ihave 指令會告知伺服器，客戶端有一個 ID 為 $msgid 的文章。如果伺服器想要取得該文章的副本，且已提供 $message，則會將其傳送出去。

如果伺服器想要取得該文章，且已成功傳送 $message（如果已指定），則傳回 true。

如果未指定 $message，則必須使用 Net::Cmd 中的 datasend 和 dataend 方法傳送訊息。

$message 可以是陣列的線條或陣列的參考，且呼叫者必須將其編碼為任何所需編碼的八位元組，例如使用 Encode 模組的 encode() 函數。

#last()

將「目前文章指標」設定為目前新聞群組中的前一篇文章。

傳回該篇文章的訊息 ID。

#date()

傳回遠端伺服器的日期。此日期將採用 UNIX 時間格式（自 1970 年起的秒數）。

#postok()

如果伺服器的初始回應表示它允許張貼，則 postok 會傳回 true。

#authinfo($user, $pass)

使用提供的使用者名稱和密碼，根據 RFC2980 中定義的原始 AUTHINFO USER / AUTHINFO PASS 形式，向伺服器進行驗證。請注意，密碼會以純文字傳送到伺服器。除非與伺服器的連線已受到某種程度的保護，否則不應使用此指令搭配有價值的密碼。

#authinfo_simple($user, $pass)

使用提供的使用者名稱和密碼，根據 RFC2980 中定義和棄用的建議 NNTP V2 AUTHINFO SIMPLE 形式，向伺服器進行驗證。與 "authinfo" 一樣，密碼會以純文字傳送。

#list()

取得所有活動新聞群組的資訊。結果是對雜湊的參考，其中金鑰是群組名稱，每個值都是對陣列的參考。此陣列中的元素為：- 群組中的最後一篇文章編號、群組中的第一篇文章編號和關於群組的任何資訊標記。

#newgroups($since[, $distributions])

$since 是時間值，而 $distributions 是分佈模式或對分佈模式清單的參考。結果與 list 相同，但回傳的群組將會限制在 $since 之後建立的群組，如果已指定，則會限制在 $distributions 中的分佈區域之一。

#newnews($since[, $groups[, $distributions]])

$since 是時間值。$groups 是群組模式或對群組模式清單的參考。$distributions 是分佈模式或對分佈模式清單的參考。

回傳對清單的參考，其中包含在 $since 之後張貼的所有新聞的訊息 ID，這些新聞位於與 $groups 相符的群組中，並且分佈與 $distributions 相符。

#next()

將「目前文章指標」設定為目前新聞群組中的下一篇文章。

傳回該篇文章的訊息 ID。

#post([$message])

將一則新文章張貼到新聞伺服器。如果已指定 $message 且允許張貼，則會傳送訊息。

如果未指定 $message，則必須使用 Net::Cmd 中的 datasend 和 dataend 方法傳送訊息。

$message 可以是陣列的線條或陣列的參考，且呼叫者必須將其編碼為任何所需編碼的八位元組，例如使用 Encode 模組的 encode() 函數。

透過 datasend 或作為 $message 參數傳送的訊息，必須符合 RFC822 所述的格式，且必須包含 From:、Newsgroups: 和 Subject: 標頭。

#postfh()

使用連結檔案句柄將一則新文章張貼到新聞伺服器。如果允許張貼，此方法將傳回一個連結檔案句柄，你可以將要張貼的文章內容列印（print()）到該句柄。你必須在完成文章張貼後明確地關閉（close()）檔案句柄，而 close() 呼叫的傳回值將指出訊息是否已成功張貼。

#slave()

告訴遠端伺服器我不是使用者用戶端，而是另一個新聞伺服器。

#quit()

退出遠端伺服器並關閉 socket 連線。

#can_inet6()

傳回我們是否可以使用 IPv6。

#can_ssl()

傳回我們是否可以使用 SSL。

#延伸方法

這些方法使用不屬於 RFC977 文件一部分的指令。有些伺服器可能不支援所有這些指令。

#newsgroups([$pattern])

傳回一個雜湊的參考，其中金鑰是所有符合 $pattern 的群組名稱，或所有群組（如果未指定模式），且每個值都包含群組的說明文字。

#distributions()

傳回一個雜湊的參考，其中金鑰是所有可能的配送名稱，而值是配送說明。

#distribution_patterns()

傳回一個陣列的參考，其中每個元素（本身是一個陣列參考）包含由某些 NNTP 伺服器維護的 distrib.pats 清單中一行三個欄位，即：權重、通配符和用戶可使用來建構 Distribution 標頭的值。

#subscriptions()

傳回一個清單的參考，其中包含建議新用戶訂閱的群組清單。

#overview_fmt()

傳回一個陣列的參考，其中包含 xover 傳回的欄位名稱。

#active_times()

傳回一個雜湊的參考，其中鍵是群組名稱，每個值都是一個陣列的參考，其中包含群組建立的時間和建立者的識別碼（可能是電子郵件地址）。

#active([$pattern])

類似於 list，但只傳回符合模式的活動群組。$pattern 可以是群組模式。

#xgtitle($pattern)

傳回一個雜湊的參考，其中鍵是所有符合 $pattern 的群組名稱，每個值都是群組的說明文字。

#xhdr($header, $message_spec)

取得所有指定訊息的標頭欄位 $header。

傳回值將是一個雜湊的參考，其中鍵是訊息編號，每個值都包含該訊息所要求標頭的文字。

#xover($message_spec)

傳回值將是一個雜湊的參考，其中鍵是訊息編號，每個值都包含一個陣列的參考，其中包含該訊息的概觀欄位。

欄位的名稱可透過呼叫 overview_fmt 取得。

#xpath($message_id)

傳回伺服器上包含指定訊息之檔案的路徑名稱。

#xpat($header, $pattern, $message_spec)

結果與 xhdr 相同，但會限制在標頭文字符合 $pattern 的標頭。

#xrover($message_spec)

XROVER 指令會傳回所指定文章的參考資訊。

傳回對 HASH 的參考，其中金鑰為訊息編號，而值為文章中的 References: 行。

#listgroup([$group])

傳回對 $group 中所有有效訊息清單的參考，或在未指定 $group 的情況下傳回目前群組的參考。

#reader()

告知伺服器您是讀者，而不是其他伺服器。

某些伺服器需要此項。例如，如果您連線到 INN 伺服器，且您有傳輸權限，則您的連線會連線到傳輸守護程式，而不是 NNTP 守護程式。發出此指令會導致傳輸守護程式將控制權移交給 NNTP 守護程式。

有些伺服器不了解此指令，但發出此指令並忽略回應是無害的。

#不支援

下列 NNTP 指令不受套件支援，且沒有計畫支援。

AUTHINFO GENERIC
XTHREAD
XSEARCH
XINDEX

#定義

#$message_spec

$message_spec 是單一訊息識別碼、單一訊息編號，或對兩個訊息編號清單的參考。

如果 $message_spec 是對兩個訊息編號清單的參考，且範圍內的第二個編號小於或等於第一個編號，則此範圍表示第一個訊息編號之後群組中的所有訊息。

注意僅出於與 Net::NNTP 較早版本相容性的原因，訊息規格才能傳遞為兩個數字的清單，此做法已不建議使用，現在應傳遞對清單的參考

#$pattern

NNTP 協定使用 WILDMAT 格式作為模式。WILDMAT 格式最初是由 Rich Salz 開發，其基礎為 UNIX「find」指令中用於說明檔名的格式。它的開發目的是提供統一機制，以與 UNIX shell 比對檔名的方式相同來比對模式。

測試比對時，模式會隱含地錨定在每個字串的開頭和結尾。

除了模式與要檢查比對的來源之間的嚴格一對一比對之外，還有五種模式比對操作。

第一個是星號 *，用於比對任何零個或多個字元的序列。

第二個是問號 ?，用於比對任何單一字元。第三個指定特定字元組。

此組指定為字元清單，或字元範圍（範圍的開頭和結尾以減號（或破折號）字元分隔），或清單和範圍的任何組合。減號也可以包含在組中，作為組的開頭或結尾。此組括在方括號中。如果方括號 ] 是組中的第一個字元，則可以使用它。

第四個操作與第三個操作的邏輯非相同，指定方式與第三個相同，但在測試字串開頭的方括號內加上插入符號 ^ 字元。

最後一個運算使用反斜線字元來取消開方括號 [、星號、反斜線或問號的特殊意義。兩個反斜線連續出現會導致反斜線被評估為沒有特殊意義的字元。

#範例
#[^]-]: 與方括號或減號/破折號以外的任何單一字元相符。
#*bdc: 與任何以字串「bdc」結尾的字串相符，包括字串「bdc」（不含引號）。
#[0-9a-zA-Z]: 與任何單一可列印的字母數字 ASCII 字元相符。
#a??d: 與任何以 a 開頭、以 d 結尾的四個字元字串相符。

#EXPORTS

無.

#已知錯誤

請參閱 https://rt.cpan.org/Dist/Display.html?Status=Active&Queue=libnet。

#另請參閱

Net::Cmd、IO::Socket::SSL。

#作者

Graham Barr <gbarr@pobox.com>。

從 1.22_02 版開始，Steve Hay <shay@cpan.org> 現在維護 libnet。

#版權

#授權

此模組是自由軟體；您可以在與 Perl 相同的條款下重新散布或修改它，亦即在 LICENCE 檔案中指定的 GNU 通用公共授權或 Artistic 授權條款下。

#版本