
=head1 NAME

Mail::Transport::IMAP4 - handle messages via the IMAP4 protocol


=head1 INHERITANCE

 Mail::Transport::IMAP4
   is a Mail::Transport::Receive
   is a Mail::Transport
   is a Mail::Reporter


=head1 SYNOPSIS

 my $imap = Mail::Transport::IMAP4->new(...);
 my $message = $imap->receive($id);
 $imap->send($message);


=head1 DESCRIPTION

UNDER DEVELOPMENT: Cannot be used yet.

The IMAP4 protocol is quite complicated: it is feature rich and allows
verious asynchronous actions.  The main document describing IMAP is
rfc2060.

This package, as part of Mail::Box, does not implement the actual
protocol itself, but uses Mail::IMAPClient to do the work.  The task
for this package is to hide as much differences between that module's
interface and the common L<Mail::Box|Mail::Box> folder types.  This package is used
by L<Mail::Box::IMAP4|Mail::Box::IMAP4> for the real work.



=head1 METHODS


$obj-E<gt>B<url>

=over 4

Represent this imap4 connection as URL.

=back

=head2 Constructors


Mail::Transport::IMAP4-E<gt>B<new>(OPTIONS)

=over 4

Create the IMAP connection to the server.  IMAP servers can handle
multiple folders for a single user, which means that connections
may get shared.  This is sharing is hidden for the user.

 Option        Defined in       Default       
 authenticate                   C<'AUTO'>     
 executable    L<Mail::Transport>  C<undef>      
 hostname      L<Mail::Transport>  C<'localhost'>
 interval      L<Mail::Transport>  C<30>         
 log           L<Mail::Reporter>  C<'WARNINGS'> 
 password      L<Mail::Transport>  undef         
 port          L<Mail::Transport>  143           
 proxy         L<Mail::Transport>  undef         
 retry         L<Mail::Transport>  <false>       
 timeout       L<Mail::Transport>  C<120>        
 trace         L<Mail::Reporter>  C<'WARNINGS'> 
 username      L<Mail::Transport>  undef         
 via           L<Mail::Transport>  C<'sendmail'> 

. authenticate 'KERBEROS_V4'|'GSSAPI'|'SKEY'|'AUTO'

=over 4

Authenthication method.  RFC1731 defines a few authentication methods
to be (optionally) used with IMAP. NOT IMPLEMENTED YET.

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

=head2 Exchanging Information


$obj-E<gt>B<deleteFetched>

=over 4

Mark all messages that have been fetched with message() for deletion.  See
fetched().

=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 the
message() method.  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 IMAP4 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 deleteFetched().

=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 = $imap4->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 IMAP4 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 = $imap->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<askSubfolderSeparator>

=over 4

Returns the separator which is used on the server side to indicate
sub-folders.

=back

$obj-E<gt>B<askSubfoldersOf>(NAME)

=over 4

Returns a list of subfolders for this server.

=back

$obj-E<gt>B<getFlag>(ID, LABEL)

=over 4

Returns the value of the LABEL for the message with this ID.

=back

$obj-E<gt>B<login>

=over 4

Establish a new connection to the IMAP4 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<setFlags>(ID, LABEL, VALUE, [LABEL, VALUE], ...)

=over 4

=back

$obj-E<gt>B<socket>

=over 4

Returns a connection to the IMAP4 server.  If there was no connection yet,
it will be created transparently.  If the connection with the IMAP4 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

=head2 Error handling


$obj-E<gt>B<AUTOLOAD>

=over 4

See L<Mail::Reporter/"Error handling">

=back

$obj-E<gt>B<defaultTrace>([LEVEL, [LEVEL])

Mail::Transport::IMAP4-E<gt>B<defaultTrace>([LEVEL, [LEVEL])

=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::IMAP4-E<gt>B<log>([LEVEL [,STRINGS]])

=over 4

See L<Mail::Reporter/"Error handling">

=back

$obj-E<gt>B<logPriority>(LEVEL)

Mail::Transport::IMAP4-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

The connection is cleanly terminated when the program is cleanly
terminated.

=back

$obj-E<gt>B<inGlobalDestruction>

=over 4

See L<Mail::Reporter/"Cleanup">

=back



=head1 DIAGNOSTICS

I<Error:> Cannot connect to $host:$port for IMAP4: $!


I<Error:> Cannot get the messages of imap4 via messages()

It is not possible to retreive all messages on a remote IMAP4 folder
at once: each shall be taken separately.  The IMAP4 folder will hide this
for you.

I<Error:> Cannot re-connect reliably to server which doesn't support UIDL.

The connection to the remote IMAP4 was lost, and cannot be re-established
because the server's protocol implementation lacks the necessary information.

I<Error:> Cannot read IMAP4 from socket: $!

It is not possible to read the success status of the previously given IMAP4
command.  Connection lost?

I<Error:> Cannot write IMAP4 to socket: $@

It is not possible to send a protocol command to the IMAP4 server.  Connection
lost?

I<Error:> IMAP4 requires a username and password


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.






=head1 REFERENCES

See the Mail::Box website at L<http://perl.overmeer.net/mailbox/> for more details.

=head1 COPYRIGHTS

Module version 2.042.
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.


