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::Maildir(3pmUser Contributed Perl DocumentatiMail::Box::Maildir(3pm)



NAME
       Mail::Box::Maildir - handle Maildir folders

INHERITANCE
        Mail::Box::Maildir
          is a Mail::Box::Dir
          is a Mail::Box
          is a Mail::Reporter

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

DESCRIPTION
       This documentation describes how Maildir mailboxes work, and what you
       can do with the Maildir folder object "Mail::Box::Maildir".

       Maildir is not supported for Windows, because it create filenames which
       are not accepted by the Windows system.

OVERLOADED
       overload: ""

           See "OVERLOADED" in Mail::Box

       overload: @{}

           See "OVERLOADED" in Mail::Box

       overload: cmp

           See "OVERLOADED" in Mail::Box

METHODS
       Constructors

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

        Option           --Defined in     --Default
        accept_new                          <false>
        access             Mail::Box        'r'
        body_delayed_type  Mail::Box        Mail::Message::Body::Delayed
        body_type          Mail::Box        Mail::Message::Body::Lines
        coerce_options     Mail::Box        []
        create             Mail::Box        <false>
        directory          Mail::Box::Dir   <derived from folder name>
        extract            Mail::Box        10240
        field_type         Mail::Box        undef
        fix_headers        Mail::Box        <false>
        folder             Mail::Box        $ENV{MAIL}
        folderdir          Mail::Box        $ENV{HOME}/.maildir
        head_delayed_type  Mail::Box        Mail::Message::Head::Delayed
        head_type          Mail::Box        Mail::Message::Head::Complete
        keep_dups          Mail::Box        <false>
        lock_file          Mail::Box        <not used>
        lock_timeout       Mail::Box        <not used>
        lock_type          Mail::Box        'NONE' (constant)
        lock_wait          Mail::Box        <not used>
        locker             Mail::Box        undef
        log                Mail::Reporter   'WARNINGS'
        manager            Mail::Box        undef
        message_type       Mail::Box        Mail::Box::Message
        multipart_type     Mail::Box        Mail::Message::Body::Multipart
        remove_when_empty  Mail::Box        <true>
        save_on_exit       Mail::Box        <true>
        trace              Mail::Reporter   'WARNINGS'
        trusted            Mail::Box        <depends on folder location>

           . accept_new => BOOLEAN

               When the folder is open, some messages may be stored in the
               "new" sub-directory.  By default, these messages are
               immediately moved to the "cur" directory when the folder is
               opened.  Otherwise, you have to call acceptMessages() or
               Mail::Box::Maildir::Message::accept().

           . access => MODE

           . body_delayed_type => CLASS

           . body_type => CLASS|CODE

           . coerce_options => ARRAY

           . create => BOOLEAN

           . directory => DIRECTORY

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

           . field_type => CLASS

           . fix_headers => BOOLEAN

           . folder => FOLDERNAME

           . folderdir => DIRECTORY

           . head_delayed_type => CLASS

           . head_type => CLASS

           . 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

           . remove_when_empty => BOOLEAN

           . save_on_exit => BOOLEAN

           . trace => LEVEL

           . trusted => BOOLEAN

       The folder

       $obj->addMessage(MESSAGE, OPTIONS)

           See "The folder" in Mail::Box

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

           See "The folder" in Mail::Box

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

           See "The folder" in Mail::Box

       $obj->close(OPTIONS)

           See "The folder" in Mail::Box

       $obj->copyTo(FOLDER, OPTIONS)

           See "The folder" in Mail::Box

       $obj->delete(OPTIONS)

           See "The folder" in Mail::Box

       $obj->directory

           See "The folder" in Mail::Box::Dir

       $obj->folderdir([DIRECTORY])

           See "The folder" in Mail::Box

       $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::Maildir->listSubFolders(OPTIONS)

           See "Sub-folders" in Mail::Box

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

       Mail::Box::Maildir->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::Maildir->topFolderWithMessages

           See "Sub-folders" in Mail::Box

       Internals

       $obj->acceptMessages

           Accept all messages which are waiting in the "new" directory to be
           moved to the "cur" directory.  This will not rescan the directory
           for newly arrived messages, because that's a task for update().

       Mail::Box::Maildir->appendMessage(OPTIONS)

       $obj->coerce(MESSAGE, OPTIONS)

       $obj->create(FOLDERNAME, OPTIONS)

       Mail::Box::Maildir->create(FOLDERNAME, OPTIONS)

        Option   --Defined in--Default
        folderdir  Mail::Box   undef

           . folderdir => DIRECTORY

       $obj->createDirs(FOLDERDIR)

       Mail::Box::Maildir->createDirs(FOLDERDIR)

           The FOLDERDIR contains the absolute path of the location where the
           messages are kept.  Maildir folders contain a "tmp", "new", and
           "cur" sub-directory within that folder directory as well.  This
           method will ensure that all directories exist.  Returns false on
           failure.

       $obj->determineBodyType(MESSAGE, HEAD)

           See "Internals" in Mail::Box

       $obj->folderIsEmpty(FOLDERDIR)

       Mail::Box::Maildir->folderIsEmpty(FOLDERDIR)

           Checks whether the folder whose directory is specified as absolute
           FOLDERDIR is empty or not.  A folder is empty when the "tmp",
           "new", and "cur" subdirectories are empty and some files which are
           left there by application programs.  The maildir spec explicitly
           states: ".qmail", "bulletintime", "bulletinlock" and "seriallock".
           If any other files are found, the directory is considered not-
           empty.

       $obj->folderToDirectory(FOLDERNAME, FOLDERDIR)

           See "Internals" in Mail::Box::Dir

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

           See "Internals" in Mail::Box

       $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->readMessageFilenames(DIRECTORY)

           See "Internals" in Mail::Box::Dir

       $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->updateMessages(OPTIONS)

           See "Internals" in Mail::Box

       $obj->write(OPTIONS)

           See "Internals" in Mail::Box

       $obj->writeMessages(OPTIONS)

           See "Internals" in Mail::Box

       Other methods

       $obj->timespan2seconds(TIME)

       Mail::Box::Maildir->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::Maildir->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::Maildir->log([LEVEL [,STRINGS]])

           See "Error handling" in Mail::Reporter

       $obj->logPriority(LEVEL)

       Mail::Box::Maildir->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
       The explanation is complicated, but for normal use you should bother
       yourself with all details.

       How MAILDIR folders work

       Maildir-type folders use a directory to store the messages of one
       folder.  Each message is stored in a separate file.  This seems useful,
       because changes in a folder change only a few of these small files, in
       contrast with file-based folders where changes in a folder cause
       rewrites of huge folder-files.

       However, Maildir based folders perform very bad if you need header
       information of all messages.  For instance, if you want to have full
       knowledge about all message-threads (see Mail::Box::Thread::Manager) in
       the folder, it requires to read all header lines in all message files.
       And usually, reading your messages as threads is desired.  Maildir
       maintains a tiny amount of info visible in the filename, which may make
       it perform just a little bit faster than MH.

DIAGNOSTICS
       Error: Cannot append Maildir message in $new to folder $self.

           The message (or messages) could not be stored in the right
           directories for the Maildir folder.

       Error: Cannot create Maildir directory $dir: $!

           A Maildir folder is represented by a directory, with some sub-
           directories.  The top folder directory could not be created for the
           reason indicated.

       Error: Cannot create Maildir folder $name.

           One or more of the directories required to administer a Maildir
           folder could not be created.

       Error: Cannot create Maildir message file $new.

           A message is converted from some other message format into a
           Maildir format by writing it to a file with a name which contains
           the status flags of the message.  Apparently, creating this file
           failed.

       Error: Cannot create Maildir subdir $dir: $!

           Each Maildir folder has three sub-directories for administration:
           "new", "tmp", and "cur".  The mentioned directory could not be
           created for the indicated reason.

       Warning: Changes not written to read-only folder $self.

           You have opened the folder read-only --which is the default set by
           new(access)--, made modifications, and now want to close it.  Set
           close(force) if you want to overrule the access mode, or close the
           folder with close(write) set to "NEVER".

       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: 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 is opened read-only

           You can not write to this folder unless you have opened the folder
           to write or append with new(access), or the "force" option is set
           true.

       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.

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

       Error: Writing folder $name failed

           For some reason (you probably got more error messages about this
           problem) it is impossible to write the folder, although you should
           because there were changes made.

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::Maildir(3pm)