=head1 NAME
Mail::Box::POP3 - handle POP3 folders as client
=head1 INHERITANCE
Mail::Box::POP3
is a Mail::Box::Net
is a Mail::Box
is a Mail::Reporter
=head1 SYNOPSIS
my
$folder
= new Mail::Box::POP3
folder
=>
$ENV
{MAIL}, ...;
=head1 DESCRIPTION
Maintain a folder which
has
its messages stored on a remote server. The
communication between the client application and the server is implemented
using the POP3 protocol. This class uses L<Mail::Transport::POP3|Mail::Transport::POP3> to
hide the transport of information, and focusses solely on the correct
handling of messages within a POP3 folder.
=head1 OVERLOADED
overload: B<
""
>
=over 4
See L<Mail::Box/
"OVERLOADED"
>
=back
overload: B<@{}>
=over 4
See L<Mail::Box/
"OVERLOADED"
>
=back
overload: B<cmp>
=over 4
See L<Mail::Box/
"OVERLOADED"
>
=back
=head1 METHODS
=head2 Constructors
Mail::Box::POP3-E<gt>B<new>(OPTIONS)
=over 4
For authentications, you have three choices: specify a foldername which
resembles an URL, or specify a
pop
-client object, or separate options
for
user, password,
pop
-server and server-port.
Option Defined in Default
access L<Mail::Box> C<
'r'
>
authenticate C<
'AUTO'
>
body_delayed_type L<Mail::Box> L<Mail::Message::Body::Delayed|Mail::Message::Body::Delayed>
body_type L<Mail::Box> L<Mail::Message::Body::Lines|Mail::Message::Body::Lines>
coerce_options L<Mail::Box> C<[]>
create L<Mail::Box> <not applicable>
extract L<Mail::Box> C<10240>
field_type L<Mail::Box>
undef
fix_headers L<Mail::Box> <false>
folder L<Mail::Box> <not applicable>
folderdir L<Mail::Box> <not used>
head_delayed_type L<Mail::Box> L<Mail::Message::Head::Delayed|Mail::Message::Head::Delayed>
head_type L<Mail::Box> L<Mail::Message::Head::Complete|Mail::Message::Head::Complete>
keep_dups L<Mail::Box> <false>
lock_file L<Mail::Box>
undef
lock_timeout L<Mail::Box> 1 hour
lock_type L<Mail::Box> C<
'NONE'
>
lock_wait L<Mail::Box> 10 seconds
locker L<Mail::Box>
undef
log
L<Mail::Reporter> C<
'WARNINGS'
>
manager L<Mail::Box>
undef
message_type L<Mail::Box> L<Mail::Box::POP3::Message|Mail::Box::POP3::Message>
multipart_type L<Mail::Box> L<Mail::Message::Body::Multipart|Mail::Message::Body::Multipart>
password L<Mail::Box::Net>
undef
pop_client
undef
remove_when_empty L<Mail::Box> <false>
save_on_exit L<Mail::Box> <true>
server_name L<Mail::Box::Net>
undef
server_port L<Mail::Box::Net> 110
trace L<Mail::Reporter> C<
'WARNINGS'
>
trusted L<Mail::Box> <false>
username L<Mail::Box::Net>
undef
. access MODE
. authenticate
'LOGIN'
|
'APOP'
|
'AUTO'
=over 4
POP3 can
use
two methods of authentication: the old LOGIN protocol, which
transmits a username and password in plain text, and the newer APOP
protocol which uses MD5 encryption. APOP is therefore much better, however
not always supported by the server. With AUTO, first APOP is tried and
if
that fails LOGIN.
=back
. body_delayed_type CLASS
. body_type CLASS|CODE
. coerce_options ARRAY
. create BOOLEAN
. extract INTEGER | CODE | METHOD |
'LAZY'
|
'ALWAYS'
. field_type CLASS
. fix_headers BOOLEAN
. folder FOLDERNAME
. folderdir DIRECTORY
. head_delayed_type CLASS
. head_type CLASS
. keep_dups BOOLEAN
. lock_file FILENAME
. lock_timeout SECONDS
. lock_type CLASS|STRING|ARRAY
. lock_wait SECONDS
. locker OBJECT
.
log
LEVEL
. manager MANAGER
. message_type CLASS
. multipart_type CLASS
. password STRING
. pop_client OBJECT
=over 4
You may want to specify your own
pop
-client object. The object
which is passed must extend L<Mail::Transport::POP3|Mail::Transport::POP3>.
=back
. remove_when_empty BOOLEAN
. save_on_exit BOOLEAN
. server_name HOSTNAME
. server_port INTEGER
. trace LEVEL
. trusted BOOLEAN
. username STRING
I<Example:>
my
$pop
= Mail::Box::POP3->new(
$url
);
my
$pop
=
$mgr
->
open
(
type
=>
'pop3'
,
username
=>
'myname'
,
password
=>
'mypassword'
,
server_name
=>
'pop.xs4all.nl'
);
=back
=head2 The folder
$obj
-E<gt>B<addMessage>(MESSAGE)
=over 4
It is impossible to
write
messages to the average POP3 server. There are
extensions to the protocol which
do
permit it, however these are not
implemented (yet, patches welcome).
C<
undef
> is returned, and an error displayed. However,
no
complaint is
given
when
the MESSAGE is C<
undef
> itself.
Option Defined in Default
share L<Mail::Box> <not used>
. share BOOLEAN
=back
$obj
-E<gt>B<addMessages>(MESSAGES)
=over 4
As useless as L<addMessage()|Mail::Box::POP3/
"METHODS"
>. The only acceptable call to this method
is without any message.
=back
Mail::Box::POP3-E<gt>B<appendMessages>(OPTIONS)
=over 4
See L<Mail::Box/
"The folder"
>
=back
$obj
-E<gt>B<
close
>(OPTIONS)
=over 4
See L<Mail::Box/
"The folder"
>
=back
$obj
-E<gt>B<copyTo>(FOLDER, OPTIONS)
=over 4
See L<Mail::Box/
"The folder"
>
=back
$obj
-E<gt>B<
delete
>(OPTIONS)
=over 4
It is not possible to
delete
a POP3 folder remotely: the best we can
do
is remove all the messages in it... which is the action implemented here.
A notice is logged about this.
Option Defined in Default
recursive L<Mail::Box> <not used>
. recursive BOOLEAN
=back
$obj
-E<gt>B<folderdir>([DIRECTORY])
=over 4
See L<Mail::Box::Net/
"METHODS"
>
=back
$obj
-E<gt>B<name>
=over 4
See L<Mail::Box/
"The folder"
>
=back
$obj
-E<gt>B<organization>
=over 4
See L<Mail::Box/
"The folder"
>
=back
$obj
-E<gt>B<size>
=over 4
See L<Mail::Box/
"The folder"
>
=back
$obj
-E<gt>B<type>
=over 4
See L<Mail::Box/
"The folder"
>
=back
$obj
-E<gt>B<update>
=over 4
NOT IMPLEMENTED YET
=back
$obj
-E<gt>B<url>
=over 4
See L<Mail::Box/
"The folder"
>
=back
=head2 Folder flags
$obj
-E<gt>B<access>
=over 4
See L<Mail::Box/
"Folder flags"
>
=back
$obj
-E<gt>B<isModified>
=over 4
See L<Mail::Box/
"Folder flags"
>
=back
$obj
-E<gt>B<modified>([BOOLEAN])
=over 4
See L<Mail::Box/
"Folder flags"
>
=back
$obj
-E<gt>B<writable>
=over 4
See L<Mail::Box/
"Folder flags"
>
=back
=head2 The messages
$obj
-E<gt>B<current>([NUMBER|MESSAGE|MESSAGE-ID])
=over 4
See L<Mail::Box/
"The messages"
>
=back
$obj
-E<gt>B<find>(MESSAGE-ID)
=over 4
See L<Mail::Box/
"The messages"
>
=back
$obj
-E<gt>B<findFirstLabeled>(LABEL, [BOOLEAN, [ARRAY-OF-MSGS]])
=over 4
See L<Mail::Box/
"The messages"
>
=back
$obj
-E<gt>B<message>(INDEX [,MESSAGE])
=over 4
See L<Mail::Box/
"The messages"
>
=back
$obj
-E<gt>B<messageId>(MESSAGE-ID [,MESSAGE])
=over 4
See L<Mail::Box/
"The messages"
>
=back
$obj
-E<gt>B<messageIds>
=over 4
See L<Mail::Box/
"The messages"
>
=back
$obj
-E<gt>B<messages>([
'ALL'
,RANGE,
'ACTIVE'
,
'DELETED'
,LABEL,!LABEL,FILTER])
=over 4
See L<Mail::Box/
"The messages"
>
=back
$obj
-E<gt>B<nrMessages>(OPTIONS)
=over 4
See L<Mail::Box/
"The messages"
>
=back
$obj
-E<gt>B<scanForMessages>(MESSAGE, MESSAGE-IDS, TIMESPAN, WINDOW)
=over 4
See L<Mail::Box/
"The messages"
>
=back
=head2 Sub-folders
$obj
-E<gt>B<listSubFolders>(OPTIONS)
Mail::Box::POP3-E<gt>B<listSubFolders>(OPTIONS)
=over 4
The standard POP3 protocol does not support
sub
-folders, so an
empty list will be returned in any case.
Option Defined in Default
check L<Mail::Box> <false>
folder L<Mail::Box> <from calling object>
folderdir L<Mail::Box> <from folder>
skip_empty L<Mail::Box> <false>
. check BOOLEAN
. folder FOLDERNAME
. folderdir DIRECTORY
. skip_empty BOOL
=back
$obj
-E<gt>B<nameOfSubFolder>(SUBNAME, [PARENTNAME])
Mail::Box::POP3-E<gt>B<nameOfSubFolder>(SUBNAME, [PARENTNAME])
=over 4
See L<Mail::Box/
"Sub-folders"
>
=back
$obj
-E<gt>B<openRelatedFolder>(OPTIONS)
=over 4
See L<Mail::Box/
"Sub-folders"
>
=back
$obj
-E<gt>B<openSubFolder>(OPTIONS)
=over 4
It is not possible to
open
a
sub
-folder
for
a POP3 folder, because that
is not supported by the official POP3 protocol. In any case, C<
undef
>
is returned to indicate a failure.
=back
$obj
-E<gt>B<topFolderWithMessages>
Mail::Box::POP3-E<gt>B<topFolderWithMessages>
=over 4
See L<Mail::Box/
"Sub-folders"
>
=back
=head2 Internals
$obj
-E<gt>B<coerce>(MESSAGE, OPTIONS)
=over 4
See L<Mail::Box/
"Internals"
>
=back
$obj
-E<gt>B<create>(FOLDER, OPTIONS)
Mail::Box::POP3-E<gt>B<create>(FOLDER, OPTIONS)
=over 4
It is not possible to create a new folder on a POP3 server. This method
will always
return
C<false>.
Option Defined in Default
folderdir L<Mail::Box> <not used>
. folderdir DIRECTORY
=back
$obj
-E<gt>B<determineBodyType>(MESSAGE, HEAD)
=over 4
See L<Mail::Box/
"Internals"
>
=back
Mail::Box::POP3-E<gt>B<foundIn>([FOLDERNAME], OPTIONS)
=over 4
See L<Mail::Box/
"Internals"
>
=back
$obj
-E<gt>B<getHead>(MESSAGE)
=over 4
Read the header
for
the specified message from the remote server.
=back
$obj
-E<gt>B<getHeadAndBody>(MESSAGE)
=over 4
Read all data
for
the specified message from the remote server.
=back
$obj
-E<gt>B<lineSeparator>([STRING|
'CR'
|
'LF'
|
'CRLF'
])
=over 4
See L<Mail::Box/
"Internals"
>
=back
$obj
-E<gt>B<locker>
=over 4
See L<Mail::Box/
"Internals"
>
=back
$obj
-E<gt>B<popClient>
=over 4
Returns the
pop
client object. This does not establish the connection.
=back
$obj
-E<gt>B<
read
>(OPTIONS)
=over 4
See L<Mail::Box/
"Internals"
>
=back
$obj
-E<gt>B<readMessages>(OPTIONS)
=over 4
See L<Mail::Box/
"Internals"
>
=back
$obj
-E<gt>B<storeMessage>(MESSAGE)
=over 4
See L<Mail::Box/
"Internals"
>
=back
$obj
-E<gt>B<toBeThreaded>(MESSAGES)
=over 4
See L<Mail::Box/
"Internals"
>
=back
$obj
-E<gt>B<toBeUnthreaded>(MESSAGES)
=over 4
See L<Mail::Box/
"Internals"
>
=back
$obj
-E<gt>B<updateMessages>(OPTIONS)
=over 4
See L<Mail::Box/
"Internals"
>
=back
$obj
-E<gt>B<
write
>(OPTIONS)
=over 4
See L<Mail::Box/
"Internals"
>
=back
$obj
-E<gt>B<writeMessages>(OPTIONS)
=over 4
Option Defined in Default
messages L<Mail::Box> <required>
. messages ARRAY
=back
=head2 Other methods
$obj
-E<gt>B<timespan2seconds>(TIME)
Mail::Box::POP3-E<gt>B<timespan2seconds>(TIME)
=over 4
See L<Mail::Box/
"Other methods"
>
=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::Box::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::Box::POP3-E<gt>B<
log
>([LEVEL [,STRINGS]])
=over 4
See L<Mail::Reporter/
"Error handling"
>
=back
$obj
-E<gt>B<logPriority>(LEVEL)
Mail::Box::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::Box/
"Cleanup"
>
=back
$obj
-E<gt>B<inGlobalDestruction>
=over 4
See L<Mail::Reporter/
"Cleanup"
>
=back
=head1 DIAGNOSTICS
I<Error:> Cannot create POP3 client
for
$name
.
The connection to the POP3 server cannot be established. You may see
more, related, error messages about the failure.
I<Error:> Cannot find head back
for
$uidl
on POP3 server
$name
.
The server told to have this message, but
when
asked
for
its headers,
no
single line was returned. Did the message get destroyed?
I<Error:> Cannot
read
body
for
$uidl
on POP3 server
$name
.
The message's headers are retreived from the server, but the body seems
to be lost. Did the message get destroyed between reading the header
and reading the body?
I<Warning:> Changes not written to
read
-only folder
$self
.
You have opened the folder
read
-only --which is the
default
set
by L<new(access)|Mail::Box/
"Constructors"
>--, made modifications, and now want to
close
it.
Set L<
close
(force)|Mail::Box/
"The folder"
>
if
you want to overrule the access mode, or
close
the folder
with
L<
close
(
write
)|Mail::Box/
"The folder"
> set to C<NEVER>.
I<Error:> Copying failed
for
one message.
For some reason,
for
instance disc full, removed by external process, or
read
-protection, it is impossible to copy one of the messages. Copying will
proceed
for
the other messages.
I<Error:> Destination folder
$name
is not writable.
The folder where the messages are copied to is not opened
with
write
access (see L<new(access)|Mail::Box/
"Constructors"
>). This
has
no
relation
with
write
permission
to the folder which is controled by your operating
system
.
I<Warning:> Different messages
with
id
$msgid
The message id is discovered more than once within the same folder, but the
content of the message seems to be different. This should not be possible:
each
message must be unique.
I<Error:> Folder
$name
is opened
read
-only
You can not
write
to this folder
unless
you have opened the folder to
write
or append
with
L<new(access)|Mail::Box/
"Constructors"
>, or the C<force> option is set true.
I<Error:> Invalid timespan
'$timespan'
specified.
The string does not follow the strict rules of the
time
span syntax which
is permitted as parameter.
I<Warning:> Message
$uidl
on POP3 server
$name
disappeared.
The server indicated the existence of this message
before
, however it
has
no
information about the message anymore.
I<Warning:> Message-id
'$msgid'
does not contain a domain.
According to the RFCs, message-ids need to contain a unique random part,
then an C<@>, and then a domain name. This is made to avoid the creation
of two messages
with
the same id. The warning emerges
when
the C<@> is
missing from the string.
I<Warning:> POP3 folders cannot be deleted.
Each user
has
only one POP3 folder on a server. This folder is created and
deleted by the server's administrator only.
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:> Unable to create subfolder
$name
of
$folder
.
The copy includes the subfolders, but
for
some reason it was not possible
to copy one of these. Copying will proceed
for
all other
sub
-folders.
I<Error:> Update of
$nr
messages ignored
for
POP3 folder
$name
.
The standard POP3 implementation does not support writing from client back
to the server. Therefore, modifications may be lost.
I<Error:> Writing folder
$name
failed
For some reason (you probably got more error messages about this problem)
it is impossible to
write
the folder, although you should because there
were changes made.
I<Error:> You cannot
write
a message to a
pop
server (yet)
Some extensions to the POP3 protocol
do
permit writing messages to the server,
but the standard protocol only implements retreival. Feel invited to extend
our
implementation
with
writing.
=head1 DETAILS
=head2 How POP3 folders work
Rfc1939 defines how POP3 works. POP3 is a really simple protocol to
receive messages from a server to a user's client. POP3 is also
really limited: it can only be used to fetch messages, but
has
not
many ways to limit the amount of network traffic, like the IMAP4
protocol
has
.
One POP3 account represents only one folder: there is
no
way of
sub
-folders in POP3. POP3 doesn't support writing (except
for
some message status flags).
=head2 This implementation
The protocol specifics are implemented in L<Mail::Transport::POP3|Mail::Transport::POP3>,
written by Liz Mattijsen. That module does not
use
any of the
other POP3 modules available on CPAN
for
the reason that MailBox
tries to be smarter: it is capable of re-establishing broken POP3
connection
when
the server supports UIDs.
The implementation
has
shown to work
with
many different POP servers.
In the test directory of the distribution, you will find a small
server implementation, which is used to test the client.
=head1 REFERENCES
=head1 COPYRIGHTS
Distribution version 2.062.
Written by Mark Overmeer (mark
@overmeer
.net). See the ChangeLog
for
other contributors.
Copyright (c) 2001-2003 by the author(s). All rights reserved.
This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.