OVERLOADED

overload: ""
See "" in Mail::Box.
overload: @{}
See @{} in Mail::Box.
overload: cmp
See cmp in Mail::Box.

METHODS

See METHODS in Mail::Reporter

Constructors

$class->new( OPTIONS )
Option Defined in Default

access

Mail::Box

'r'

body_delayed_type

Mail::Box

Mail::Message::Body::Delayed

body_type

<see description>

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

$ENV{MAIL}

folderdir

Mail::Box

$ENV{HOME}.'/Mail'

head_delayed_type

Mail::Box

Mail::Message::Head::Delayed

head_type

Mail::Box

Mail::Message::Head::Complete

keep_dups

Mail::Box

<false>

lock_extension

'.lock'

lock_file

Mail::Box

<foldername><lock-extension>

lock_timeout

Mail::Box

1 hour

lock_type

Mail::Box

Mail::Box::Locker::DotLock

lock_wait

Mail::Box

10 seconds

locker

Mail::Box

undef

log

Mail::Reporter

'WARNINGS'

manager

Mail::Box

undef

message_type

Mail::Box

Mail::Box::File::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>

write_policy

undef

access => MODE
body_delayed_type => CLASS
body_type => CLASS|CODE
The default body_type option for File folders, which will cause messages larger than 10kB to be stored in files and smaller files in memory, is implemented like this:
 sub determine_body_type($$)
 {   my $head = shift;
     my $size = shift || 0;
     'Mail::Message::Body::'
        . ($size > 10000 ? 'File' : 'Lines');
 }
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
keep_dups => BOOLEAN
lock_extension => FILENAME|STRING
When the dotlock locking mechanism is used, the lock is created with a hardlink to the folder file. For Mail::Box::File type of folders, this file is by default named as the folder-file itself followed by .lock. For example: the Mail/inbox folder file will have a hardlink made as Mail/inbox.lock.
You may specify an absolute filename, a relative (to the folder's directory) filename, or an extension (preceded by a dot). So valid examples are:
 .lock        # appended to the folder's filename
 my_own_lockfile.test   # full filename, same dir
 /etc/passwd            # somewhere else
When the program runs with less priviledges (as normal user), often the default inbox folder can not be locked with the lockfile name which is produced by default.
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
write_policy => 'REPLACE'|'INPLACE'|undef
Sets the default write policy, as default for a later call to write(policy). With undef, the best policy is autodetected.
» Error: Cannot get a lock on $type folder $self.

A lock is required to get access to the folder. If no locking is needed, specify the NONE lock type.

» Warning: Folder $name file $filename is write-protected.

The folder is opened writable or for appending via new(access), but the operating system does not permit writing to the file. The folder will be opened read-only.

The folder

$obj->addMessage( MESSAGE, OPTIONS )
See addMessage in Mail::Box.
$obj->addMessages( MESSAGE [, MESSAGE, ...] )
See addMessages in Mail::Box.
$class->appendMessages( OPTIONS )

Appending messages to a file based folder which is not opened is a little risky. In practice, this is often done without locking the folder. So, an other application may write to the folder at the same time... :( Hopefully, all goes fast enough that the chance on collition is small.

All OPTIONS of Mail::Box::Mbox::new() can be supplied.

Option Defined in Default

folder

Mail::Box

<required>

lock_type

NONE

message

Mail::Box

undef

messages

Mail::Box

undef

share

Mail::Box

<false>

folder => FOLDERNAME
lock_type => ...
See Mail::Box::new(lock_type) for possible values.
message => MESSAGE
messages => ARRAY-OF-MESSAGES
share => BOOLEAN
» Error: Cannot append messages to folder file $filename: $!

Appending messages to a not-opened file-organized folder may fail when the operating system does not allow write access to the file at hand.

$obj->close( OPTIONS )
See close in Mail::Box.
$obj->copyTo( FOLDER, OPTIONS )
See copyTo in Mail::Box.
$obj->delete( OPTIONS )
See delete in Mail::Box.
$obj->filename

Returns the filename for this folder, which may be an absolute or relative path to the file.

» Example:
 print $folder->filename;
$obj->folderdir( [DIRECTORY] )
See folderdir in Mail::Box.
$obj->name
See name in Mail::Box.
$obj->organization
See organization in Mail::Box.
$obj->size
See size in Mail::Box.
$obj->type
See type in Mail::Box.
$obj->update( OPTIONS )
See update in Mail::Box.
$obj->url
See url in Mail::Box.

Folder flags

$obj->access
See access in Mail::Box.
$obj->isModified
See isModified in Mail::Box.
$obj->modified( [BOOLEAN] )
See modified in Mail::Box.
$obj->writable
See writable in Mail::Box.

The messages

$obj->current( [NUMBER|MESSAGE|MESSAGE-ID] )
See current in Mail::Box.
$obj->find( MESSAGE-ID )
See find in Mail::Box.
$obj->findFirstLabeled( LABEL, [BOOLEAN, [ARRAY-OF-MSGS]] )
See findFirstLabeled in Mail::Box.
$obj->message( INDEX [,MESSAGE] )
See message in Mail::Box.
$obj->messageId( MESSAGE-ID [,MESSAGE] )
See messageId in Mail::Box.
$obj->messageIds
See messageIds in Mail::Box.
$obj->messages( ['ALL',RANGE,'ACTIVE','DELETED',LABEL,!LABEL,FILTER] )
See messages in Mail::Box.
$obj->nrMessages( OPTIONS )
See nrMessages in Mail::Box.
$obj->scanForMessages( MESSAGE, MESSAGE-IDS, TIMESPAN, WINDOW )
See scanForMessages in Mail::Box.

Sub-folders

$obj->listSubFolders( OPTIONS )
$class->listSubFolders( OPTIONS )
See listSubFolders in Mail::Box.
$obj->nameOfSubFolder( SUBNAME, [PARENTNAME] )
$class->nameOfSubFolder( SUBNAME, [PARENTNAME] )
See nameOfSubFolder in Mail::Box.
$obj->openRelatedFolder( OPTIONS )
See openRelatedFolder in Mail::Box.
$obj->openSubFolder( SUBNAME, OPTIONS )
See openSubFolder in Mail::Box.
$obj->topFolderWithMessages
$class->topFolderWithMessages
See topFolderWithMessages in Mail::Box.

Internals

$obj->coerce( MESSAGE, OPTIONS )
See coerce in Mail::Box.
$obj->create( FOLDERNAME, OPTIONS )
$class->create( FOLDERNAME, OPTIONS )
Option Defined in Default

folderdir

Mail::Box

undef

folderdir => DIRECTORY
» Error: Cannot create directory $dir for folder $name.

While creating a file-organized folder, at most one level of directories is created above it. Apparently, more levels of directories are needed, or the operating system does not allow you to create the directory.

» Error: Cannot create folder file $name: $!

The file-organized folder file cannot be created for the indicated reason. In common cases, the operating system does not grant you write access to the directory where the folder file should be stored.

$obj->determineBodyType( MESSAGE, HEAD )
See determineBodyType in Mail::Box.
$obj->folderToFilename( FOLDERNAME, FOLDERDIR, [SUBEXT] )
$class->folderToFilename( FOLDERNAME, FOLDERDIR, [SUBEXT] )

Translate a folder name into a filename, using the FOLDERDIR value to replace a leading =. SUBEXT is only used for MBOX folders.

$class->foundIn( [FOLDERNAME], OPTIONS )
See foundIn in Mail::Box.
$obj->lineSeparator( [STRING|'CR'|'LF'|'CRLF'] )
See lineSeparator in Mail::Box.
$obj->locker
See locker in Mail::Box.
$obj->messageCreateOptions( [TYPE, CONFIG] )

Returns a key-value list of options to be used each time a new message is read from a file. The list is preceeded by the TYPE of message which has to be created.

This data is used by readMessages() and updateMessages(). With TYPE and CONFIG, a new configuration is set.

$obj->moveAwaySubFolder( DIRECTORY, EXTENSION )

The DIRECTORY is renamed by appending the EXTENSION, which defaults to ".d", to make place for a folder file on that specific location. false is returned if this failed.

» Error: Cannot move away sub-folder $dir
$obj->parser

Create a parser for this mailbox. The parser stays alive as long as the folder is open.

$obj->read( OPTIONS )
See read in Mail::Box.
$obj->readMessages( OPTIONS )
See readMessages in Mail::Box.
$obj->storeMessage( MESSAGE )
See storeMessage in Mail::Box.
$obj->toBeThreaded( MESSAGES )
See toBeThreaded in Mail::Box.
$obj->toBeUnthreaded( MESSAGES )
See toBeUnthreaded in Mail::Box.
$obj->updateMessages( OPTIONS )

For file based folders, the file handle stays open until the folder is closed. Update is therefore rather simple: move to the end of the last known message, and continue reading...

$obj->write( OPTIONS )
Option Defined in Default

force

Mail::Box

<false>

policy

undef

save_deleted

Mail::Box

<false>

force => BOOLEAN
policy => 'REPLACE'|'INPLACE'|undef
In what way will the mail folder be updated. If not specified during the write, the value of the new(write_policy) at folder creation is taken.
Valid values:
  • REPLACE

    First a new folder is written in the same directory as the folder which has to be updated, and then a call to move will throw away the old immediately replacing it by the new.
    Writing in REPLACE module is slightly optimized: messages which are not modified are copied from file to file, byte by byte. This is much faster than printing the data which is will be done for modified messages.
  • INPLACE

    The original folder file will be opened read/write. All message which where not changed will be left untouched, until the first deleted or modified message is detected. All further messages are printed again.
  • undef

    As default, or when undef is explicitly specified, first REPLACE mode is tried. Only when that fails, an INPLACE update is performed.

INPLACE will be much faster than REPLACE when applied on large folders, however requires the truncate function to be implemented on your operating system (at least available for recent versions of Linux, Solaris, Tru64, HPUX). It is also dangerous: when the program is interrupted during the update process, the folder is corrupted. Data may be lost.
However, in some cases it is not possible to write the folder with REPLACE. For instance, the usual incoming mail folder on UNIX is stored in a directory where a user can not write. Of course, the root and mail users can, but if you want to use this Perl module with permission of a normal user, you can only get it to work in INPLACE mode. Be warned that in this case folder locking via a lockfile is not possible as well.
save_deleted => BOOLEAN
» Warning: Cannot remove folder $name file $filename: $!

Writing an empty folder will usually cause that folder to be removed, which fails for the indicated reason. new(remove_when_empty)

» Warning: Cannot remove folder $name file $filename: $!

Writing an empty folder will usually cause that folder to be removed, which fails for the indicated reason. new(remove_when_empty) controls whether the empty folder will removed; setting it to false (0) may be needed to avoid this message.

» Error: Cannot replace $filename by $tempname, to update folder $name: $!

The replace policy wrote a new folder file to update the existing, but was unable to give the final touch: replacing the old version of the folder file for the indicated reason.

» Error: File too short to get write message $nr ($size, $need)

Mail::Box is lazy: it tries to leave messages in the folders until they are used, which saves time and memory usage. When this message appears, something is terribly wrong: some lazy message are needed for updating the folder, but they cannot be retreived from the original file anymore. In this case, messages can be lost.

This message does appear regularly on Windows systems when using the 'replace' write policy. Please help to find the cause, probably something to do with Windows incorrectly handling multiple filehandles open in the same file.

» Error: Unable to update folder $self.

When a folder is to be written, both replace and inplace write policies are tried, If both fail, the whole update fails. You may see other, related, error messages to indicate the real problem.

$obj->writeMessages( OPTIONS )
See writeMessages in Mail::Box.

File based folders

File based folders maintain a folder (a set of messages) in one single file. The advantage is that your folder has only one single name, which speeds-up access to all messages at once.

The disadvantage over directory based folder (see Mail::Box::Dir) is that you have to construct some means to keep all message apart, for instance by adding a message separator, and this will cause problems. Where access to all messages at once is faster in file based folders, access to a single message is (much) slower, because the whole folder must be read.

File based folders

File based folders maintain a folder (a set of messages) in one single file. The advantage is that your folder has only one single name, which speeds-up access to all messages at once.

The disadvantage over directory based folder (see Mail::Box::Dir) is that you have to construct some means to keep all message apart, for instance by adding a message separator, and this will cause problems. Where access to all messages at once is faster in file based folders, access to a single message is (much) slower, because the whole folder must be read.

Other methods

$obj->timespan2seconds( TIME )
$class->timespan2seconds( TIME )
See timespan2seconds in Mail::Box.

Error handling

$obj->AUTOLOAD
See AUTOLOAD in Mail::Reporter.
$obj->addReport( OBJECT )
See addReport in Mail::Reporter.
$obj->defaultTrace( [LEVEL]|[LOGLEVEL, TRACELEVEL]|[LEVEL, CALLBACK] )
$class->defaultTrace( [LEVEL]|[LOGLEVEL, TRACELEVEL]|[LEVEL, CALLBACK] )
See defaultTrace in Mail::Reporter.
$obj->errors
See errors in Mail::Reporter.
$obj->log( [LEVEL [,STRINGS]] )
$class->log( [LEVEL [,STRINGS]] )
See log in Mail::Reporter.
$obj->logPriority( LEVEL )
$class->logPriority( LEVEL )
See logPriority in Mail::Reporter.
$obj->logSettings
See logSettings in Mail::Reporter.
$obj->notImplemented
See notImplemented in Mail::Reporter.
$obj->report( [LEVEL] )
See report in Mail::Reporter.
$obj->reportAll( [LEVEL] )
See reportAll in Mail::Reporter.
$obj->trace( [LEVEL] )
See trace in Mail::Reporter.
$obj->warnings
See warnings in Mail::Reporter.

Cleanup

$obj->DESTROY
See DESTROY in Mail::Box.
$obj->inGlobalDestruction
See inGlobalDestruction in Mail::Reporter.