unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (Debian-5.0)
Page:
Section:
Apropos / Subsearch:
optional field

Mail::Box::IMAP4(3pm) User Contributed Perl DocumentationMail::Box::IMAP4(3pm)



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

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

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

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 IMAP4 protocol.  See also Mail::Server::IMAP4.

       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.  More than one IMAP4 folder can be handled by
       one single IMAP4 connection.

OVERLOADED
       overload: ""

           See "OVERLOADED" in Mail::Box

       overload: @{}

           See "OVERLOADED" in Mail::Box

       overload: cmp

           See "OVERLOADED" in Mail::Box

METHODS
       Constructors

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

           The "new" can have many OPTIONS.  Not only the ones listed here
           below, but also all the OPTIONS for Mail::Transport::IMAP4::new()
           can be passed.

           The default depends on the value of new(cache_head).

           Without folder name, no folder is selected.  Only few methods are
           available now, for instance listSubFolders() to get the top-level
           folder names.  Usually, the folder named "INBOX" will be present.

            Option           --Defined in     --Default
            access             Mail::Box        'r'
            body_delayed_type  Mail::Box        Mail::Message::Body::Delayed
            body_type          Mail::Box        Mail::Message::Body::Lines
            cache_body                          NO
            cache_head                          NO or DELAY
            cache_labels                        NO or DELAY
            coerce_options     Mail::Box        []
            create             Mail::Box        <false>
            extract            Mail::Box        10240
            field_type         Mail::Box        undef
            fix_headers        Mail::Box        <false>
            folder             Mail::Box        /
            folderdir          Mail::Box        <not used>
            head_delayed_type  Mail::Box        Mail::Message::Head::Delayed
            head_type          Mail::Box        Mail::Box::IMAP4::Head or Mail::Message::Head::Complete
            join_connection                     true
            keep_dups          Mail::Box        <false>
            lock_file          Mail::Box        undef
            lock_timeout       Mail::Box        1 hour
            lock_type          Mail::Box        'NONE'
            lock_wait          Mail::Box        10 seconds
            locker             Mail::Box        undef
            log                Mail::Reporter   'WARNINGS'
            manager            Mail::Box        undef
            message_type       Mail::Box        Mail::Box::IMAP4::Message
            multipart_type     Mail::Box        Mail::Message::Body::Multipart
            password           Mail::Box::Net   undef
            remove_when_empty  Mail::Box        <false>
            save_on_exit       Mail::Box        <true>
            server_name        Mail::Box::Net   undef
            server_port        Mail::Box::Net   143
            trace              Mail::Reporter   'WARNINGS'
            transporter                         Mail::Transport::IMAP4
            trusted            Mail::Box        <false>
            username           Mail::Box::Net   undef

           . access => MODE

           . body_delayed_type => CLASS

           . body_type => CLASS|CODE

           . cache_body => 'NO'|'YES'|'DELAY'

               Body objects are immutable, but may still cached or not.  In
               common case, the body of a message is requested via
               Mail::Message::body() or Mail::Message::decoded().  This
               returns a handle to a body object.  You may decide wether that
               body object can be reused or not.  "NO" means: retreive the
               data each time again, "YES" will cache the body data, "DELAY"
               will send the whole message when the folder is closed.

                       [local cache]  [write]
                NO         no           no
                YES        yes          no
                DELAY      yes          yes

           . cache_head => 'NO'|'PARTIAL'|'DELAY'

               For a read-only folder, "DELAY" is the default, otherwise "NO"
               is choosen.  The four configuration parameter have subtile
               consequences.  To start with a table:

                       [local cache]  [write]  [default head_type]
                NO         no           no     Mail::Box::IMAP4::Head
                PARTIAL    yes          no     Mail::Box::IMAP4::Head
                DELAY      yes          yes    Mail::Message::Head::Complete

               The default "head_type" is Mail::Box::IMAP4::Head, the default
               "cached_head_type" is Mail::Message::Head::Complete.

               Having a local cache means that a lookup for a field is first
               done in a local data-structure (which extends
               Mail::Message::Head::Partial), and only on the remote server if
               it was not found.  This is dangerous, because your locally
               cached data can be out-of-sync with the server.  However, it
               may give you a nice performance benefit.

               "DELAY" will always collect the whole header for you.  This is
               required when you want to look for Resent Groups (See
               Mail::Message::Head::ResentGroup) or other field order
               dependent header access.  A Mail::Message::Head::Delayed will
               be created first.

           . cache_labels => 'NO'|'WRITE'|'DELAY'

               When labels from a message are received, these values can be
               kept. However, this imposes dangers where the server's internal
               label storage may get out of sync with your data.

               With "NO", no caching will take place (but the performance will
               be worse). With "WRITE", all label access will be cached, but
               written to the server as well.  Both "NO" and "WRITE" will
               update the labels on the served, even when the folder was
               opened read-only.  "DELAY" will not write the changed
               information to the server, but delay that till the moment that
               the folder is closed.  It only works when the folder is opened
               read/write or write is enforced.

               The default is "DELAY" for folders which where opened read-
               only.  This means that you still can force an update with
               close(write).  For folders which are opened read-write, the
               default is the safeset setting, which is "NO".

           . coerce_options => ARRAY

           . create => BOOLEAN

           . extract => INTEGER | CODE | METHOD | 'LAZY'|'ALWAYS'

           . field_type => CLASS

           . fix_headers => BOOLEAN

           . folder => FOLDERNAME

           . folderdir => DIRECTORY

           . head_delayed_type => CLASS

           . head_type => CLASS

           . join_connection => BOOLEAN

               Within this Mail::Box::IMAP4 class is registered which
               transporters are already in use, i.e. which connections to the
               IMAP server are already in established.  When this option is
               set, multiple folder openings on the same server will try to
               reuse one connection.

           . keep_dups => BOOLEAN

           . lock_file => FILENAME

           . lock_timeout => SECONDS

           . lock_type => CLASS|STRING|ARRAY

           . lock_wait => SECONDS

           . locker => OBJECT

           . log => LEVEL

           . manager => MANAGER

           . message_type => CLASS

           . multipart_type => CLASS

           . password => STRING

           . remove_when_empty => BOOLEAN

           . save_on_exit => BOOLEAN

           . server_name => HOSTNAME

           . server_port => INTEGER

           . trace => LEVEL

           . transporter => OBJECT|CLASS

               The name of the CLASS which will interface with the connection.
               When you implement your own extension to
               Mail::Transport::IMAP4, you can either specify a fully
               instantiated transporter OBJECT, or the name of your own CLASS.
               When an OBJECT is given, most other options will be ignored.

           . trusted => BOOLEAN

           . username => STRING

           example:

            my $imap   = Mail::Box::IMAP4->new(username => 'myname',
               password => 'mypassword', server_name => 'imap.xs4all.nl');

            my $url    = 'imap4://user:passwordATimap.nl');
            my $imap   = $mgr->open($url);

            my $client = Mail::IMAPClient->new(...);
            my $imap   = Mail::Box::IMAP4->new(imap_client => $client);

       The folder

       $obj->addMessage(MESSAGE, OPTIONS)

           See "The folder" in Mail::Box

       $obj->addMessages(MESSAGE [, MESSAGE, ...])

           See "The folder" in Mail::Box

       Mail::Box::IMAP4->appendMessages(OPTIONS)

           See "The folder" in Mail::Box

       $obj->close(OPTIONS)

           Close the folder.  In the case of IMAP, more than one folder can
           use the same connection, therefore, closing a folder does not
           always close the connection to the server.  Only when no folder is
           using the connection anymore, a logout will be invoked by
           Mail::Transport::IMAP4::DESTROY()

            Option      --Defined in     --Default
            force         Mail::Box        <false>
            save_deleted  Mail::Box        false
            write         Mail::Box        MODIFIED

           . force => BOOLEAN

           . save_deleted => BOOLEAN

           . write => 'ALWAYS'|'NEVER'|'MODIFIED'

       $obj->copyTo(FOLDER, OPTIONS)

           See "The folder" in Mail::Box

       $obj->delete(OPTIONS)

           See "The folder" in Mail::Box

       $obj->folderdir([DIRECTORY])

           See "METHODS" in Mail::Box::Net

       $obj->name

           See "The folder" in Mail::Box

       $obj->organization

           See "The folder" in Mail::Box

       $obj->size

           See "The folder" in Mail::Box

       $obj->type

           See "The folder" in Mail::Box

       $obj->update(OPTIONS)

           See "The folder" in Mail::Box

       $obj->url

           See "The folder" in Mail::Box

       Folder flags

       $obj->access

           See "Folder flags" in Mail::Box

       $obj->isModified

           See "Folder flags" in Mail::Box

       $obj->modified([BOOLEAN])

           See "Folder flags" in Mail::Box

       $obj->writable

           See "Folder flags" in Mail::Box

       The messages

       $obj->current([NUMBER|MESSAGE|MESSAGE-ID])

           See "The messages" in Mail::Box

       $obj->find(MESSAGE-ID)

           See "The messages" in Mail::Box

       $obj->findFirstLabeled(LABEL, [BOOLEAN, [ARRAY-OF-MSGS]])

           See "The messages" in Mail::Box

       $obj->message(INDEX [,MESSAGE])

           See "The messages" in Mail::Box

       $obj->messageId(MESSAGE-ID [,MESSAGE])

           See "The messages" in Mail::Box

       $obj->messageIds

           See "The messages" in Mail::Box

       $obj->messages(['ALL',RANGE,'ACTIVE','DELETED',LABEL,!LABEL,FILTER])

           See "The messages" in Mail::Box

       $obj->nrMessages(OPTIONS)

           See "The messages" in Mail::Box

       $obj->scanForMessages(MESSAGE, MESSAGE-IDS, TIMESPAN, WINDOW)

           See "The messages" in Mail::Box

       Sub-folders

       $obj->listSubFolders(OPTIONS)

       Mail::Box::IMAP4->listSubFolders(OPTIONS)

           See "Sub-folders" in Mail::Box

       $obj->nameOfSubFolder(SUBNAME, [PARENTNAME])

       Mail::Box::IMAP4->nameOfSubFolder(SUBNAME, [PARENTNAME])

           See "Sub-folders" in Mail::Box

       $obj->openRelatedFolder(OPTIONS)

           See "Sub-folders" in Mail::Box

       $obj->openSubFolder(SUBNAME, OPTIONS)

           See "Sub-folders" in Mail::Box

       $obj->topFolderWithMessages

       Mail::Box::IMAP4->topFolderWithMessages

           See "Sub-folders" in Mail::Box

       Internals

       $obj->body([BODY])

       $obj->coerce(MESSAGE, OPTIONS)

           See "Internals" in Mail::Box

       $obj->create(FOLDER, OPTIONS)

       Mail::Box::IMAP4->create(FOLDER, OPTIONS)

           See "METHODS" in Mail::Box::Net

       $obj->createTransporter(CLASS, OPTIONS)

           Create a transporter object (an instance of
           Mail::Transport::IMAP4), where CLASS defines the exact object type.
           As OPTIONS, everything which is acceptable to a transporter
           initiation can be used (see Mail::Transport::IMAP4::new().

            Option         --Default
            join_connection  true

           . join_connection => BOOLEAN

               See new(join_connection).  When false, the connection will
               never be shared with other IMAP mail boxes.

       $obj->determineBodyType(MESSAGE, HEAD)

           See "Internals" in Mail::Box

       $obj->fetch(ARRAY-OF-MESSAGES|MESSAGE-SELECTION, INFO)

           Low-level data retreival about one or more messages via IMAP4 from
           the remote server. Some of this data may differ from the
           information which is stored in the message objects which are
           created by MailBox, so you should avoid the use of this method for
           your own purposes.  The IMAP implementation provides some wrappers
           around this, providing the correct behavior.

           An array of MESSAGES may be specified or some MESSAGE SELECTION,
           acceptable to Mail::Box::messages().  Examples of the latter are
           'ALL', 'DELETED', or "spam" (messages labelled to contain spam).

           The INFO contains one or more attributes as defined by the IMAP
           protocol.  You have to read the full specs of the related RFCs to
           see these.

       Mail::Box::IMAP4->foundIn([FOLDERNAME], OPTIONS)

           See "Internals" in Mail::Box

       $obj->getHead(MESSAGE)

           Read the header for the specified message from the remote server.
           "undef" is returned in case the message disappeared.

       $obj->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.

       $obj->lineSeparator([STRING|'CR'|'LF'|'CRLF'])

           See "Internals" in Mail::Box

       $obj->locker

           See "Internals" in Mail::Box

       $obj->read(OPTIONS)

           See "Internals" in Mail::Box

       $obj->readMessages(OPTIONS)

           See "Internals" in Mail::Box

       $obj->storeMessage(MESSAGE)

           See "Internals" in Mail::Box

       $obj->toBeThreaded(MESSAGES)

           See "Internals" in Mail::Box

       $obj->toBeUnthreaded(MESSAGES)

           See "Internals" in Mail::Box

       $obj->transporter([OBJECT])

           Returns the object which is the interface to the IMAP4 protocol
           handler.  The IMAP4 handler has the current folder selected.  When
           an OBJECT is specified, it is set to be the transporter from that
           moment on.  The OBJECT must extend Mail::Transport::IMAP4.

       $obj->updateMessages(OPTIONS)

           See "Internals" in Mail::Box

       $obj->write(OPTIONS)

           The IMAP protocol usually writes the data immediately to the remote
           server, because that's what the protocol wants.  However, some
           options to new() may delay that to boost performance.  This method
           will, when the folder is being closed, write that info after all.

            Option      --Defined in     --Default
            force         Mail::Box        <false>
            save_deleted                   <false>

           . force => BOOLEAN

           . save_deleted => BOOLEAN

               You may be able to save the messages which are flagged for
               deletion now, but they will be removed anyway when the folder
               is closed.

       $obj->writeMessages(OPTIONS)

        Option     --Defined in     --Default
        messages     Mail::Box        <required>
        transporter                   <required>

           . messages => ARRAY

           . transporter => OBJECT

       Other methods

       $obj->timespan2seconds(TIME)

       Mail::Box::IMAP4->timespan2seconds(TIME)

           See "Other methods" in Mail::Box

       Error handling

       $obj->AUTOLOAD

           See "Error handling" in Mail::Reporter

       $obj->addReport(OBJECT)

           See "Error handling" in Mail::Reporter

       $obj->defaultTrace([LEVEL]|[LOGLEVEL, TRACELEVEL]|[LEVEL, CALLBACK])

       Mail::Box::IMAP4->defaultTrace([LEVEL]|[LOGLEVEL, TRACELEVEL]|[LEVEL,
       CALLBACK])

           See "Error handling" in Mail::Reporter

       $obj->errors

           See "Error handling" in Mail::Reporter

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

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

           See "Error handling" in Mail::Reporter

       $obj->logPriority(LEVEL)

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

           See "Error handling" in Mail::Reporter

       $obj->logSettings

           See "Error handling" in Mail::Reporter

       $obj->notImplemented

           See "Error handling" in Mail::Reporter

       $obj->report([LEVEL])

           See "Error handling" in Mail::Reporter

       $obj->reportAll([LEVEL])

           See "Error handling" in Mail::Reporter

       $obj->trace([LEVEL])

           See "Error handling" in Mail::Reporter

       $obj->warnings

           See "Error handling" in Mail::Reporter

       Cleanup

       $obj->DESTROY

           See "Cleanup" in Mail::Box

       $obj->inGlobalDestruction

           See "Cleanup" in Mail::Reporter

DETAILS
       How IMAP4 folders work

DIAGNOSTICS
       Warning: Cannot find head back for $uidl in $folder.

           The header was read before, but now seems empty: the IMAP4 server
           does not produce the header lines anymore.

       Warning: Cannot read body for $uidl in $folder.

           The header of the message was retreived from the IMAP4 server, but
           the body is not read, for an unknown reason.

       Error: Copying failed for one message.

           For some reason, for instance disc full, removed by external
           process, or read-protection, it is impossible to copy one of the
           messages.  Copying will proceed for the other messages.

       Error: Couldn't select IMAP4 folder $name

       Error: Destination folder $name is not writable.

           The folder where the messages are copied to is not opened with
           write access (see new(access)).  This has no relation with write
           permission to the folder which is controled by your operating
           system.

       Warning: Different messages with id $msgid

           The message id is discovered more than once within the same folder,
           but the content of the message seems to be different.  This should
           not be possible: each message must be unique.

       Error: Folder $name not deleted: not writable.

           The folder must be opened with write access via new(access),
           otherwise removing it will be refused.  So, you may have write-
           access according to the operating system, but that will not
           automatically mean that this "delete" method permits you to.  The
           reverse remark is valid as well.

       Notice: Impossible to keep deleted messages in IMAP

           Some folder type have a 'deleted' flag which can be stored in the
           folder to be performed later.  The folder keeps that knowledge even
           when the folder is rewritten.  Well, IMAP4 cannot play that trick.

       Error: Invalid timespan '$timespan' specified.

           The string does not follow the strict rules of the time span syntax
           which is permitted as parameter.

       Warning: Message $uidl disappeared from $folder.

           Trying to get the specific message from the server, but it appears
           to be gone.

       Warning: Message $uidl disappeared from $folder.

           Trying to get the specific message from the server, but it appears
           to be gone.

       Warning: Message-id '$msgid' does not contain a domain.

           According to the RFCs, message-ids need to contain a unique random
           part, then an "@", and then a domain name.  This is made to avoid
           the creation of two messages with the same id.  The warning emerges
           when the "@" is missing from the string.

       Error: No IMAP4 transporter configured

       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: Unable to create subfolder $name of $folder.

           The copy includes the subfolders, but for some reason it was not
           possible to copy one of these.  Copying will proceed for all other
           sub-folders.

SEE ALSO
       This module is part of Mail-Box distribution version 2.082, built on
       April 28, 2008. Website: http://perl.overmeer.net/mailbox/

LICENSE
       Copyrights 2001-2008 by Mark Overmeer. For other contributors see
       ChangeLog.

       This program is free software; you can redistribute it and/or modify it
       under the same terms as Perl itself.  See
       http://www.perl.com/perl/misc/Artistic.html



perl v5.10.0                      2008-04-28             Mail::Box::IMAP4(3pm)