
=head1 NAME

Mail::Box::POP3 - handle POP3 folders as client

=head1 CLASS INHERITANCE

 Mail::Box::POP3
   is a Mail::Box::Net
   is a Mail::Box
   is a Mail::Reporter

=head1 SYNOPSIS

 use Mail::Box::POP3;
 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 Mail::Transport::POP3 to
hide the transport of information, and focusses solely on the correct
handling of messages within a POP3 folder.

=head1 METHODS

=head2 Initiation

=over 4

=item B<new> OPTIONS

(Class method) 
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               DEFAULT
 access               'r'
 authenticate         'AUTO'
 body_delayed_type    'Mail::Message::Body::Delayed'
 body_type            'Mail::Message::Body::Lines'
 coerce_options       []
 create               <not applicable>
 extract              10240
 field_type           undef
 fix_headers          <false>
 folder               '/'
 folderdir            <not used>
 head_delayed_type    'Mail::Message::Head::Delayed'
 head_type            'Mail::Message::Head::Complete'
 keep_dups            <false>
 lock_file            undef
 lock_timeout         1 hour
 lock_type            'NONE'
 lock_wait            10 seconds
 locker               undef
 log                  'WARNINGS'
 manager              undef
 message_type         'Mail::Box::POP3::Message'
 multipart_type       'Mail::Message::Body::Multipart'
 password             undef
 pop_client           undef
 remove_when_empty    <false>
 save_on_exit         <true>
 server_name          undef
 server_port          110
 trace                'WARNINGS'
 trusted              <false>
 username             undef

=over 4

=item B<access> =E<gt> MODE

See Mail::Box::new(access)

=item B<authenticate> =E<gt> 'LOGIN'|'APOP'|'AUTO'

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.

=item B<body_delayed_type> =E<gt> CLASS

See Mail::Box::new(body_delayed_type)

=item B<body_type> =E<gt> CLASS|CODE

See Mail::Box::new(body_type)

=item B<coerce_options> =E<gt> ARRAY

See Mail::Box::new(coerce_options)

=item B<create> =E<gt> BOOLEAN

See Mail::Box::new(create)

=item B<extract> =E<gt> INTEGER | CODE | METHOD | 'LAZY'|'ALWAYS'

See Mail::Box::new(extract)

=item B<field_type> =E<gt> CLASS

See Mail::Box::new(field_type)

=item B<fix_headers> =E<gt> BOOLEAN

See Mail::Box::new(fix_headers)

=item B<folder> =E<gt> FOLDERNAME

See Mail::Box::new(folder)

=item B<folderdir> =E<gt> DIRECTORY

See Mail::Box::new(folderdir)

=item B<head_delayed_type> =E<gt> CLASS

See Mail::Box::new(head_delayed_type)

=item B<head_type> =E<gt> CLASS

See Mail::Box::new(head_type)

=item B<keep_dups> =E<gt> BOOLEAN

See Mail::Box::new(keep_dups)

=item B<lock_file> =E<gt> FILENAME

See Mail::Box::new(lock_file)

=item B<lock_timeout> =E<gt> SECONDS

See Mail::Box::new(lock_timeout)

=item B<lock_type> =E<gt> CLASS|STRING

See Mail::Box::new(lock_type)

=item B<lock_wait> =E<gt> SECONDS

See Mail::Box::new(lock_wait)

=item B<locker> =E<gt> OBJECT

See Mail::Box::new(locker)

=item B<log> =E<gt> LEVEL

See Mail::Reporter::new(log)

=item B<manager> =E<gt> MANAGER

See Mail::Box::new(manager)

=item B<message_type> =E<gt> CLASS

See Mail::Box::new(message_type)

=item B<multipart_type> =E<gt> CLASS

See Mail::Box::new(multipart_type)

=item B<password> =E<gt> STRING

See Mail::Box::Net::new(password)

=item B<pop_client> =E<gt> OBJECT

You may want to specify your own pop-client object.  The object
which is passed must extend Mail::Transport::POP3.

=item B<remove_when_empty> =E<gt> BOOLEAN

See Mail::Box::new(remove_when_empty)

=item B<save_on_exit> =E<gt> BOOLEAN

See Mail::Box::new(save_on_exit)

=item B<server_name> =E<gt> HOSTNAME

See Mail::Box::Net::new(server_name)

=item B<server_port> =E<gt> INTEGER

See Mail::Box::Net::new(server_port)

=item B<trace> =E<gt> LEVEL

See Mail::Reporter::new(trace)

=item B<trusted> =E<gt> BOOLEAN

See Mail::Box::new(trusted)

=item B<username> =E<gt> STRING

See Mail::Box::Net::new(username)

=back

Examples:

 my $pop = Mail::Box::POP3->new('pop3://user:password@pop.xs4all.nl');

 my $pop = $mgr->open(type => 'pop3', username => 'myname',
    password => 'mypassword', server_name => 'pop.xs4all.nl');

=back

=head2 Opening folders

=over 4

=item B<clone> OPTIONS

See Mail::Box::clone()

=item B<create> FOLDER, OPTIONS

It is not possible to create a new folder on a POP3 server.  This method
will always return C<false>.

 OPTION               DEFAULT
 folderdir            <not used>

=over 4

=item B<folderdir> =E<gt> DIRECTORY

See Mail::Box::create(folderdir)

=back

=item B<folderdir> [DIRECTORY]

See Mail::Box::Net::folderdir()

=item B<foundIn> [FOLDERNAME], OPTIONS

See Mail::Box::foundIn()

=back

=head2 On open folders

=over 4

=item B<addMessage> MESSAGE

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.

=item B<addMessages> MESSAGES

As useless as addMessage().  The only acceptable call to this method
is without any message.

=item B<copyTo> FOLDER, OPTIONS

See Mail::Box::copyTo()

=item B<isModified> 

See Mail::Box::isModified()

=item B<modified> [BOOLEAN]

See Mail::Box::modified()

=item B<name> 

See Mail::Box::name()

=item B<organization> 

See Mail::Box::organization()

=item B<type> 

See Mail::Box::type()

=item B<url> 

See Mail::Box::url()

=item B<writable> 

See Mail::Box::writable()

=item B<write> OPTIONS

See Mail::Box::write()

=back

=head2 Closing the folder

=over 4

=item B<DESTROY> 

See Mail::Box::DESTROY()

=item B<close> OPTIONS

See Mail::Box::close()

=item B<delete> 

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.

=back

=head2 The messages

=over 4

=item B<current> [NUMBER|MESSAGE|MESSAGE-ID]

See Mail::Box::current()

=item B<find> MESSAGE-ID

See Mail::Box::find()

=item B<message> INDEX [,MESSAGE]

See Mail::Box::message()

=item B<messageId> MESSAGE-ID [,MESSAGE]

See Mail::Box::messageId()

=item B<messageIds> 

See Mail::Box::messageIds()

=item B<messages> ['ALL',RANGE,'ACTIVE','DELETED',LABEL,!LABEL,FILTER]

See Mail::Box::messages()

=item B<scanForMessages> MESSAGE, MESSAGE-IDS, TIMESTAMP, WINDOW

See Mail::Box::scanForMessages()

=back

=head2 Sub-folders

=over 4

=item B<listSubFolders> OPTIONS

See Mail::Box::listSubFolders()

=item B<nameOfSubfolder> NAME

See Mail::Box::nameOfSubfolder()

=item B<openRelatedFolder> OPTIONS

See Mail::Box::openRelatedFolder()

=item B<openSubFolder> NAME, OPTIONS

See Mail::Box::openSubFolder()

=item B<update> 

NOT IMPLEMENTED YET

=back

=head2 Message threads [internals]

=over 4

=item B<toBeThreaded> MESSAGES

See Mail::Box::toBeThreaded()

=item B<toBeUnthreaded> MESSAGES

See Mail::Box::toBeUnthreaded()

=back

=head2 Reading and Writing [internals]

=over 4

=item B<appendMessages> OPTIONS

See Mail::Box::appendMessages()

=item B<coerce> MESSAGE

See Mail::Box::coerce()

=item B<determineBodyType> MESSAGE, HEAD

See Mail::Box::determineBodyType()

=item B<getHead> MESSAGE

Read the header for the specified message from the remote server.

=item B<getHeadAndBody> MESSAGE

Read all data for the specified message from the remote server.

=item B<lineSeparator> [STRING|'CR'|'LF'|'CRLF']

See Mail::Box::lineSeparator()

=item B<locker> 

See Mail::Box::locker()

=item B<popClient> 

Returns the pop client object.  This does not establish the connection.

=item B<read> OPTIONS

See Mail::Box::read()

=item B<readMessages> OPTIONS

See Mail::Box::readMessages()

=item B<storeMessage> MESSAGE

See Mail::Box::storeMessage()

=item B<updateMessages> OPTIONS

See Mail::Box::updateMessages()

=item B<writeMessages> OPTIONS

 OPTION               DEFAULT
 messages             <required>

=over 4

=item B<messages> =E<gt> ARRAY

See Mail::Box::writeMessages(messages)

=back

=back

=head2 Logging and Tracing

=over 4

=item B<defaultTrace> [LEVEL, [LEVEL]

See Mail::Reporter::defaultTrace()

=item B<errors> 

See Mail::Reporter::errors()

=item B<log> [LEVEL [,STRINGS]]

See Mail::Reporter::log()

=item B<report> [LEVEL]

See Mail::Reporter::report()

=item B<reportAll> [LEVEL]

See Mail::Reporter::reportAll()

=item B<trace> [LEVEL]

See Mail::Reporter::trace()

=item B<warnings> 

See Mail::Reporter::warnings()

=back

=head2 Other Methods

=over 4

=item B<AUTOLOAD> 

See Mail::Reporter::AUTOLOAD()

=item B<inGlobalDestruction> 

See Mail::Reporter::inGlobalDestruction()

=item B<logPriority> LEVEL

See Mail::Reporter::logPriority()

=item B<logSettings> 

See Mail::Reporter::logSettings()

=item B<notImplemented> 

See Mail::Reporter::notImplemented()

=item B<timespan2seconds> TIME

See Mail::Box::timespan2seconds()

=back

=head1 SEE ALSO

A good start to read is Mail::Box-Overview.
More documentation and a mailinglist are available from the project's
website at L<http://perl.overmeer.net/mailbox/>.

=head1 AUTHOR

Written by Liz Mattijsen (L<liz@dijkmat.nl|mailto:liz@dijkmat.nl>) and Mark Overmeer (L<mark@overmeer.net|mailto:mark@overmeer.net>)
with the help of many.  See the ChangeLog for details.

=head1 VERSION

This code is beta, version 2.037.

Copyright (c) 2001-2003 by the authors. All rights reserved.
This program is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.
