/ 
Mail-Box-2.017
River stage one • 8 direct dependents • 8 total dependents
/ Mail::Box::Maildir

NAME

Mail::Box::Maildir - handle Maildir folders

CLASS HIERARCHY

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. Please read Mail::Box-Overview and Mail::Box::Dir first.

Maildir is not supported for Windows, because it create filenames which are not accepted by the Windows system. The internal organization and details are found at the bottom of this manual-page.

METHOD INDEX

Methods prefixed with an abbreviation are described in Mail::Box (MB), Mail::Reporter (MR), Mail::Box::Dir (MBD).

The general methods for Mail::Box::Maildir objects:

 MB addMessage  MESSAGE               MR log [LEVEL [,STRINGS]]
 MB addMessages MESSAGE [, MESS...    MB message INDEX [,MESSAGE]
 MB close OPTIONS                     MB messageId MESSAGE-ID [,MESS...
 MB copyTo FOLDER, OPTIONS            MB messageIds
 MB create FOLDERNAME [, OPTIONS]     MB messages ['ALL',RANGE,'ACTI...
    createDirs FOLDERDIR              MB modified [BOOLEAN]
 MB current [NUMBER|MESSAGE|MES...    MB name
 MB delete                               new OPTIONS
MBD directory                         MB openSubFolder NAME [,OPTIONS]
 MR errors                            MR report [LEVEL]
 MB find MESSAGE-ID                   MR reportAll [LEVEL]
    folderIsEmpty FOLDERDIR           MR trace [LEVEL]
 MB listSubFolders OPTIONS            MR warnings
 MB locker                            MB writable

The extra methods for extension writers:

 MR AUTOLOAD                          MB organization
 MB DESTROY                           MB read OPTIONS
 MB appendMessages OPTIONS           MBD readAllHeaders
 MB clone OPTIONS                    MBD readMessageFilenames DIRECTORY
 MB coerce MESSAGE                    MB readMessages OPTIONS
 MB determineBodyType MESSAGE, ...    MB scanForMessages MESSAGE, ME...
MBD folderToDirectory FOLDERNAM...    MB sort PREPARE, COMPARE, LIST
 MB folderdir [DIR]                   MB storeMessage MESSAGE
 MB foundIn [FOLDERNAME], OPTIONS     MB timespan2seconds TIME
 MR inGlobalDestruction               MB toBeThreaded MESSAGES
 MB lineSeparator [STRING|'CR'|...    MB toBeUnthreaded MESSAGES
 MR logPriority LEVEL                 MB update OPTIONS
 MR logSettings                       MB updateMessages OPTIONS
 MR notImplemented                    MB write OPTIONS
 MB openRelatedFolder OPTIONS            writeMessages [OPTIONS]

METHODS

new OPTIONS

Create a new folder. The are many options which are taken from other objects. For some, different options are set. For MH-specific options see below, but first the full list.

OPTION            DEFINED BY         DEFAULT
access            Mail::Box          'r'
create            Mail::Box          0
folder            Mail::Box          $ENV{MAIL}
folderdir         Mail::Box          <no default>
head_wrap         Mail::Box          72
keep_dups         Mail::Box          0
extract           Mail::Box          10kB
lock_type         Mail::Box          'NONE'  # constant
lock_file         Mail::Box          <not used>
lock_timeout      Mail::Box          <not used>
lock_wait         Mail::Box          <not used>
log               Mail::Reporter     'WARNINGS'
remove_when_empty Mail::Box          1
save_on_exit      Mail::Box          1
trace             Mail::Reporter     'WARNINGS'
trusted           Mail::Box          <depends on folder location>

Only useful to write extension to Mail::Box::MH. Common users of folders you will not specify these:

OPTION            DEFINED BY         DEFAULT
body_type         Mail::Box::Dir     <see Mail::Box::Dir>
body_delayed_type Mail::Box          'Mail::Message::Body::Delayed'
coerce_options    Mail::Box          []
field_type        Mail::Box          undef
head_type         Mail::Box          'Mail::Message::Head::Complete'
head_delayed_type Mail::Box          'Mail::Message::Head::Delayed'
locker            Mail::Box          <not used>
multipart_type    Mail::Box          'Mail::Message::Body::Multipart'
manager           Mail::Box          undef
message_type      Mail::Box          'Mail::Box::MH::Message'
realhead_type     Mail::Box          'Mail::Message::Head'

MH specific options:

createDirs FOLDERDIR

(Instance or class method) 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.

folderIsEmpty FOLDERDIR

(Instance or class method) 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.

METHODS for extension writers

writeMessages [OPTIONS]

Write all messages to the folder-file.

OPTION            DEFINED BY         DEFAULT
force             Mail::Box          <true>
head_wrap         Mail::Box          72
keep_deleted      Mail::Box          <false>
save_deleted      Mail::Box          <false>

IMPLEMENTATION

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

The following information was found at http://cr.yp.to/proto/maildir.html. Each message is written in a seperate file. The filename is constructed from the time-of-arrival, a unique component, hostname, a syntax marker, and flags. For example 1014220791.meteor.42:2,DF. The filename must match:

my ($time, $unique, $hostname, $info)
   = $filename =~ m!^(\d+)\.(.*)\.(\w+)(\:.*)?$!;
my ($semantics, $flags)
   = $info =~ m!([12])\,([RSTDF]+)$!;
my @flags = split //, $flags;

The @flags are sorted alphabetically, with the following meanings:

D = draft, to be sent later
F = flagged for user-defined purpose
R = has been replied
S = seen / (partially) read by the user
T = trashed, flagged to be deleted later

Labels

The filename contains flags, and those flags are translated into labels when the folder is opened. Labels can be changed by the application using the labels method.

Changes will directly reflect in a filename change. The Status and X-Status lines in the header, which are used by Mbox kind of folders, are ignored except when a new message is received in the new directory. In case a message has to be written to file for some reason, the status header lines are updated as well.

SEE ALSO

Mail::Box-Overview

For support and additional documentation, see http://perl.overmeer.net/mailbox/

AUTHOR

Mark Overmeer (mailbox@overmeer.net). All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

VERSION

This code is beta, version 2.017.

Copyright (c) 2001-2002 Mark Overmeer. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.