=head1 NAME
Mail::Transport::POP3 - receive messages via POP3
=head1 INHERITANCE
Mail::Transport::POP3
is a Mail::Transport::Receive
is a Mail::Transport
is a Mail::Reporter
=head1 SYNOPSIS
my
$receiver
= Mail::Transport::POP3->new(...);
my
$message
=
$receiver
->receive(
$id
);
=head1 DESCRIPTION
Receive messages via the POP3 protocol from one remote server, as specified
in rfc1939. This object hides much of the complications in the protocol and
recovers broken connections automatically. Although it is part of the
MailBox distribution, this object can be used separately.
You probably should B<not
use
this> module, but L<Mail::Box::POP3|Mail::Box::POP3>. This
module is the interface to POP3, whereas L<Mail::Box::POP3|Mail::Box::POP3> hides the
protocol weirdness and works as any other mail folder.
=head1 METHODS
=head2 Constructors
Mail::Transport::POP3-E<gt>B<new>(OPTIONS)
=over 4
Create a new pop3 server connection. One object can only handle one
connection:
for
a single user to one single server. If the server
could not be reached, or
when
the login fails, this instantiating C<new>
will
return
C<
undef
>.
Option --Defined in --Default
authenticate
'AUTO'
executable Mail::Transport
undef
hostname Mail::Transport
'localhost'
interval Mail::Transport 30
log
Mail::Reporter
'WARNINGS'
password Mail::Transport
undef
port Mail::Transport 110
proxy Mail::Transport
undef
retry Mail::Transport <false>
timeout Mail::Transport 120
trace Mail::Reporter
'WARNINGS'
username Mail::Transport
undef
via Mail::Transport
'sendmail'
. authenticate
'LOGIN'
|
'APOP'
|
'AUTO'
=over 4
Authenthication method. The standard defines two methods, named LOGIN and
APOP. The first sends the username and password in plain text to the server
to get permission, the latter encrypts this data using MD5. When AUTO is
used, first APOP is tried, and then LOGIN.
=back
. executable FILENAME
. hostname HOSTNAME|ARRAY-OF-HOSTNAMES
. interval SECONDS
.
log
LEVEL
. password STRING
. port INTEGER
. proxy PATH
. retry NUMBER|
undef
. timeout SECONDS
. trace LEVEL
. username STRING
. via CLASS|NAME
=back
=head2 Receiving mail
$obj
-E<gt>B<receive>([UNIQUE-MESSAGE-ID])
=over 4
See L<Mail::Transport::Receive/
"Receiving mail"
>
=back
=head2 Exchanging information
$obj
-E<gt>B<deleteFetched>
=over 4
Mark all messages that have been fetched
with
L<message()|Mail::Transport::POP3/
"Exchanging information"
>
for
deletion.
See L<fetched()|Mail::Transport::POP3/
"Exchanging information"
>.
=back
$obj
-E<gt>B<deleted>(BOOLEAN, ID's)
=over 4
Either mark the specified message(s) to be deleted on the remote server or
unmark them
for
deletion (
if
the first parameter is false). Deletion of
messages will take place B<only>
when
the connection is specifically
disconnected or the
last
reference to the object goes out of scope.
=back
$obj
-E<gt>B<disconnect>
=over 4
Break contact
with
the server,
if
that (still)
exists
. Returns true
if
successful. Please note that even
if
the disconnect was not successful,
all knowledge of messages etc. will be removed from the object: the object
basically
has
reverted to the state in which it was
before
anything was done
with
the mail box.
=back
$obj
-E<gt>B<fetched>
=over 4
Returns a reference to a list of ID's that have been fetched using
L<message()|Mail::Transport::POP3/
"Exchanging information"
>. This can be used to update a database of messages that
were fetched (but maybe not yet deleted) from the mailbox.
Please note that
if
the POP3 server did not support the UIDL command, this
method will always
return
undef
because it is not possibly to reliably
identify messages between sessions (other than looking at the contents of
the messages themselves).
See also L<deleteFetched()|Mail::Transport::POP3/
"Exchanging information"
>.
=back
$obj
-E<gt>B<folderSize>
=over 4
Returns the total number of octets used by the mailbox on the remote server.
=back
$obj
-E<gt>B<header>(ID, [BODYLINES])
=over 4
Returns a reference to an array which contains the header of the message
with
the specified ID. C<
undef
> is returned
if
something
has
gone wrong.
The optional integer BODYLINES specifies the number of lines from the body
which should be added, by
default
none.
I<Example:>
my
$ref_lines
=
$pop3
->header(
$uidl
);
print
@$ref_lines
;
=back
$obj
-E<gt>B<id2n>(ID)
=over 4
Translates the unique ID of a message into a sequence number which
represents the message as long a this connection to the POP3 server
exists
. When the message
has
been deleted
for
some reason, C<
undef
>
is returned.
=back
$obj
-E<gt>B<ids>
=over 4
Returns a list (in list context) or a reference to a list (in
scalar
context)
of all ID's which are known by the server on this moment.
=back
$obj
-E<gt>B<message>(ID)
=over 4
Returns a reference to an array which contains the lines of the
message
with
the specified ID. Returns C<
undef
>
if
something
has
gone
wrong.
I<Example:>
my
$ref_lines
=
$pop3
->message(
$uidl
);
print
@$ref_lines
;
=back
$obj
-E<gt>B<messageSize>(ID)
=over 4
Returns the size of the message which is indicated by the ID, in octets.
If the message
has
been deleted on the remote server, this will
return
C<
undef
>.
=back
$obj
-E<gt>B<messages>
=over 4
Returns (in
scalar
context only) the number of messages that are known
to exist in the mailbox.
=back
=head2 Protocol internals
The follow methods handle protocol internals, and should not be used
by a normal user of this class.
$obj
-E<gt>B<login>
=over 4
Establish a new connection to the POP3 server, using username and password.
=back
$obj
-E<gt>B<
send
>(SOCKET, data)
=over 4
Send data to the indicated
socket
and
return
the first line
read
from
that
socket
. Logs an error
if
either writing to or reading from
socket
failed.
This method does B<not> attempt to reconnect or anything:
if
reading or
writing the
socket
fails, something is very definitely wrong.
=back
$obj
-E<gt>B<sendList>(SOCKET, COMMAND)
=over 4
Sends the indicated COMMAND to the specified
socket
, and retrieves the
response. It returns a reference to an array
with
all the lines that
were reveived
after
the first C<+OK> line and
before
the end-of-message
delimiter (a single dot on a line). Returns C<
undef
>
whenever something
has
gone wrong.
=back
$obj
-E<gt>B<
socket
>
=over 4
Returns a connection to the POP3 server. If there was
no
connection yet,
it will be created transparently. If the connection
with
the POP3 server
was lost, it will be reconnected and the assures that internal
state information (STAT and UIDL) is up-to-date in the object.
If the contact to the server was still present, or could be established,
an IO::Socket::INET object is returned. Else, C<
undef
> is returned and
no
further actions should be tried on the object.
=back
$obj
-E<gt>B<status>(SOCKET)
=over 4
Update the current status of folder on the remote POP3 server.
=back
=head2 Server connection
$obj
-E<gt>B<findBinary>(NAME [, DIRECTORIES])
=over 4
See L<Mail::Transport/
"Server connection"
>
=back
$obj
-E<gt>B<remoteHost>
=over 4
See L<Mail::Transport/
"Server connection"
>
=back
$obj
-E<gt>B<retry>
=over 4
See L<Mail::Transport/
"Server connection"
>
=back
$obj
-E<gt>B<url>
=over 4
Represent this pop3 connection as URL.
=back
=head2 Error handling
$obj
-E<gt>B<AUTOLOAD>
=over 4
See L<Mail::Reporter/
"Error handling"
>
=back
$obj
-E<gt>B<addReport>(OBJECT)
=over 4
See L<Mail::Reporter/
"Error handling"
>
=back
$obj
-E<gt>B<defaultTrace>([LEVEL]|[LOGLEVEL, TRACELEVEL]|[LEVEL, CALLBACK])
Mail::Transport::POP3-E<gt>B<defaultTrace>([LEVEL]|[LOGLEVEL, TRACELEVEL]|[LEVEL, CALLBACK])
=over 4
See L<Mail::Reporter/
"Error handling"
>
=back
$obj
-E<gt>B<errors>
=over 4
See L<Mail::Reporter/
"Error handling"
>
=back
$obj
-E<gt>B<
log
>([LEVEL [,STRINGS]])
Mail::Transport::POP3-E<gt>B<
log
>([LEVEL [,STRINGS]])
=over 4
See L<Mail::Reporter/
"Error handling"
>
=back
$obj
-E<gt>B<logPriority>(LEVEL)
Mail::Transport::POP3-E<gt>B<logPriority>(LEVEL)
=over 4
See L<Mail::Reporter/
"Error handling"
>
=back
$obj
-E<gt>B<logSettings>
=over 4
See L<Mail::Reporter/
"Error handling"
>
=back
$obj
-E<gt>B<notImplemented>
=over 4
See L<Mail::Reporter/
"Error handling"
>
=back
$obj
-E<gt>B<report>([LEVEL])
=over 4
See L<Mail::Reporter/
"Error handling"
>
=back
$obj
-E<gt>B<reportAll>([LEVEL])
=over 4
See L<Mail::Reporter/
"Error handling"
>
=back
$obj
-E<gt>B<trace>([LEVEL])
=over 4
See L<Mail::Reporter/
"Error handling"
>
=back
$obj
-E<gt>B<warnings>
=over 4
See L<Mail::Reporter/
"Error handling"
>
=back
=head2 Cleanup
$obj
-E<gt>B<DESTROY>
=over 4
See L<Mail::Reporter/
"Cleanup"
>
=back
$obj
-E<gt>B<inGlobalDestruction>
=over 4
See L<Mail::Reporter/
"Cleanup"
>
=back
=head1 DIAGNOSTICS
I<Error:> Cannot
connect
to
$host
:
$port
for
POP3: $!
Unsuccesful in connecting to the remote POP3 server.
I<Error:> Cannot get the messages of pop3 via messages()
It is not possible to retreive all messages on a remote POP3 folder
at once:
each
shall be taken separately. The POP3 folder will hide this
for
you.
I<Error:> Cannot re-
connect
reliably to server which doesn't support UIDL.
The connection to the remote POP3 was lost, and cannot be re-established
because the server's protocol implementation lacks the necessary information.
I<Error:> Cannot
read
POP3 from
socket
: $!
It is not possible to
read
the success status of the previously
given
POP3
command. Connection lost?
I<Error:> Cannot
write
POP3 to
socket
: $@
It is not possible to
send
a protocol command to the POP3 server. Connection
lost?
I<Error:> Could not authenticate using
'$some'
method.
The authenication method to get access to the POP3 server did not result in
a connection. Maybe you need a different authentication protocol, or your
username
with
password are invalid.
I<Error:> Could not authenticate using any login method.
No authentication method was explicitly prescribed, so both AUTH and APOP were
tried. However, both failed. There are other authentication methods, which
are not
defined
by the main POP3 RFC rfc1939. These protocols are not
implemented yet. Please contribute your implementation.
I<Error:> POP3 Could not
do
a STAT
For some weird reason, the server does not respond to the STAT call.
I<Error:> POP3 requires a username and password.
No username and/or
no
password specified
for
this POP3 folder, although
these are obligatory parts in the protocol.
I<Error:> Package
$package
does not implement
$method
.
Fatal error: the specific
package
(or one of its superclasses) does not
implement this method where it should. This message means that some other
related classes
do
implement this method however the class at hand does
not. Probably you should investigate this and probably inform the author
of the
package
.
I<Error:> Server at
$host
:
$port
does not seem to be talking POP3.
The remote server did not respond to an initial exchange of messages as is
expected by the POP3 protocol. The server
has
probably a different
service on the specified port.
=head1 SEE ALSO
This module is part of Mail-Box distribution version 2.070,
=head1 LICENSE
Copyrights 2001-2007 by Mark Overmeer.For other contributors see ChangeLog.
This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.