| 1 |
# Net::POP3.pm |
| 2 |
# |
| 3 |
# Copyright (c) 1995-2004 Graham Barr <gbarr@pobox.com>. All rights reserved. |
| 4 |
# This program is free software; you can redistribute it and/or |
| 5 |
# modify it under the same terms as Perl itself. |
| 6 |
|
| 7 |
package Net::POP3; |
| 8 |
|
| 9 |
use strict; |
| 10 |
use IO::Socket; |
| 11 |
use vars qw(@ISA $VERSION $debug); |
| 12 |
use Net::Cmd; |
| 13 |
use Carp; |
| 14 |
use Net::Config; |
| 15 |
|
| 16 |
$VERSION = "2.28"; |
| 17 |
|
| 18 |
@ISA = qw(Net::Cmd IO::Socket::INET); |
| 19 |
|
| 20 |
sub new |
| 21 |
{ |
| 22 |
my $self = shift; |
| 23 |
my $type = ref($self) || $self; |
| 24 |
my ($host,%arg); |
| 25 |
if (@_ % 2) { |
| 26 |
$host = shift ; |
| 27 |
%arg = @_; |
| 28 |
} else { |
| 29 |
%arg = @_; |
| 30 |
$host=delete $arg{Host}; |
| 31 |
} |
| 32 |
my $hosts = defined $host ? [ $host ] : $NetConfig{pop3_hosts}; |
| 33 |
my $obj; |
| 34 |
my @localport = exists $arg{ResvPort} ? ( LocalPort => $arg{ResvPort} ): (); |
| 35 |
|
| 36 |
my $h; |
| 37 |
foreach $h (@{$hosts}) |
| 38 |
{ |
| 39 |
$obj = $type->SUPER::new(PeerAddr => ($host = $h), |
| 40 |
PeerPort => $arg{Port} || 'pop3(110)', |
| 41 |
Proto => 'tcp', |
| 42 |
@localport, |
| 43 |
Timeout => defined $arg{Timeout} |
| 44 |
? $arg{Timeout} |
| 45 |
: 120 |
| 46 |
) and last; |
| 47 |
} |
| 48 |
|
| 49 |
return undef |
| 50 |
unless defined $obj; |
| 51 |
|
| 52 |
${*$obj}{'net_pop3_host'} = $host; |
| 53 |
|
| 54 |
$obj->autoflush(1); |
| 55 |
$obj->debug(exists $arg{Debug} ? $arg{Debug} : undef); |
| 56 |
|
| 57 |
unless ($obj->response() == CMD_OK) |
| 58 |
{ |
| 59 |
$obj->close(); |
| 60 |
return undef; |
| 61 |
} |
| 62 |
|
| 63 |
${*$obj}{'net_pop3_banner'} = $obj->message; |
| 64 |
|
| 65 |
$obj; |
| 66 |
} |
| 67 |
|
| 68 |
sub host { |
| 69 |
my $me = shift; |
| 70 |
${*$me}{'net_pop3_host'}; |
| 71 |
} |
| 72 |
|
| 73 |
## |
| 74 |
## We don't want people sending me their passwords when they report problems |
| 75 |
## now do we :-) |
| 76 |
## |
| 77 |
|
| 78 |
sub debug_text { $_[2] =~ /^(pass|rpop)/i ? "$1 ....\n" : $_[2]; } |
| 79 |
|
| 80 |
sub login |
| 81 |
{ |
| 82 |
@_ >= 1 && @_ <= 3 or croak 'usage: $pop3->login( USER, PASS )'; |
| 83 |
my($me,$user,$pass) = @_; |
| 84 |
|
| 85 |
if (@_ <= 2) { |
| 86 |
($user, $pass) = $me->_lookup_credentials($user); |
| 87 |
} |
| 88 |
|
| 89 |
$me->user($user) and |
| 90 |
$me->pass($pass); |
| 91 |
} |
| 92 |
|
| 93 |
sub apop |
| 94 |
{ |
| 95 |
@_ >= 1 && @_ <= 3 or croak 'usage: $pop3->apop( USER, PASS )'; |
| 96 |
my($me,$user,$pass) = @_; |
| 97 |
my $banner; |
| 98 |
my $md; |
| 99 |
|
| 100 |
if (eval { local $SIG{__DIE__}; require Digest::MD5 }) { |
| 101 |
$md = Digest::MD5->new(); |
| 102 |
} elsif (eval { local $SIG{__DIE__}; require MD5 }) { |
| 103 |
$md = MD5->new(); |
| 104 |
} else { |
| 105 |
carp "You need to install Digest::MD5 or MD5 to use the APOP command"; |
| 106 |
return undef; |
| 107 |
} |
| 108 |
|
| 109 |
return undef |
| 110 |
unless ( $banner = (${*$me}{'net_pop3_banner'} =~ /(<.*>)/)[0] ); |
| 111 |
|
| 112 |
if (@_ <= 2) { |
| 113 |
($user, $pass) = $me->_lookup_credentials($user); |
| 114 |
} |
| 115 |
|
| 116 |
$md->add($banner,$pass); |
| 117 |
|
| 118 |
return undef |
| 119 |
unless($me->_APOP($user,$md->hexdigest)); |
| 120 |
|
| 121 |
$me->_get_mailbox_count(); |
| 122 |
} |
| 123 |
|
| 124 |
sub user |
| 125 |
{ |
| 126 |
@_ == 2 or croak 'usage: $pop3->user( USER )'; |
| 127 |
$_[0]->_USER($_[1]) ? 1 : undef; |
| 128 |
} |
| 129 |
|
| 130 |
sub pass |
| 131 |
{ |
| 132 |
@_ == 2 or croak 'usage: $pop3->pass( PASS )'; |
| 133 |
|
| 134 |
my($me,$pass) = @_; |
| 135 |
|
| 136 |
return undef |
| 137 |
unless($me->_PASS($pass)); |
| 138 |
|
| 139 |
$me->_get_mailbox_count(); |
| 140 |
} |
| 141 |
|
| 142 |
sub reset |
| 143 |
{ |
| 144 |
@_ == 1 or croak 'usage: $obj->reset()'; |
| 145 |
|
| 146 |
my $me = shift; |
| 147 |
|
| 148 |
return 0 |
| 149 |
unless($me->_RSET); |
| 150 |
|
| 151 |
if(defined ${*$me}{'net_pop3_mail'}) |
| 152 |
{ |
| 153 |
local $_; |
| 154 |
foreach (@{${*$me}{'net_pop3_mail'}}) |
| 155 |
{ |
| 156 |
delete $_->{'net_pop3_deleted'}; |
| 157 |
} |
| 158 |
} |
| 159 |
} |
| 160 |
|
| 161 |
sub last |
| 162 |
{ |
| 163 |
@_ == 1 or croak 'usage: $obj->last()'; |
| 164 |
|
| 165 |
return undef |
| 166 |
unless $_[0]->_LAST && $_[0]->message =~ /(\d+)/; |
| 167 |
|
| 168 |
return $1; |
| 169 |
} |
| 170 |
|
| 171 |
sub top |
| 172 |
{ |
| 173 |
@_ == 2 || @_ == 3 or croak 'usage: $pop3->top( MSGNUM [, NUMLINES ])'; |
| 174 |
my $me = shift; |
| 175 |
|
| 176 |
return undef |
| 177 |
unless $me->_TOP($_[0], $_[1] || 0); |
| 178 |
|
| 179 |
$me->read_until_dot; |
| 180 |
} |
| 181 |
|
| 182 |
sub popstat |
| 183 |
{ |
| 184 |
@_ == 1 or croak 'usage: $pop3->popstat()'; |
| 185 |
my $me = shift; |
| 186 |
|
| 187 |
return () |
| 188 |
unless $me->_STAT && $me->message =~ /(\d+)\D+(\d+)/; |
| 189 |
|
| 190 |
($1 || 0, $2 || 0); |
| 191 |
} |
| 192 |
|
| 193 |
sub list |
| 194 |
{ |
| 195 |
@_ == 1 || @_ == 2 or croak 'usage: $pop3->list( [ MSGNUM ] )'; |
| 196 |
my $me = shift; |
| 197 |
|
| 198 |
return undef |
| 199 |
unless $me->_LIST(@_); |
| 200 |
|
| 201 |
if(@_) |
| 202 |
{ |
| 203 |
$me->message =~ /\d+\D+(\d+)/; |
| 204 |
return $1 || undef; |
| 205 |
} |
| 206 |
|
| 207 |
my $info = $me->read_until_dot |
| 208 |
or return undef; |
| 209 |
|
| 210 |
my %hash = map { (/(\d+)\D+(\d+)/) } @$info; |
| 211 |
|
| 212 |
return \%hash; |
| 213 |
} |
| 214 |
|
| 215 |
sub get |
| 216 |
{ |
| 217 |
@_ == 2 or @_ == 3 or croak 'usage: $pop3->get( MSGNUM [, FH ])'; |
| 218 |
my $me = shift; |
| 219 |
|
| 220 |
return undef |
| 221 |
unless $me->_RETR(shift); |
| 222 |
|
| 223 |
$me->read_until_dot(@_); |
| 224 |
} |
| 225 |
|
| 226 |
sub getfh |
| 227 |
{ |
| 228 |
@_ == 2 or croak 'usage: $pop3->getfh( MSGNUM )'; |
| 229 |
my $me = shift; |
| 230 |
|
| 231 |
return unless $me->_RETR(shift); |
| 232 |
return $me->tied_fh; |
| 233 |
} |
| 234 |
|
| 235 |
|
| 236 |
|
| 237 |
sub delete |
| 238 |
{ |
| 239 |
@_ == 2 or croak 'usage: $pop3->delete( MSGNUM )'; |
| 240 |
my $me = shift; |
| 241 |
return 0 unless $me->_DELE(@_); |
| 242 |
${*$me}{'net_pop3_deleted'} = 1; |
| 243 |
} |
| 244 |
|
| 245 |
sub uidl |
| 246 |
{ |
| 247 |
@_ == 1 || @_ == 2 or croak 'usage: $pop3->uidl( [ MSGNUM ] )'; |
| 248 |
my $me = shift; |
| 249 |
my $uidl; |
| 250 |
|
| 251 |
$me->_UIDL(@_) or |
| 252 |
return undef; |
| 253 |
if(@_) |
| 254 |
{ |
| 255 |
$uidl = ($me->message =~ /\d+\s+([\041-\176]+)/)[0]; |
| 256 |
} |
| 257 |
else |
| 258 |
{ |
| 259 |
my $ref = $me->read_until_dot |
| 260 |
or return undef; |
| 261 |
my $ln; |
| 262 |
$uidl = {}; |
| 263 |
foreach $ln (@$ref) { |
| 264 |
my($msg,$uid) = $ln =~ /^\s*(\d+)\s+([\041-\176]+)/; |
| 265 |
$uidl->{$msg} = $uid; |
| 266 |
} |
| 267 |
} |
| 268 |
return $uidl; |
| 269 |
} |
| 270 |
|
| 271 |
sub ping |
| 272 |
{ |
| 273 |
@_ == 2 or croak 'usage: $pop3->ping( USER )'; |
| 274 |
my $me = shift; |
| 275 |
|
| 276 |
return () unless $me->_PING(@_) && $me->message =~ /(\d+)\D+(\d+)/; |
| 277 |
|
| 278 |
($1 || 0, $2 || 0); |
| 279 |
} |
| 280 |
|
| 281 |
sub _lookup_credentials |
| 282 |
{ |
| 283 |
my ($me, $user) = @_; |
| 284 |
|
| 285 |
require Net::Netrc; |
| 286 |
|
| 287 |
$user ||= eval { local $SIG{__DIE__}; (getpwuid($>))[0] } || |
| 288 |
$ENV{NAME} || $ENV{USER} || $ENV{LOGNAME}; |
| 289 |
|
| 290 |
my $m = Net::Netrc->lookup(${*$me}{'net_pop3_host'},$user); |
| 291 |
$m ||= Net::Netrc->lookup(${*$me}{'net_pop3_host'}); |
| 292 |
|
| 293 |
my $pass = $m ? $m->password || "" |
| 294 |
: ""; |
| 295 |
|
| 296 |
($user, $pass); |
| 297 |
} |
| 298 |
|
| 299 |
sub _get_mailbox_count |
| 300 |
{ |
| 301 |
my ($me) = @_; |
| 302 |
my $ret = ${*$me}{'net_pop3_count'} = ($me->message =~ /(\d+)\s+message/io) |
| 303 |
? $1 : ($me->popstat)[0]; |
| 304 |
|
| 305 |
$ret ? $ret : "0E0"; |
| 306 |
} |
| 307 |
|
| 308 |
|
| 309 |
sub _STAT { shift->command('STAT')->response() == CMD_OK } |
| 310 |
sub _LIST { shift->command('LIST',@_)->response() == CMD_OK } |
| 311 |
sub _RETR { shift->command('RETR',$_[0])->response() == CMD_OK } |
| 312 |
sub _DELE { shift->command('DELE',$_[0])->response() == CMD_OK } |
| 313 |
sub _NOOP { shift->command('NOOP')->response() == CMD_OK } |
| 314 |
sub _RSET { shift->command('RSET')->response() == CMD_OK } |
| 315 |
sub _QUIT { shift->command('QUIT')->response() == CMD_OK } |
| 316 |
sub _TOP { shift->command('TOP', @_)->response() == CMD_OK } |
| 317 |
sub _UIDL { shift->command('UIDL',@_)->response() == CMD_OK } |
| 318 |
sub _USER { shift->command('USER',$_[0])->response() == CMD_OK } |
| 319 |
sub _PASS { shift->command('PASS',$_[0])->response() == CMD_OK } |
| 320 |
sub _APOP { shift->command('APOP',@_)->response() == CMD_OK } |
| 321 |
sub _PING { shift->command('PING',$_[0])->response() == CMD_OK } |
| 322 |
|
| 323 |
sub _RPOP { shift->command('RPOP',$_[0])->response() == CMD_OK } |
| 324 |
sub _LAST { shift->command('LAST')->response() == CMD_OK } |
| 325 |
|
| 326 |
sub _CAPA { shift->command('CAPA')->response() == CMD_OK } |
| 327 |
|
| 328 |
sub quit |
| 329 |
{ |
| 330 |
my $me = shift; |
| 331 |
|
| 332 |
$me->_QUIT; |
| 333 |
$me->close; |
| 334 |
} |
| 335 |
|
| 336 |
sub DESTROY |
| 337 |
{ |
| 338 |
my $me = shift; |
| 339 |
|
| 340 |
if(defined fileno($me) and ${*$me}{'net_pop3_deleted'}) |
| 341 |
{ |
| 342 |
$me->reset; |
| 343 |
$me->quit; |
| 344 |
} |
| 345 |
} |
| 346 |
|
| 347 |
## |
| 348 |
## POP3 has weird responses, so we emulate them to look the same :-) |
| 349 |
## |
| 350 |
|
| 351 |
sub response { |
| 352 |
my $cmd = shift; |
| 353 |
my $str = $cmd->getline() or return undef; |
| 354 |
my $code = "500"; |
| 355 |
|
| 356 |
$cmd->debug_print(0, $str) |
| 357 |
if ($cmd->debug); |
| 358 |
|
| 359 |
if ($str =~ s/^\+OK\s*//io) { |
| 360 |
$code = "200"; |
| 361 |
} |
| 362 |
elsif ($str =~ s/^\+\s*//io) { |
| 363 |
$code = "300"; |
| 364 |
} |
| 365 |
else { |
| 366 |
$str =~ s/^-ERR\s*//io; |
| 367 |
} |
| 368 |
|
| 369 |
${*$cmd}{'net_cmd_resp'} = [$str]; |
| 370 |
${*$cmd}{'net_cmd_code'} = $code; |
| 371 |
|
| 372 |
substr($code, 0, 1); |
| 373 |
} |
| 374 |
|
| 375 |
|
| 376 |
sub capa { |
| 377 |
my $this = shift; |
| 378 |
my ($capa, %capabilities); |
| 379 |
|
| 380 |
# Fake a capability here |
| 381 |
$capabilities{APOP} = '' if ($this->banner() =~ /<.*>/); |
| 382 |
|
| 383 |
return \%capabilities unless $this->_CAPA(); |
| 384 |
|
| 385 |
$capa = $this->read_until_dot(); |
| 386 |
%capabilities = map { /^\s*(\S+)\s*(.*)/ } @$capa; |
| 387 |
$capabilities{APOP} = '' if ($this->banner() =~ /<.*>/); |
| 388 |
|
| 389 |
return ${*$this}{'net_pop3e_capabilities'} = \%capabilities; |
| 390 |
} |
| 391 |
|
| 392 |
sub capabilities { |
| 393 |
my $this = shift; |
| 394 |
|
| 395 |
${*$this}{'net_pop3e_capabilities'} || $this->capa; |
| 396 |
} |
| 397 |
|
| 398 |
sub auth { |
| 399 |
my ($self, $username, $password) = @_; |
| 400 |
|
| 401 |
eval { |
| 402 |
require MIME::Base64; |
| 403 |
require Authen::SASL; |
| 404 |
} or $self->set_status(500,["Need MIME::Base64 and Authen::SASL todo auth"]), return 0; |
| 405 |
|
| 406 |
my $capa = $self->capa; |
| 407 |
my $mechanisms = $capa->{SASL} || 'CRAM-MD5'; |
| 408 |
|
| 409 |
my $sasl; |
| 410 |
|
| 411 |
if (ref($username) and UNIVERSAL::isa($username,'Authen::SASL')) { |
| 412 |
$sasl = $username; |
| 413 |
$sasl->mechanism($mechanisms); |
| 414 |
} |
| 415 |
else { |
| 416 |
die "auth(username, password)" if not length $username; |
| 417 |
$sasl = Authen::SASL->new(mechanism=> $mechanisms, |
| 418 |
callback => { user => $username, |
| 419 |
pass => $password, |
| 420 |
authname => $username, |
| 421 |
}); |
| 422 |
} |
| 423 |
|
| 424 |
# We should probably allow the user to pass the host, but I don't |
| 425 |
# currently know and SASL mechanisms that are used by smtp that need it |
| 426 |
my $client = $sasl->client_new('pop3',${*$self}{'net_pop3_host'},0); |
| 427 |
my $str = $client->client_start; |
| 428 |
|
| 429 |
# We dont support sasl mechanisms that encrypt the socket traffic. |
| 430 |
# todo that we would really need to change the ISA hierarchy |
| 431 |
# so we dont inherit from IO::Socket, but instead hold it in an attribute |
| 432 |
|
| 433 |
my @cmd = ("AUTH", $client->mechanism); |
| 434 |
my $code; |
| 435 |
|
| 436 |
push @cmd, MIME::Base64::encode_base64($str,'') |
| 437 |
if defined $str and length $str; |
| 438 |
|
| 439 |
while (($code = $self->command(@cmd)->response()) == CMD_MORE) { |
| 440 |
@cmd = (MIME::Base64::encode_base64( |
| 441 |
$client->client_step( |
| 442 |
MIME::Base64::decode_base64( |
| 443 |
($self->message)[0] |
| 444 |
) |
| 445 |
), '' |
| 446 |
)); |
| 447 |
} |
| 448 |
|
| 449 |
$code == CMD_OK; |
| 450 |
} |
| 451 |
|
| 452 |
sub banner { |
| 453 |
my $this = shift; |
| 454 |
|
| 455 |
return ${*$this}{'net_pop3_banner'}; |
| 456 |
} |
| 457 |
|
| 458 |
1; |
| 459 |
|
| 460 |
__END__ |
| 461 |
|
| 462 |
=head1 NAME |
| 463 |
|
| 464 |
Net::POP3 - Post Office Protocol 3 Client class (RFC1939) |
| 465 |
|
| 466 |
=head1 SYNOPSIS |
| 467 |
|
| 468 |
use Net::POP3; |
| 469 |
|
| 470 |
# Constructors |
| 471 |
$pop = Net::POP3->new('pop3host'); |
| 472 |
$pop = Net::POP3->new('pop3host', Timeout => 60); |
| 473 |
|
| 474 |
if ($pop->login($username, $password) > 0) { |
| 475 |
my $msgnums = $pop->list; # hashref of msgnum => size |
| 476 |
foreach my $msgnum (keys %$msgnums) { |
| 477 |
my $msg = $pop->get($msgnum); |
| 478 |
print @$msg; |
| 479 |
$pop->delete($msgnum); |
| 480 |
} |
| 481 |
} |
| 482 |
|
| 483 |
$pop->quit; |
| 484 |
|
| 485 |
=head1 DESCRIPTION |
| 486 |
|
| 487 |
This module implements a client interface to the POP3 protocol, enabling |
| 488 |
a perl5 application to talk to POP3 servers. This documentation assumes |
| 489 |
that you are familiar with the POP3 protocol described in RFC1939. |
| 490 |
|
| 491 |
A new Net::POP3 object must be created with the I<new> method. Once |
| 492 |
this has been done, all POP3 commands are accessed via method calls |
| 493 |
on the object. |
| 494 |
|
| 495 |
=head1 CONSTRUCTOR |
| 496 |
|
| 497 |
=over 4 |
| 498 |
|
| 499 |
=item new ( [ HOST ] [, OPTIONS ] 0 |
| 500 |
|
| 501 |
This is the constructor for a new Net::POP3 object. C<HOST> is the |
| 502 |
name of the remote host to which an POP3 connection is required. |
| 503 |
|
| 504 |
C<HOST> is optional. If C<HOST> is not given then it may instead be |
| 505 |
passed as the C<Host> option described below. If neither is given then |
| 506 |
the C<POP3_Hosts> specified in C<Net::Config> will be used. |
| 507 |
|
| 508 |
C<OPTIONS> are passed in a hash like fashion, using key and value pairs. |
| 509 |
Possible options are: |
| 510 |
|
| 511 |
B<Host> - POP3 host to connect to. It may be a single scalar, as defined for |
| 512 |
the C<PeerAddr> option in L<IO::Socket::INET>, or a reference to |
| 513 |
an array with hosts to try in turn. The L</host> method will return the value |
| 514 |
which was used to connect to the host. |
| 515 |
|
| 516 |
B<ResvPort> - If given then the socket for the C<Net::POP3> object |
| 517 |
will be bound to the local port given using C<bind> when the socket is |
| 518 |
created. |
| 519 |
|
| 520 |
B<Timeout> - Maximum time, in seconds, to wait for a response from the |
| 521 |
POP3 server (default: 120) |
| 522 |
|
| 523 |
B<Debug> - Enable debugging information |
| 524 |
|
| 525 |
=back |
| 526 |
|
| 527 |
=head1 METHODS |
| 528 |
|
| 529 |
Unless otherwise stated all methods return either a I<true> or I<false> |
| 530 |
value, with I<true> meaning that the operation was a success. When a method |
| 531 |
states that it returns a value, failure will be returned as I<undef> or an |
| 532 |
empty list. |
| 533 |
|
| 534 |
=over 4 |
| 535 |
|
| 536 |
=item auth ( USERNAME, PASSWORD ) |
| 537 |
|
| 538 |
Attempt SASL authentication. |
| 539 |
|
| 540 |
=item user ( USER ) |
| 541 |
|
| 542 |
Send the USER command. |
| 543 |
|
| 544 |
=item pass ( PASS ) |
| 545 |
|
| 546 |
Send the PASS command. Returns the number of messages in the mailbox. |
| 547 |
|
| 548 |
=item login ( [ USER [, PASS ]] ) |
| 549 |
|
| 550 |
Send both the USER and PASS commands. If C<PASS> is not given the |
| 551 |
C<Net::POP3> uses C<Net::Netrc> to lookup the password using the host |
| 552 |
and username. If the username is not specified then the current user name |
| 553 |
will be used. |
| 554 |
|
| 555 |
Returns the number of messages in the mailbox. However if there are no |
| 556 |
messages on the server the string C<"0E0"> will be returned. This is |
| 557 |
will give a true value in a boolean context, but zero in a numeric context. |
| 558 |
|
| 559 |
If there was an error authenticating the user then I<undef> will be returned. |
| 560 |
|
| 561 |
=item apop ( [ USER [, PASS ]] ) |
| 562 |
|
| 563 |
Authenticate with the server identifying as C<USER> with password C<PASS>. |
| 564 |
Similar to L</login>, but the password is not sent in clear text. |
| 565 |
|
| 566 |
To use this method you must have the Digest::MD5 or the MD5 module installed, |
| 567 |
otherwise this method will return I<undef>. |
| 568 |
|
| 569 |
=item banner () |
| 570 |
|
| 571 |
Return the sever's connection banner |
| 572 |
|
| 573 |
=item capa () |
| 574 |
|
| 575 |
Return a reference to a hash of the capabilties of the server. APOP |
| 576 |
is added as a pseudo capability. Note that I've been unable to |
| 577 |
find a list of the standard capability values, and some appear to |
| 578 |
be multi-word and some are not. We make an attempt at intelligently |
| 579 |
parsing them, but it may not be correct. |
| 580 |
|
| 581 |
=item capabilities () |
| 582 |
|
| 583 |
Just like capa, but only uses a cache from the last time we asked |
| 584 |
the server, so as to avoid asking more than once. |
| 585 |
|
| 586 |
=item top ( MSGNUM [, NUMLINES ] ) |
| 587 |
|
| 588 |
Get the header and the first C<NUMLINES> of the body for the message |
| 589 |
C<MSGNUM>. Returns a reference to an array which contains the lines of text |
| 590 |
read from the server. |
| 591 |
|
| 592 |
=item list ( [ MSGNUM ] ) |
| 593 |
|
| 594 |
If called with an argument the C<list> returns the size of the message |
| 595 |
in octets. |
| 596 |
|
| 597 |
If called without arguments a reference to a hash is returned. The |
| 598 |
keys will be the C<MSGNUM>'s of all undeleted messages and the values will |
| 599 |
be their size in octets. |
| 600 |
|
| 601 |
=item get ( MSGNUM [, FH ] ) |
| 602 |
|
| 603 |
Get the message C<MSGNUM> from the remote mailbox. If C<FH> is not given |
| 604 |
then get returns a reference to an array which contains the lines of |
| 605 |
text read from the server. If C<FH> is given then the lines returned |
| 606 |
from the server are printed to the filehandle C<FH>. |
| 607 |
|
| 608 |
=item getfh ( MSGNUM ) |
| 609 |
|
| 610 |
As per get(), but returns a tied filehandle. Reading from this |
| 611 |
filehandle returns the requested message. The filehandle will return |
| 612 |
EOF at the end of the message and should not be reused. |
| 613 |
|
| 614 |
=item last () |
| 615 |
|
| 616 |
Returns the highest C<MSGNUM> of all the messages accessed. |
| 617 |
|
| 618 |
=item popstat () |
| 619 |
|
| 620 |
Returns a list of two elements. These are the number of undeleted |
| 621 |
elements and the size of the mbox in octets. |
| 622 |
|
| 623 |
=item ping ( USER ) |
| 624 |
|
| 625 |
Returns a list of two elements. These are the number of new messages |
| 626 |
and the total number of messages for C<USER>. |
| 627 |
|
| 628 |
=item uidl ( [ MSGNUM ] ) |
| 629 |
|
| 630 |
Returns a unique identifier for C<MSGNUM> if given. If C<MSGNUM> is not |
| 631 |
given C<uidl> returns a reference to a hash where the keys are the |
| 632 |
message numbers and the values are the unique identifiers. |
| 633 |
|
| 634 |
=item delete ( MSGNUM ) |
| 635 |
|
| 636 |
Mark message C<MSGNUM> to be deleted from the remote mailbox. All messages |
| 637 |
that are marked to be deleted will be removed from the remote mailbox |
| 638 |
when the server connection closed. |
| 639 |
|
| 640 |
=item reset () |
| 641 |
|
| 642 |
Reset the status of the remote POP3 server. This includes reseting the |
| 643 |
status of all messages to not be deleted. |
| 644 |
|
| 645 |
=item quit () |
| 646 |
|
| 647 |
Quit and close the connection to the remote POP3 server. Any messages marked |
| 648 |
as deleted will be deleted from the remote mailbox. |
| 649 |
|
| 650 |
=back |
| 651 |
|
| 652 |
=head1 NOTES |
| 653 |
|
| 654 |
If a C<Net::POP3> object goes out of scope before C<quit> method is called |
| 655 |
then the C<reset> method will called before the connection is closed. This |
| 656 |
means that any messages marked to be deleted will not be. |
| 657 |
|
| 658 |
=head1 SEE ALSO |
| 659 |
|
| 660 |
L<Net::Netrc>, |
| 661 |
L<Net::Cmd> |
| 662 |
|
| 663 |
=head1 AUTHOR |
| 664 |
|
| 665 |
Graham Barr <gbarr@pobox.com> |
| 666 |
|
| 667 |
=head1 COPYRIGHT |
| 668 |
|
| 669 |
Copyright (c) 1995-2003 Graham Barr. All rights reserved. |
| 670 |
This program is free software; you can redistribute it and/or modify |
| 671 |
it under the same terms as Perl itself. |
| 672 |
|
| 673 |
=cut |
