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 fix_headers <false> 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)
- fix_headers => BOOLEAN
-
See Mail::Box::new(fix_headers)
- 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::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 isundef
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.036.
Copyright (c) 2001-2003 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.