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.038
River stage one • 8 direct dependents • 8 total dependents
/ Mail::Transport::IMAP4

NAME

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

CLASS 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 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 Mail::Box folder types. This package is used by Mail::Box::IMAP4 for the real work.

METHODS

Initiation

new OPTIONS

(Class method) 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               DEFAULT
 authenticate         'AUTO'
 executable           C<undef>
 hostname             'localhost'
 interval             30
 log                  'WARNINGS'
 password             undef
 port                 143
 proxy                undef
 retry                <false>
 timeout              120
 trace                'WARNINGS'
 username             undef
 via                  'sendmail'
authenticate => 'KERBEROS_V4'|'GSSAPI'|'SKEY'|'AUTO'

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

executable => FILENAME

See Mail::Transport::new(executable)

hostname => HOSTNAME|ARRAY-OF-HOSTNAMES

See Mail::Transport::new(hostname)

interval => SECONDS

See Mail::Transport::new(interval)

log => LEVEL

See Mail::Reporter::new(log)

password => STRING

See Mail::Transport::new(password)

port => INTEGER

See Mail::Transport::new(port)

proxy => PATH

See Mail::Transport::new(proxy)

retry => NUMBER|undef

See Mail::Transport::new(retry)

timeout => SECONDS

See Mail::Transport::new(timeout)

trace => LEVEL

See Mail::Reporter::new(trace)

username => STRING

See Mail::Transport::new(username)

via => CLASS|NAME

See Mail::Transport::new(via)

url

Represent this imap4 connection as URL.

Server Connection

findBinary NAME [, DIRECTORIES]

See Mail::Transport::findBinary()

remoteHost

See Mail::Transport::remoteHost()

retry

See Mail::Transport::retry()

Receiving Mail

receive [UNIQUE-MESSAGE-ID]

See Mail::Transport::Receive::receive()

Exchanging Information

deleteFetched

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

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.

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.

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

folderSize

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

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.

Examples:

 my $ref_lines = $imap4->header($uidl);
 print @$ref_lines;
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.

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.

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.

Examples:

 my $ref_lines = $imap->message($uidl);
 print @$ref_lines;
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.

messages

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

Protocol [internals]

askSubfolderSeparator

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

askSubfoldersOf NAME

Returns a list of subfolders for this server.

getFlag ID, LABEL

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

login

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

IMAP4 requires a username and password Cannot connect to $host:$port for IMAP4: $!

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.

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.

setFlags ID, LABEL, VALUE, [LABEL, VALUE], ...
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 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, undef is returned and no further actions should be tried on the object.

Logging and Tracing

defaultTrace [LEVEL, [LEVEL]

See Mail::Reporter::defaultTrace()

errors

See Mail::Reporter::errors()

log [LEVEL [,STRINGS]]

See Mail::Reporter::log()

report [LEVEL]

See Mail::Reporter::report()

reportAll [LEVEL]

See Mail::Reporter::reportAll()

trace [LEVEL]

See Mail::Reporter::trace()

warnings

See Mail::Reporter::warnings()

Other Methods

AUTOLOAD

See Mail::Reporter::AUTOLOAD()

DESTROY

See Mail::Reporter::DESTROY()

inGlobalDestruction

See Mail::Reporter::inGlobalDestruction()

logPriority LEVEL

See Mail::Reporter::logPriority()

logSettings

See Mail::Reporter::logSettings()

notImplemented

See Mail::Reporter::notImplemented()

SEE ALSO

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

AUTHOR

Written by Mark Overmeer (mark@overmeer.net) with the help of many. See the ChangeLog for details.

VERSION

This code is beta, version 2.038.

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.