/ 
Mail-Box-2.023
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

WARNING: THE POP3 IMPLEMENTATION IS UNDER CONSTRUCTION: IT WILL *NOT* WORK AT ALL!!!!

This documentation describes how POP3 mailboxes work, and what you can do with the POP3 folder object Mail::Box::POP3. Please read Mail::Box-Overview and Mail::Box first.

The internal organization and details are found at the bottom of this manual-page.

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         'LOGIN'
body_delayed_type    'Mail::Message::Body::Delayed'
body_type            'Mail::Message::Body::Lines'
coerce_options       []
create               <false>
extract              10240
field_type           undef
folder               $ENV{MAIL}
folderdir            undef
head_delayed_type    'Mail::Message::Head::Delayed'
head_type            'Mail::Message::Head::Complete'
keep_dups            <false>
lock_file            <not used>
lock_timeout         <not used>
lock_type            <not used>
lock_wait            <not used>
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              <depends on folder location>
username             undef
access => MODE

See Mail::Box::new(access)

authenticate => 'LOGIN'|'APOP'

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.

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 FOLDERNAME, OPTIONS

See Mail::Box::create()

folderdir [DIRECTORY]

See Mail::Box::folderdir()

foundIn [FOLDERNAME], OPTIONS

See Mail::Box::foundIn()

On open folders

addMessage MESSAGE

See Mail::Box::addMessage()

addMessages MESSAGE [, MESSAGE, ...]

See Mail::Box::addMessages()

copyTo FOLDER, OPTIONS

See Mail::Box::copyTo()

modified [BOOLEAN]

See Mail::Box::modified()

name

See Mail::Box::name()

organization

See Mail::Box::organization()

update OPTIONS

See Mail::Box::update()

writable

See Mail::Box::writable()

Closing the folder

DESTROY

See Mail::Box::DESTROY()

close OPTIONS

See Mail::Box::close()

delete

See Mail::Box::delete()

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

openRelatedFolder OPTIONS

See Mail::Box::openRelatedFolder()

openSubFolder NAME, OPTIONS

See Mail::Box::openSubFolder()

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

write OPTIONS

See Mail::Box::write()

writeMessages

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

IMPLEMENTATION

How POP3-folders work

This implementation

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

Mark Overmeer (mark@overmeer.net) with the help of many.

VERSION

This code is beta, version 2.023.

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.