The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
Mail-Box-2.046
River stage one • 8 direct dependents • 8 total dependents
/ Mail::Transport::IMAP4

NAME

Mail::Transport::IMAP4 - proxy to Mail::IMAPClient

INHERITANCE

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

SYNOPSIS

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

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 rfc3501 (which obsoleted the original specification of protocol 4r1 in rfc2060 in March 2003).

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 many differences between that module's interface and the common Mail::Box folder types. Multiple Mail::Box::IMAP4 folders can share one Mail::Transport::IMAP4 connection.

METHODS

$obj->url

    Represent this imap4 connection as URL.

Constructors

Mail::Transport::IMAP4->new(OPTIONS)

    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<'imap'>

    . authenticate 'PLAIN'|'CRAM-MD5'|'NTLM'|'AUTO'|CODE

      Authenthication method. AUTO will try all known methods. The NTLM authentication requires Authen::NTLM to be installed. If this module is not installed, it will be skipped by AUTO.

      You can also specify your own mechan$^O eq 'MSWin32' ? "\n" : ism as CODE reference. The Mail::IMAPClient documentation refers to this code as Authcallback. In case you have your own implementation, please consider to contribute it to Mail::Box.

    . 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

Receiving mail

$obj->receive([UNIQUE-MESSAGE-ID])

Server connection

$obj->findBinary(NAME [, DIRECTORIES])

$obj->remoteHost

$obj->retry

Exchanging Information

$obj->deleteFetched

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

$obj->deleted(BOOLEAN, ID's)

    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 only when the connection is specifically disconnected or the last reference to the object goes out of scope.

$obj->disconnect

    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.

$obj->fetched

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

$obj->folderSize

    Returns the total number of octets used by the mailbox on the remote server.

$obj->header(ID, [BODYLINES])

    Returns a reference to an array which contains the header of the message with the specified ID. 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.

    Example:

     my $ref_lines = $imap4->header($uidl);
 print @$ref_lines;

$obj->id2n(ID)

    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, undef is returned.

$obj->ids

    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.

$obj->message(ID)

    Returns a reference to an array which contains the lines of the message with the specified ID. Returns undef if something has gone wrong.

    Example:

     my $ref_lines = $imap->message($uidl);
 print @$ref_lines;

$obj->messageSize(ID)

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

$obj->messages

    Returns (in scalar context only) the number of messages that are known to exist in the mailbox.

Protocol [internals]

The follow methods handle protocol internals, and should not be used by a normal user of this class.

$obj->askSubfolderSeparator

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

$obj->askSubfoldersOf(NAME)

    Returns a list of subfolders for this server.

$obj->getFlags(ID)

    Returns the values of all flags which are related to the message with the specified ID. These flags are translated into the names which are standard for the Mail::Box suite

$obj->login

    Establish a new connection to the IMAP4 server, using username and password.

$obj->send(SOCKET, data)

    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 not attempt to reconnect or anything: if reading or writing the socket fails, something is very definitely wrong.

$obj->sendList(SOCKET, COMMAND)

    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 +OK line and before the end-of-message delimiter (a single dot on a line). Returns undef whenever something has gone wrong.

$obj->setFlags(ID, LABEL, VALUE, [LABEL, VALUE], ...)

$obj->socket

    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 UID) 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, undef is returned and no further actions should be tried on the object.

Error handling

$obj->AUTOLOAD

$obj->defaultTrace([LEVEL, [LEVEL])

Mail::Transport::IMAP4->defaultTrace([LEVEL, [LEVEL])

$obj->errors

$obj->log([LEVEL [,STRINGS]])

Mail::Transport::IMAP4->log([LEVEL [,STRINGS]])

$obj->logPriority(LEVEL)

Mail::Transport::IMAP4->logPriority(LEVEL)

$obj->logSettings

$obj->notImplemented

$obj->report([LEVEL])

$obj->reportAll([LEVEL])

$obj->trace([LEVEL])

$obj->warnings

Cleanup

$obj->DESTROY

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

$obj->inGlobalDestruction

DIAGNOSTICS

Error: Cannot connect to $host:$port for IMAP4: $!

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.

Error: Cannot re-connect reliably to server which doesn't support UID.

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

Error: Cannot read IMAP4 from socket: $!

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

Error: Cannot write IMAP4 to socket: $@

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

Error: IMAP4 requires a username and password

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.

Error: module Authen::NTLM is not installed

You try to establish an IMAP4 connection which explicitly uses NTLM authentication, but the optional Authen::NTLM, which implements this is not installed on your system.

REFERENCES

See the MailBox website at http://perl.overmeer.net/mailbox/ for more details.

COPYRIGHTS

Distribution version 2.046. 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.