Net::POP3

(原始碼, CPAN)

版本 3.15

#名稱

Net::POP3 - 郵局通訊協定 3 客戶端類別 (RFC1939)

#語法

use Net::POP3;

# Constructors
$pop = Net::POP3->new('pop3host');
$pop = Net::POP3->new('pop3host', Timeout => 60);
$pop = Net::POP3->new('pop3host', SSL => 1, Timeout => 60);

if ($pop->login($username, $password) > 0) {
  my $msgnums = $pop->list; # hashref of msgnum => size
  foreach my $msgnum (keys %$msgnums) {
    my $msg = $pop->get($msgnum);
    print @$msg;
    $pop->delete($msgnum);
  }
}

$pop->quit;

#說明

此模組實作了 POP3 通訊協定的客戶端介面，讓 perl5 應用程式可以與 POP3 伺服器通訊。此文件假設您已熟悉 RFC1939 中所述的 POP3 通訊協定。如果已安裝 IO::Socket::SSL，它也會支援隱式和明確的 TLS 加密，亦即 POP3S 或 POP3+STARTTLS。

必須使用 new 方法建立新的 Net::POP3 物件。完成此步驟後，所有 POP3 指令都可透過物件上的方法呼叫存取。

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

#類別方法

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

這是新的 Net::POP3 物件的建構函式。$host 是需要建立 POP3 連線的遠端主機名稱。

$host 是選配的。如果沒有提供 $host，則可以改用下方所述的 Host 選項傳遞。如果兩者都沒有提供，則會使用 Net::Config 中指定的 POP3_Hosts。

%options 以雜湊函數傳遞，使用鍵值對。可能的選項有

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

Port - 要連線的埠。預設值 - 一般 POP3 為 110，POP3s（直接 SSL）為 995。

SSL - 如果連線應從一開始就使用 SSL，而不是稍後使用 starttls 升級。你可以使用 IO::Socket::SSL 中所記載的 SSL 引數，但通常會自動使用正確的引數。

LocalAddr 和 LocalPort - 這些參數會直接傳遞給 IO::Socket，以允許將 socket 繫結到特定的本機位址和埠。為了與舊版本相容，可以使用 ResvPort 取代 LocalPort。

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

Timeout - 等待 POP3 伺服器回應的最長時間（秒），預設值：120

Debug - 啟用偵錯資訊

#物件方法

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

Net::POP3 繼承自 Net::Cmd，因此可以在此記載的方法之外，使用 Net::Cmd 中定義的方法將指令傳送至遠端 POP3 伺服器。

#host()

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

#auth($username, $password)

嘗試 SASL 驗證。

#user($user)

傳送 USER 指令。

#pass($pass)

傳送 PASS 指令。傳回郵件信箱中的訊息數目。

#login([$user[, $pass]])

傳送 USER 和 PASS 指令。如果未提供 $pass，Net::POP3 會使用 Net::Netrc 透過主機和使用者名稱查詢密碼。如果未指定使用者名稱，則會使用目前的使用者名稱。

傳回郵件信箱中的訊息數目。不過，如果伺服器上沒有訊息，則會傳回字串 "0E0"。這會在布林值脈絡中傳回 true 值，但在數字脈絡中傳回 0。

如果驗證使用者時發生錯誤，則會傳回 undef。

#starttls(%sslargs)

將現有的純文字連線升級為 SSL。您可以使用 IO::Socket::SSL 中記載的 SSL 引數，但通常會使用正確的引數。

#apop([$user[, $pass]])

使用密碼 $pass 驗證伺服器，並辨識為 $user。類似於 "login"，但密碼不會以明文傳送。

要使用此方法，您必須安裝 Digest::MD5 或 MD5 模組，否則此方法會傳回 undef。

#banner()

傳回伺服器的連線橫幅

#capa()

傳回伺服器功能的雜湊參考。APOP 會新增為偽功能。請注意，我無法找到標準功能值的清單，有些功能值似乎是多字詞，有些則不是。我們會嘗試智慧化地分析它們，但可能不正確。

#capabilities()

與 capa 相同，但只使用我們上次詢問伺服器的快取，以避免詢問多次。

#top($msgnum[, $numlines])

取得訊息 $msgnum 的標頭和主體的前 $numlines 行。傳回一個包含從伺服器讀取的文字行的陣列參考。

#list([$msgnum])

如果呼叫帶有引數，list 會傳回訊息的大小（以八位元組為單位）。

如果未呼叫參數，將傳回雜湊的參考。金鑰將為所有未刪除訊息的 $msgnum，而值將為其八位元組大小。

#get($msgnum[, $fh])

從遠端郵件信箱取得訊息 $msgnum。如果未提供 $fh，則 get 會傳回包含從伺服器讀取的文字列的陣列參考。如果提供 $fh，則從伺服器傳回的文字列會列印到檔案處理 $fh。

#getfh($msgnum)

如同 get()，但傳回繫結的檔案處理。從此檔案處理讀取會傳回所要求的訊息。檔案處理會在訊息結束時傳回 EOF，不應重複使用。

#last()

傳回已存取所有訊息中最高的 $msgnum。

#popstat()

傳回兩個元素的清單。這些元素為未刪除元素的數量和 mbox 的八位元組大小。

#ping($user)

傳回兩個元素的清單。這些元素為 $user 的新訊息數量和訊息總數。

#uidl([$msgnum])

如果提供，傳回 $msgnum 的唯一識別碼。如果未提供 $msgnum，uidl 會傳回雜湊的參考，其中金鑰為訊息編號，而值為唯一識別碼。

#delete($msgnum)

標記訊息 $msgnum 以從遠端郵件信箱刪除。當伺服器連線關閉時，所有標記為要刪除的訊息將從遠端郵件信箱移除。

#reset()

重設遠端 POP3 伺服器的狀態。這包括重設所有訊息的狀態，使其不會被刪除。

#quit()

退出並關閉與遠端 POP3 伺服器的連線。任何標記為已刪除的訊息都將從遠端信箱中刪除。

#can_inet6()

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

#can_ssl()

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

#備註

如果在呼叫 quit 方法之前，Net::POP3 物件超出範圍，則在關閉連線之前將呼叫 reset 方法。這表示任何標記為要刪除的訊息都不會被刪除。

#匯出

無.

#已知錯誤

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

#另請參閱

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

#作者

Graham Barr <gbarr@pobox.com>。

Steve Hay <shay@cpan.org> 目前維護 libnet，版本為 1.22_02。

#版權

#授權

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

#版本

版本 3.15

#日期

2023 年 3 月 20 日

#歷程

請參閱 Changes 檔案。

目錄

#名稱

#語法

#說明

#類別方法

#物件方法

#備註

#匯出

#已知錯誤

#另請參閱

#作者

#版權

#授權

#版本

#日期

#歷程