595 lines
17 KiB
HTML
595 lines
17 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
|
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
|
<head>
|
|
<title>GT::Mail::POP3 - Receieve email through POP3 protocal</title>
|
|
<link rev="made" href="mailto:root@penguin.office.gossamer-threads.com" />
|
|
|
|
<style type="text/css">
|
|
/* $MVD$:fontset("Untitled Font Set 1","ARIEL","HELVETICA","HELV","SANSERIF") */
|
|
/* $MVD$:fontset("Arial","Arial") */
|
|
/* $MVD$:fontset("Arial Black","Arial Black") */
|
|
/* $MVD$:fontset("Algerian","Algerian") */
|
|
|
|
|
|
body {
|
|
background-color: white;
|
|
font-family: Verdana, Arial, sans-serif;
|
|
font-size: small;
|
|
color: black;
|
|
}
|
|
|
|
|
|
p {
|
|
background-color : white;
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : small;
|
|
color : black;
|
|
}
|
|
|
|
|
|
h1 {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-weight : bold;
|
|
font-size : medium;
|
|
background-color : white;
|
|
color : maroon;
|
|
}
|
|
|
|
|
|
h2 {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : medium;
|
|
font-weight : bold;
|
|
color : blue;
|
|
background-color : white;
|
|
}
|
|
|
|
|
|
h3 {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-weight : bold;
|
|
font-size : medium;
|
|
color : black;
|
|
background-color : white;
|
|
}
|
|
|
|
|
|
h4 {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-weight : bold;
|
|
font-size : small;
|
|
color : maroon;
|
|
background-color : white;
|
|
}
|
|
|
|
|
|
h5 {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-weight : bold;
|
|
font-size : small;
|
|
color : blue;
|
|
background-color : white;
|
|
}
|
|
|
|
|
|
h6 {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-weight : bold;
|
|
font-size : small;
|
|
color : black;
|
|
background-color : white;
|
|
}
|
|
|
|
|
|
ul {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : small;
|
|
color : black;
|
|
}
|
|
|
|
|
|
ol {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : small;
|
|
color : black;
|
|
}
|
|
|
|
|
|
dl {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : small;
|
|
color : black;
|
|
}
|
|
|
|
|
|
li {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : small;
|
|
color : black;
|
|
}
|
|
|
|
|
|
th {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : small;
|
|
color : black;
|
|
}
|
|
|
|
|
|
td {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : small;
|
|
color : black;
|
|
}
|
|
|
|
|
|
dl {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : small;
|
|
color : black;
|
|
}
|
|
|
|
|
|
dd {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : small;
|
|
color : black;
|
|
}
|
|
|
|
|
|
dt {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : small;
|
|
color : black;
|
|
}
|
|
|
|
|
|
code {
|
|
font-family : Courier;
|
|
font-size : small;
|
|
color : black;
|
|
}
|
|
|
|
|
|
pre {
|
|
font-family : Courier;
|
|
font-size : small;
|
|
color : black;
|
|
}
|
|
|
|
.mvd-H1 {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-weight : bold;
|
|
font-size : 14.0pt;
|
|
background-color : transparent;
|
|
background-image : none;
|
|
color : maroon;
|
|
}
|
|
|
|
|
|
.mvd-H2 {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : 12.0pt;
|
|
color : blue;
|
|
}
|
|
|
|
|
|
p.indent {
|
|
font-family : "Verdana, Arial, sans-serif";
|
|
list-style-type : circle;
|
|
list-style-position : inside;
|
|
color : black;
|
|
margin-left : 16.0pt;
|
|
}
|
|
|
|
|
|
.mvd-P-indent {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
list-style-type : circle;
|
|
list-style-position : inside;
|
|
color : black;
|
|
margin-left : 16.0pt;
|
|
}
|
|
|
|
|
|
pre.programlisting {
|
|
font-size : 9.0pt;
|
|
list-style-type : disc;
|
|
margin-left : 16.0pt;
|
|
margin-top : -14.0pt;
|
|
}
|
|
|
|
|
|
.mvd-PRE-programlisting {
|
|
font-size : 9.0pt;
|
|
list-style-type : disc;
|
|
margin-left : 16.0pt;
|
|
margin-top : -14.0pt;
|
|
}
|
|
|
|
|
|
.mvd-PRE {
|
|
font-size : 9.0pt;
|
|
}
|
|
|
|
|
|
p.note {
|
|
margin-left : 28.0pt;
|
|
}
|
|
|
|
|
|
.mvd-P-note {
|
|
margin-left : 28.0pt;
|
|
}
|
|
|
|
|
|
.mvd-H4 {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-weight : normal;
|
|
font-size : 9.0pt;
|
|
color : black;
|
|
margin-left : 6.0pt;
|
|
margin-top : -14.0pt;
|
|
}
|
|
|
|
|
|
.mvd-P {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : 10.0pt;
|
|
color : black;
|
|
}
|
|
|
|
.mvd-BODY {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
background-color : white;
|
|
}
|
|
|
|
|
|
p.indentnobullet {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
list-style-type : none;
|
|
}
|
|
|
|
|
|
.mvd-P-indentnobullet {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
list-style-type : none;
|
|
}
|
|
</style>
|
|
|
|
|
|
</head>
|
|
|
|
<body style="background-color: white">
|
|
|
|
<p><a name="__index__"></a></p>
|
|
<!-- INDEX BEGIN -->
|
|
|
|
<ul>
|
|
|
|
<li><a href="#name">NAME</a></li>
|
|
<li><a href="#synopsis">SYNOPSIS</a></li>
|
|
<li><a href="#description">DESCRIPTION</a></li>
|
|
<ul>
|
|
|
|
<li><a href="#new__constructor_method">new - constructor method</a></li>
|
|
<li><a href="#connect__connect_to_the_pop_account">connect - Connect to the POP account</a></li>
|
|
<li><a href="#head_part__access_the_email_header">head_part - Access the email header</a></li>
|
|
<li><a href="#all_head_parts__access_all_email_headers">all_head_parts - Access all email headers</a></li>
|
|
<li><a href="#parse_message__access_an_email">parse_message - Access an email</a></li>
|
|
<li><a href="#message_save__save_an_email">message_save - Save an email</a></li>
|
|
<li><a href="#stat__do_a_stat_command">stat - Do a STAT command</a></li>
|
|
<li><a href="#list__do_a_list_command">list - Do a LIST command</a></li>
|
|
<li><a href="#rset__do_an_rset_command">rset - Do an RSET command</a></li>
|
|
<li><a href="#dele__do_a_dele_command">dele - Do a DELE command</a></li>
|
|
<li><a href="#quit__quit_the_connection">quit - Quit the connection</a></li>
|
|
<li><a href="#uidl__do_a_uidl_command">uidl - Do a UIDL command</a></li>
|
|
<li><a href="#count__get_the_number_of_messages">count - Get the number of messages</a></li>
|
|
<li><a href="#size__get_the_size_of_all_messages">size - Get the size of all messages</a></li>
|
|
<li><a href="#send__send_a_raw_command">send - Send a raw command</a></li>
|
|
<li><a href="#top__retrieve_the_header">top - Retrieve the header</a></li>
|
|
<li><a href="#retr__retrieve_an_email">retr - Retrieve an email</a></li>
|
|
</ul>
|
|
|
|
<li><a href="#requirements">REQUIREMENTS</a></li>
|
|
<li><a href="#copyright">COPYRIGHT</a></li>
|
|
<li><a href="#version">VERSION</a></li>
|
|
</ul>
|
|
<!-- INDEX END -->
|
|
|
|
<hr />
|
|
<p>
|
|
</p>
|
|
<h1><a name="name">NAME</a></h1>
|
|
<p>GT::Mail::POP3 - Receieve email through POP3 protocal</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="synopsis">SYNOPSIS</a></h1>
|
|
<pre>
|
|
use GT::Mail::POP3;</pre>
|
|
<pre>
|
|
my $pop = GT::Mail::POP3->new(
|
|
host => 'mail.gossamer-threads.com',
|
|
port => 110,
|
|
user => 'someusername',
|
|
pass => 'somepassword',
|
|
auth_mode => 'PASS',
|
|
timeout => 30,
|
|
debug => 1
|
|
);</pre>
|
|
<pre>
|
|
my $count = $pop->connect or die $GT::Mail::POP3::error;</pre>
|
|
<pre>
|
|
for my $num (1 .. $count) {
|
|
my $top = $pop->parse_head($num);</pre>
|
|
<pre>
|
|
my @to = $top->split_field;</pre>
|
|
<pre>
|
|
if (grep /myfriend\@gossamer-threads\.com/, @to) {
|
|
$pop->message_save($num, '/keep/email.txt');
|
|
last;
|
|
}
|
|
}</pre>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="description">DESCRIPTION</a></h1>
|
|
<p>GT::Mail::POP3 is a module to check an email account using the POP3 protocol.
|
|
Many of the methods are integrated with <a href="glist.cgi?do=admin_gtdoc&topic=/GT/Mail/Parse.html">the GT::Mail::Parse manpage</a>.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="new__constructor_method">new - constructor method</a></h2>
|
|
<p>This method is inherited from <a href="glist.cgi?do=admin_gtdoc&topic=/GT/Base.html">the GT::Base manpage</a>. The argument to this method can be
|
|
in the form of a hash or hash ref. As a minimum 'user', 'pass', and 'host' must
|
|
be specified.</p>
|
|
<dl>
|
|
<dt><strong><a name="item_debug">debug</a></strong><br />
|
|
</dt>
|
|
<dd>
|
|
Sets the debugging level for this instance of GT::Mail::POP3.
|
|
</dd>
|
|
<p></p>
|
|
<dt><strong><a name="item_host">host</a></strong><br />
|
|
</dt>
|
|
<dd>
|
|
Sets the host to connect to for checking a POP account. This argument must be
|
|
provided.
|
|
</dd>
|
|
<p></p>
|
|
<dt><strong><a name="item_port">port</a></strong><br />
|
|
</dt>
|
|
<dd>
|
|
Sets the port on the POP server to attempt to connect to. This defaults to 110,
|
|
unless using SSL, for which the default is 995.
|
|
</dd>
|
|
<p></p>
|
|
<dt><strong><a name="item_ssl">ssl</a></strong><br />
|
|
</dt>
|
|
<dd>
|
|
Establishes the connection using SSL. Note that this requires Net::SSLeay of
|
|
at least version 1.06.
|
|
</dd>
|
|
<p></p>
|
|
<dt><strong><a name="item_user">user</a></strong><br />
|
|
</dt>
|
|
<dd>
|
|
Sets the user name to login with when connecting to the POP server. This must
|
|
be specified.
|
|
</dd>
|
|
<p></p>
|
|
<dt><strong><a name="item_pass">pass</a></strong><br />
|
|
</dt>
|
|
<dd>
|
|
Sets the password to login with when connection to the POP server. This must be
|
|
specified.
|
|
</dd>
|
|
<p></p>
|
|
<dt><strong><a name="item_auth_mode">auth_mode</a></strong><br />
|
|
</dt>
|
|
<dd>
|
|
Sets the authentication type for this connection. This can be one of two
|
|
values. PASS (the default) or APOP. If set to APOP, GT::Mail::POP3 will use
|
|
APOP to login to the remote server.
|
|
</dd>
|
|
<p></p>
|
|
<dt><strong><a name="item_timeout">timeout</a></strong><br />
|
|
</dt>
|
|
<dd>
|
|
Sets the connection timeout. This isn't entirely reliable as it uses alarm(),
|
|
which isn't supported on all systems. That aside, this normally isn't needed
|
|
if you want a timeout - it defaults to 30 on alarm()-supporting systems. The
|
|
main purpose is to provide a value of 0 to disable the <code>alarm()</code> timeout.
|
|
</dd>
|
|
<p></p></dl>
|
|
<p>
|
|
</p>
|
|
<h2><a name="connect__connect_to_the_pop_account">connect - Connect to the POP account</a></h2>
|
|
<pre>
|
|
$obj->connect or die $GT::Mail::POP3::error;</pre>
|
|
<p>This method performs the connection to the POP server. Returns the count of
|
|
messages on the server on success, and undefined on failure. Takes no arguments
|
|
and called before you can perform any actions on the POP server.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="head_part__access_the_email_header">head_part - Access the email header</a></h2>
|
|
<pre>
|
|
# Get a parsed header part object for the first email in the list.
|
|
my $top_part = $obj->head_part(1);</pre>
|
|
<p>Instance method. The only argument to this method is the message number to get.
|
|
Returns a <a href="glist.cgi?do=admin_gtdoc&topic=/GT/Mail/Parts.html">the GT::Mail::Parts manpage</a> object containing only the parsed header of the
|
|
specified message.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="all_head_parts__access_all_email_headers">all_head_parts - Access all email headers</a></h2>
|
|
<pre>
|
|
# Get all the head parts from all messages
|
|
my @headers = $obj->all_head_parts;</pre>
|
|
<p>Instance method. Gets all the headers of all the email's on the remote server.
|
|
Returns an array of the <a href="glist.cgi?do=admin_gtdoc&topic=/GT/Mail/Parts.html">the GT::Mail::Parts manpage</a> object. One object for each
|
|
email. None of the email's bodies are retrieved, only the head.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="parse_message__access_an_email">parse_message - Access an email</a></h2>
|
|
<pre>
|
|
# Parse an email and get the GT::Mail object
|
|
my $mail = $obj->parse_message (1);</pre>
|
|
<p>Instance method. Pass in the number of the email to retrieve. This method
|
|
retrieves the specified email and returns the parsed GT::Mail object. If this
|
|
method fails you should check $GT::Mail::error for the error message.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="message_save__save_an_email">message_save - Save an email</a></h2>
|
|
<pre>
|
|
open FH, '/path/to/email.txt' or die $!;</pre>
|
|
<pre>
|
|
# Save message 2 to file
|
|
$obj->message_save (2, \*FH);
|
|
close FH;</pre>
|
|
<p>- or -</p>
|
|
<pre>
|
|
$obj->message_save (2, '/path/to/email.txt') or die $GT::Mail::POP3::error;</pre>
|
|
<p>Instance method. This method takes the message number as it's first argument,
|
|
and either a file path or a file handle ref as it's second argument. If a file
|
|
path is provided the file will be opened to truncate. The email is then
|
|
retrieved from the server and written to the file.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="stat__do_a_stat_command">stat - Do a STAT command</a></h2>
|
|
<pre>
|
|
# Get the number of messages on the server
|
|
my $count = $obj->stat;</pre>
|
|
<p>Instance method. Does a STAT command on the remote server. It stores the total
|
|
size and returns the count of messages on the server, if successful. Otherwise
|
|
returns undef.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="list__do_a_list_command">list - Do a LIST command</a></h2>
|
|
<pre>
|
|
# At a list of messages on the server
|
|
my @messages = $obj->list;</pre>
|
|
<p>Instance method. Does a LIST command on the remote server. Returns an array of
|
|
the lines in list context and a single scalar that contains all the lines in
|
|
scalar context.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="rset__do_an_rset_command">rset - Do an RSET command</a></h2>
|
|
<pre>
|
|
# Tell the server to ignore any dele commands we have issued in this
|
|
# session
|
|
$obj->rset;</pre>
|
|
<p>Instance method. Does an RSET command. This command resets the servers
|
|
knowledge of what should be deleted when QUIT is called. Returns 1 on success.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="dele__do_a_dele_command">dele - Do a DELE command</a></h2>
|
|
<pre>
|
|
# Delete message 4
|
|
$obj->dele (4);</pre>
|
|
<p>Instance method. Does a DELE command. The only argument is the message number
|
|
to delete. Returns 1 on success.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="quit__quit_the_connection">quit - Quit the connection</a></h2>
|
|
<pre>
|
|
# Close our connection
|
|
$obj->quit;</pre>
|
|
<p>Instance method. Sends the QUIT command to the server. The should should
|
|
disconnect soon after this. No more actions can be taken on this connection
|
|
until connect is called again.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="uidl__do_a_uidl_command">uidl - Do a UIDL command</a></h2>
|
|
<pre>
|
|
# Get the uidl for message 1
|
|
my $uidl = $obj->uidl (1);</pre>
|
|
<pre>
|
|
# Get a list of all the uidl's and print them
|
|
$obj->uidl (sub { print @_ });</pre>
|
|
<pre>
|
|
# Get an array of all the uidl's
|
|
my @uidl = $obj->uidl;</pre>
|
|
<p>Instance method. Attempts to do a UIDL command on the remote server. Please be
|
|
aware support for the UIDL command is not very wide spread. This method can
|
|
take the message number as it's first argument. If the message number is given,
|
|
the UIDL for that message is returned. If the first argument is a code
|
|
reference, a UIDL command is done with no message specified and the code
|
|
reference is called for each line returned from the remote server. If no second
|
|
argument is given, a UIDL command is done, and the results are returned in a
|
|
has of message number to UIDL.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="count__get_the_number_of_messages">count - Get the number of messages</a></h2>
|
|
<pre>
|
|
# Get the count from the last STAT
|
|
my $count = $obj->count;</pre>
|
|
<p>This method returns the number of messages on the server from the last STAT
|
|
command. A STAT is done on connect.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="size__get_the_size_of_all_messages">size - Get the size of all messages</a></h2>
|
|
<pre>
|
|
# Get the total size of all messages on the server
|
|
my $size = $obj->size;</pre>
|
|
<p>This method returns the size of all messages in the server as returned by the
|
|
last STAT command sent to the server.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="send__send_a_raw_command">send - Send a raw command</a></h2>
|
|
<pre>
|
|
# Send a raw command to the server
|
|
my $ret = $obj->send ("HELO");</pre>
|
|
<p>This method sends the specified raw command to the POP server. The one line
|
|
return from the server is returned. Do not call this method if you are
|
|
expecting more than a one line response.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="top__retrieve_the_header">top - Retrieve the header</a></h2>
|
|
<pre>
|
|
# Get the header of message 2 in an array. New lines are stripped
|
|
my @header = $obj->top (2);</pre>
|
|
<pre>
|
|
# Get the header as a string
|
|
my $header = $obj->top (2);</pre>
|
|
<p>Instance method to retrieve the top of an email on the POP server. The only
|
|
argument should be the message number to retrieve. Returns a scalar containing
|
|
the header in scalar context and an array, which is the scalar split on
|
|
\015?\012, in list context.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="retr__retrieve_an_email">retr - Retrieve an email</a></h2>
|
|
<pre>
|
|
# Get message 3 from the remote server in an array. New lines are stripped
|
|
my @email = $obj->retr (3);</pre>
|
|
<pre>
|
|
# Get it as a string
|
|
my $email = $obj->retr (3);</pre>
|
|
<p>Instance method to retrieve an email from the POP server. The first argument to
|
|
this method should be the message number to retrieve. The second argument is an
|
|
optional code ref to call for each line of the message that is retrieved. If no
|
|
code ref is specified, this method will put the email in a scalar and return
|
|
the scalar in scalar context and return the scalar split on \015?\012 in list
|
|
context.</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="requirements">REQUIREMENTS</a></h1>
|
|
<p><a href="glist.cgi?do=admin_gtdoc&topic=/GT/Socket/Client.html">the GT::Socket::Client manpage</a>
|
|
<a href="glist.cgi?do=admin_gtdoc&topic=/GT/Base.html">the GT::Base manpage</a>
|
|
<a href="glist.cgi?do=admin_gtdoc&topic=/GT/MD5.html">the GT::MD5 manpage</a> (for APOP authentication)</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="copyright">COPYRIGHT</a></h1>
|
|
<p>Copyright (c) 2004 Gossamer Threads Inc. All Rights Reserved.
|
|
<a href="http://www.gossamer-threads.com/">http://www.gossamer-threads.com/</a></p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="version">VERSION</a></h1>
|
|
<p>Revision: $Id: POP3.pm,v 1.56 2004/03/19 00:36:16 brewt Exp $</p>
|
|
|
|
</body>
|
|
|
|
</html>
|