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.033
River stage one • 8 direct dependents • 8 total dependents
/ Mail::Box::POP3

NAME

Mail::Box::POP3 - handle POP3 folders as client

CLASS INHERITANCE

Mail::Box::POP3 is a Mail::Box::Net is a Mail::Box is a Mail::Reporter

SYNOPSIS

 use Mail::Box::POP3;
 my $folder = new Mail::Box::POP3 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 POP3 protocol. This class uses Mail::Transport::POP3 to hide the transport of information, and focusses solely on the correct handling of messages within a POP3 folder.

METHODS

Initiation

new OPTIONS

For authentications, you have three choices: specify a foldername which resembles an URL, or specify a pop-client object, or separate options for user, password, pop-server and server-port.

 OPTION               DEFAULT
 access               'r'
 authenticate         'AUTO'
 body_delayed_type    'Mail::Message::Body::Delayed'
 body_type            'Mail::Message::Body::Lines'
 coerce_options       []
 create               <not applicable>
 extract              10240
 field_type           undef
 folder               '/'
 folderdir            <not used>
 head_delayed_type    'Mail::Message::Head::Delayed'
 head_type            'Mail::Message::Head::Complete'
 keep_dups            <false>
 lock_file            undef
 lock_timeout         1 hour
 lock_type            'NONE'
 lock_wait            10 seconds
 locker               undef
 log                  'WARNINGS'
 manager              undef
 message_type         'Mail::Box::POP3::Message'
 multipart_type       'Mail::Message::Body::Multipart'
 password             undef
 pop_client           undef
 remove_when_empty    <false>
 save_on_exit         <true>
 server_name          undef
 server_port          110
 trace                'WARNINGS'
 trusted              <false>
 username             undef
access => MODE

See Mail::Box::new(access)

authenticate => 'LOGIN'|'APOP'|'AUTO'

POP3 can use two methods of authentication: the old LOGIN protocol, which transmits a username and password in plain text, and the newer APOP protocol which uses MD5 encryption. APOP is therefore much better, however not always supported by the server. With AUTO, first APOP is tried and if that fails LOGIN.

body_delayed_type => CLASS

See Mail::Box::new(body_delayed_type)

body_type => CLASS|CODE

See Mail::Box::new(body_type)

coerce_options => ARRAY

See Mail::Box::new(coerce_options)

create => BOOLEAN

See Mail::Box::new(create)

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

See Mail::Box::new(extract)

field_type => CLASS

See Mail::Box::new(field_type)

folder => FOLDERNAME

See Mail::Box::new(folder)

folderdir => DIRECTORY

See Mail::Box::new(folderdir)

head_delayed_type => CLASS

See Mail::Box::new(head_delayed_type)

head_type => CLASS

See Mail::Box::new(head_type)

keep_dups => BOOLEAN

See Mail::Box::new(keep_dups)

lock_file => FILENAME

See Mail::Box::new(lock_file)

lock_timeout => SECONDS

See Mail::Box::new(lock_timeout)

lock_type => CLASS|STRING

See Mail::Box::new(lock_type)

lock_wait => SECONDS

See Mail::Box::new(lock_wait)

locker => OBJECT

See Mail::Box::new(locker)

log => LEVEL

See Mail::Reporter::new(log)

manager => MANAGER

See Mail::Box::new(manager)

message_type => CLASS

See Mail::Box::new(message_type)

multipart_type => CLASS

See Mail::Box::new(multipart_type)

password => STRING

See Mail::Box::Net::new(password)

pop_client => OBJECT

You may want to specify your own pop-client object. The object which is passed must extend Mail::Transport::POP3.

remove_when_empty => BOOLEAN

See Mail::Box::new(remove_when_empty)

save_on_exit => BOOLEAN

See Mail::Box::new(save_on_exit)

server_name => HOSTNAME

See Mail::Box::Net::new(server_name)

server_port => INTEGER

See Mail::Box::Net::new(server_port)

trace => LEVEL

See Mail::Reporter::new(trace)

trusted => BOOLEAN

See Mail::Box::new(trusted)

username => STRING

See Mail::Box::Net::new(username)

Examples:

 my $pop = Mail::Box::POP3->new('pop3://user:password@pop.xs4all.nl');

 my $pop = $mgr->open(type => 'pop3', username => 'myname',
    password => 'mypassword', server_name => 'pop.xs4all.nl');

Opening folders

clone OPTIONS

See Mail::Box::clone()

create FOLDER, OPTIONS

It is not possible to create a new folder on a POP3 server. This method will always return false.

 OPTION               DEFAULT
 folderdir            <not used>
folderdir => DIRECTORY

See Mail::Box::create(folderdir)

folderdir [DIRECTORY]

See Mail::Box::Net::folderdir()

foundIn [FOLDERNAME], OPTIONS

See Mail::Box::foundIn()

On open folders

addMessage MESSAGE

It is impossible to write messages to the average POP3 server. There are extensions to the protocol which do permit it, however these are not implemented (yet, patches welcome).

undef is returned, and an error displayed. However, no complaint is given when the MESSAGE is undef itself.

addMessages MESSAGES

As useless as addMessage(). The only acceptable call to this method is without any message.

copyTo FOLDER, OPTIONS

See Mail::Box::copyTo()

modified [BOOLEAN]

See Mail::Box::modified()

name

See Mail::Box::name()

organization

See Mail::Box::organization()

type

See Mail::Box::type()

url

See Mail::Box::url()

writable

See Mail::Box::writable()

write OPTIONS

See Mail::Box::write()

Closing the folder

DESTROY

See Mail::Box::DESTROY()

close OPTIONS

See Mail::Box::close()

delete

It is not possible to delete a POP3 folder remotely: the best we can do is remove all the messages in it... which is the action implemented here. A notice is logged about this.

The messages

current [NUMBER|MESSAGE|MESSAGE-ID]

See Mail::Box::current()

find MESSAGE-ID

See Mail::Box::find()

message INDEX [,MESSAGE]

See Mail::Box::message()

messageId MESSAGE-ID [,MESSAGE]

See Mail::Box::messageId()

messageIds

See Mail::Box::messageIds()

messages ['ALL',RANGE,'ACTIVE','DELETED',LABEL,!LABEL,FILTER]

See Mail::Box::messages()

scanForMessages MESSAGE, MESSAGE-IDS, TIMESTAMP, WINDOW

See Mail::Box::scanForMessages()

Sub-folders

listSubFolders OPTIONS

See Mail::Box::listSubFolders()

nameOfSubfolder NAME

See Mail::Box::nameOfSubfolder()

openRelatedFolder OPTIONS

See Mail::Box::openRelatedFolder()

openSubFolder NAME, OPTIONS

See Mail::Box::openSubFolder()

update

NOT IMPLEMENTED YET

Message threads [internals]

toBeThreaded MESSAGES

See Mail::Box::toBeThreaded()

toBeUnthreaded MESSAGES

See Mail::Box::toBeUnthreaded()

Reading and Writing [internals]

appendMessages OPTIONS

See Mail::Box::appendMessages()

coerce MESSAGE

See Mail::Box::coerce()

determineBodyType MESSAGE, HEAD

See Mail::Box::determineBodyType()

getHead MESSAGE

Read the header for the specified message from the remote server.

getHeadAndBody MESSAGE

Read all data for the specified message from the remote server.

lineSeparator [STRING|'CR'|'LF'|'CRLF']

See Mail::Box::lineSeparator()

locker

See Mail::Box::locker()

popClient

Returns the pop client object. This does not establish the connection.

read OPTIONS

See Mail::Box::read()

readMessages OPTIONS

See Mail::Box::readMessages()

storeMessage MESSAGE

See Mail::Box::storeMessage()

updateMessages OPTIONS

See Mail::Box::updateMessages()

writeMessages OPTIONS

See Mail::Box::writeMessages()

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

inGlobalDestruction

See Mail::Reporter::inGlobalDestruction()

logPriority LEVEL

See Mail::Reporter::logPriority()

logSettings

See Mail::Reporter::logSettings()

notImplemented

See Mail::Reporter::notImplemented()

timespan2seconds TIME

See Mail::Box::timespan2seconds()

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 Liz Mattijsen (liz@dijkmat.nl) and Mark Overmeer (mark@overmeer.net) with the help of many. See the ChangeLog for details.

VERSION

This code is beta, version 2.033.

Copyright (c) 2001-2002 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.