
=head1 NAME

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

=head1 CLASS INHERITANCE

 Mail::Box::IMAP4
   is a Mail::Box::Net
   is a Mail::Box
   is a Mail::Reporter

=head1 SYNOPSIS

 use Mail::Box::IMAP4;
 my $folder = new Mail::Box::IMAP4 folder => $ENV{MAIL}, ...;

=head1 DESCRIPTION

UNDER DEVELOPMENT: CANNOT BE USED YET!

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 IMAP4 protocol.  This class uses Mail::Transport::IMAP4 to
hide the transport of information, and focusses solely on the correct
handling of messages within a IMAP4 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               <false>
 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'
 imap_client          undef
 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::IMAP4::Message'
 multipart_type       'Mail::Message::Body::Multipart'
 password             undef
 remove_when_empty    <false>
 save_on_exit         <true>
 server_name          undef
 server_port          143
 sub_sep              <autodetect>
 trace                'WARNINGS'
 trusted              <false>
 username             undef

=over 4

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

See Mail::Box::new(access)

=item B<authenticate> =E<gt> 'KERBEROS_V4'|'GSSAPI'|'SKEY'|'AUTO'

IMAP defines various authentications mechanisms.
See Mail::Transport::IMAP4::new(authenticate).

=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<imap_client> =E<gt> OBJECT

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

=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<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<sub_sep> =E<gt> CHARACTER

A single character used as sub-folder indicator.  The IMAP protocol is
able to find-out the right separator itself.

=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 $imap = Mail::Box::IMAP4->new('imap4://user:password@imap.xs4all.nl');

 my $imap = $mgr->open(type => 'imap4', 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

See Mail::Box::Net::create()

=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

See Mail::Box::addMessage()

=item B<addMessages> MESSAGE [, MESSAGE, ...]

See Mail::Box::addMessages()

=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<update> OPTIONS

See Mail::Box::update()

=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> 

See Mail::Box::delete()

=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()

=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.
C<undef> is returned in case the message disappeared.

=item B<getHeadAndBody> MESSAGE

Read all data for the specified message from the remote server.
Return head and body of the mesasge as list, or an empty list
if the MESSAGE disappeared from the server.

=item B<imapClient> 

Returns the imap client object: a Mail::Transport::IMAP4 object.
This does not establish the connection.

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

See Mail::Box::lineSeparator()

=item B<locker> 

See Mail::Box::locker()

=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

See Mail::Box::writeMessages()

=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 IMPLEMENTATION

=head2 How IMAP4 folders work

=head2 This implementation

=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 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.
