Mail-POP3Client
view release on metacpan or search on metacpan
lib/Mail/POP3Client.pm view on Meta::CPAN
# only send the QUIT message is the socket is still connected. Some
# POP3 servers close the socket after a failed authentication. It
# is unclear whether the RFC allows this or not, so we'll attempt to
# check the condition of the socket before sending data here.
if ($me->Alive() && $me->Socket() && $me->Socket()->connected() ) {
$me->_sockprint( "QUIT", $me->EOL );
# from Patrick Bourdon - need this because some servers do not
# delete in all cases. RFC says server can respond (in UPDATE
# state only, otherwise always OK).
my $line = $me->_sockread();
unless (defined $line) {
$me->Message("Socket read failed for QUIT");
# XXX: Should add the following?
#$me->State('DEAD');
undef $me->{SOCKET};
return 0;
}
$me->Message( $line );
close( $me->Socket() ) or $me->Message("close failed: $!") and do {
undef $me->{SOCKET};
return 0;
};
$me->State('DEAD');
undef $me->{SOCKET};
$line =~ /^\+OK/i || return 0;
}
1;
} # end Close
sub close { Close(@_); }
sub logout { Close(@_); }
#******************************************************************************
#*
#******************************************************************************
sub DESTROY
{
my $me = shift;
$me->Close;
} # end DESTROY
#******************************************************************************
#* Connect to the specified POP server
#******************************************************************************
sub Connect
{
my ($me, $host, $port) = @_;
$host and $me->Host($host);
$port and $me->Port($port);
$me->Close();
my $s = $me->{SOCKET};
$s || do {
if ( $me->{USESSL} ) {
if ( $me->Port() == 110 ) { $me->Port( 995 ); }
eval {
require IO::Socket::SSL;
};
$@ and $me->Message("Could not load IO::Socket::SSL: $@") and return 0;
$s = IO::Socket::SSL->new( PeerAddr => $me->Host(),
PeerPort => $me->Port(),
Proto => "tcp",
Type => SOCK_STREAM,
LocalAddr => $me->LocalAddr(),
Timeout => $me->{TIMEOUT} )
or $me->Message( "could not connect SSL socket [$me->{HOST}, $me->{PORT}]: $!" )
and return 0;
$me->{SOCKET} = $s;
} else {
$s = IO::Socket::INET->new( PeerAddr => $me->Host(),
PeerPort => $me->Port(),
Proto => "tcp",
Type => SOCK_STREAM,
LocalAddr => $me->LocalAddr(),
Timeout => $me->{TIMEOUT} )
or
$me->Message( "could not connect socket [$me->{HOST}, $me->{PORT}]: $!" )
and
return 0;
$me->{SOCKET} = $s;
}
};
$s->autoflush( 1 );
defined(my $msg = $me->_sockread()) or $me->Message("Could not read") and return 0;
chomp $msg;
$me->{BANNER}= $msg;
# add check for servers that return -ERR on connect (not in RFC1939)
$me->Message($msg);
$msg =~ /^\+OK/i || return 0;
my $atom = qr([-_\w!#$%&'*+/=?^`{|}~]+);
$me->{MESG_ID}= $1 if ($msg =~/(<$atom(?:\.$atom)*\@$atom(?:\.$atom)*>)/o);
$me->Message($msg);
$me->State('AUTHORIZATION');
defined($me->User()) and defined($me->Pass()) and $me->Login();
} # end Connect
sub connect { Connect(@_); }
#******************************************************************************
#* login to the POP server. If the AUTH_MODE is set to BEST, and the server
#* appears to support APOP, it will try APOP, if that fails, then it will try
#* SASL CRAM-MD5 if the server appears to support it, and finally PASS.
#* If the AUTH_MODE is set to APOP, and the server appears to support APOP, it
#* will use APOP or it will fail to log in. Likewise, for AUTH_MODE CRAM-MD5,
#* no PASS-fallback is made. Otherwise password is sent in clear text.
#******************************************************************************
sub Login
{
my $me= shift;
return 1 if $me->State eq 'TRANSACTION'; # Already logged in
if ($me->{AUTH_MODE} eq 'BEST') {
my $retval;
lib/Mail/POP3Client.pm view on Meta::CPAN
# Macs seem to leave CR's or LF's sitting on the socket. This
# removes them.
$me->{STRIPCR} && ($line =~ s/^[\r]+//);
$me->Debug and Carp::carp "POP3 <- ", $line;
$line =~ /^[\\+\\-](OK|ERR)/i && do {
my $l = $line;
chomp $l;
push(@{$me->{tranlog}}, $l);
};
return $line;
}
# end package Mail::POP3Client
# Autoload methods go after =cut, and are processed by the autosplit program.
1;
__END__
################################################################################
# POD Documentation (perldoc Mail::POP3Client or pod2html this_file)
################################################################################
=head1 NAME
Mail::POP3Client - Perl 5 module to talk to a POP3 (RFC1939) server
=head1 SYNOPSIS
use Mail::POP3Client;
$pop = new Mail::POP3Client( USER => "me",
PASSWORD => "mypassword",
HOST => "pop3.do.main" );
for( $i = 1; $i <= $pop->Count(); $i++ ) {
foreach( $pop->Head( $i ) ) {
/^(From|Subject):\s+/i && print $_, "\n";
}
}
$pop->Close();
# OR with SSL
$pop = new Mail::POP3Client( USER => "me",
PASSWORD => "mypassword",
HOST => "pop3.do.main",
USESSL => true,
);
# OR
$pop2 = new Mail::POP3Client( HOST => "pop3.otherdo.main" );
$pop2->User( "somebody" );
$pop2->Pass( "doublesecret" );
$pop2->Connect() >= 0 || die $pop2->Message();
$pop2->Close();
# OR to use your own SSL socket...
my $socket = IO::Socket::SSL->new( PeerAddr => 'pop.securedo.main',
PeerPort => 993,
Proto => 'tcp') || die "No socket!";
my $pop = Mail::POP3Client->new();
$pop->User('somebody');
$pop->Pass('doublesecret');
$pop->Socket($socket);
$pop->Connect();
=head1 DESCRIPTION
This module implements an Object-Oriented interface to a POP3 server.
It implements RFC1939 (http://www.faqs.org/rfcs/rfc1939.html)
=head1 EXAMPLES
Here is a simple example to list out the From: and Subject: headers in
your remote mailbox:
#!/usr/local/bin/perl
use Mail::POP3Client;
$pop = new Mail::POP3Client( USER => "me",
PASSWORD => "mypassword",
HOST => "pop3.do.main" );
for ($i = 1; $i <= $pop->Count(); $i++) {
foreach ( $pop->Head( $i ) ) {
/^(From|Subject):\s+/i and print $_, "\n";
}
print "\n";
}
=head1 CONSTRUCTORS
Old style (deprecated):
new Mail::POP3Client( USER, PASSWORD [, HOST, PORT, DEBUG, AUTH_MODE] );
New style (shown with defaults):
new Mail::POP3Client( USER => "",
PASSWORD => "",
HOST => "pop3",
PORT => 110,
AUTH_MODE => 'BEST',
DEBUG => 0,
TIMEOUT => 60,
LOCALADDR => 'xxx.xxx.xxx.xxx[:xx]',
SOCKET => undef,
USESSL => 0,
);
=over 4
=item *
USER is the userID of the account on the POP server
=item *
PASSWORD is the cleartext password for the userID
=item *
HOST is the POP server name or IP address (default = 'pop3')
lib/Mail/POP3Client.pm view on Meta::CPAN
=item *
AUTH_MODE - pass 'APOP' to force APOP (MD5) authorization. (default is 'BEST')
=item *
TIMEOUT - set a timeout value for socket operations (default = 60)
=item *
LOCALADDR - allow selecting a local inet address to use
=back
=head1 METHODS
These commands are intended to make writing a POP3 client easier.
They do not necessarily map directly to POP3 commands defined in
RFC1081 or RFC1939, although all commands should be supported. Some
commands return multiple lines as an array in an array context.
=over 8
=item I<new>( USER => 'user', PASSWORD => 'password', HOST => 'host',
PORT => 110, DEBUG => 0, AUTH_MODE => 'BEST', TIMEOUT => 60,,
LOCALADDR => 'xxx.xxx.xxx.xxx[:xx]', SOCKET => undef, USESSL => 0 )
)
Construct a new POP3 connection with this. You should use the
hash-style constructor. B<The old positional constructor is
deprecated and will be removed in a future release. It is strongly
recommended that you convert your code to the new version.>
You should give it at least 2 arguments: USER and PASSWORD. The
default HOST is 'pop3' which may or may not work for you. You can
specify a different PORT (be careful here).
new will attempt to Connect to and Login to the POP3 server if you
supply a USER and PASSWORD. If you do not supply them in the
constructor, you will need to call Connect yourself.
The valid values for AUTH_MODE are 'BEST', 'PASS', 'APOP' and 'CRAM-MD5'.
BEST says to try APOP if the server appears to support it and it can be
used to successfully log on, next try similarly with CRAM-MD5, and finally
revert to PASS. APOP and CRAM-MD5 imply that an MD5 checksum will be
used instead of sending your password in cleartext. However,
B<if the server does not claim to support APOP or CRAM-MD5,
the cleartext method will be used. Be careful.> There are a few
servers that will send a timestamp in the banner greeting, but APOP
will not work with them (for instance if the server does not know your
password in cleartext). If you think your authentication information
is correct, run in DEBUG mode and look for errors regarding
authorization. If so, then you may have to use 'PASS' for that server.
The same applies to CRAM-MD5, too.
If you enable debugging with DEBUG => 1, socket traffic will be echoed
to STDERR.
Another warning, it's impossible to differentiate between a timeout
and a failure.
If you pass a true value for USESSL, the port will be changed to 995 if
it is not set or is 110. Otherwise, it will use your port. If USESSL
is true, IO::Socket::SSL will be loaded. If it is not in your perl,
the call to connect will fail.
new returns a valid Mail::POP3Client object in all cases. To test for
a connection failure, you will need to check the number of messages:
-1 indicates a connection error. This will likely change sometime in
the future to return undef on an error, setting $! as a side effect.
This change will not happen in any 2.x version.
=item I<Head>( MESSAGE_NUMBER [, PREVIEW_LINES ] )
Get the headers of the specified message, either as an array or as a
string, depending on context.
You can also specify a number of preview lines which will be returned
with the headers. This may not be supported by all POP3 server
implementations as it is marked as optional in the RFC. Submitted by
Dennis Moroney <dennis@hub.iwl.net>.
=item I<Body>( MESSAGE_NUMBER )
Get the body of the specified message, either as an array of lines or
as a string, depending on context.
=item I<BodyToFile>( FILE_HANDLE, MESSAGE_NUMBER )
Get the body of the specified message and write it to the given file handle.
my $fh = new IO::Handle();
$fh->fdopen( fileno( STDOUT ), "w" );
$pop->BodyToFile( $fh, 1 );
Does no stripping of NL or CR.
=item I<HeadAndBody>( MESSAGE_NUMBER )
Get the head and body of the specified message, either as an array of
lines or as a string, depending on context.
=over 4
=item Example
foreach ( $pop->HeadAndBody( 1 ) )
print $_, "\n";
prints out the complete text of message 1.
=back
=item I<HeadAndBodyToFile>( FILE_HANDLE, MESSAGE_NUMBER )
Get the head and body of the specified message and write it to the given file handle.
my $fh = new IO::Handle();
$fh->fdopen( fileno( STDOUT ), "w" );
$pop->HeadAndBodyToFile( $fh, 1 );
Does no stripping of NL or CR.
=item I<Retrieve>( MESSAGE_NUMBER )
( run in 3.302 seconds using v1.01-cache-2.11-cpan-39bf76dae61 )