Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Mail::Box::POP3(3)    User Contributed Perl Documentation   Mail::Box::POP3(3)

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

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

	Mail::Box::POP3	is extended by
	  Mail::Box::POP3s

SYNOPSIS
	use Mail::Box::POP3;
	my $folder = Mail::Box::POP3->new(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.

       See documentation in the	base class.

OVERLOADED
       See documentation in the	base class.

       overload: ""()
	   See "OVERLOADED" in Mail::Box

       overload: @{}()
	   See "OVERLOADED" in Mail::Box

       overload: cmp()
	   See "OVERLOADED" in Mail::Box

METHODS
       See documentation in the	base class.

   Constructors
       See documentation in the	base class.

       Mail::Box::POP3->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	      --Defined	in     --Default
	     access		Mail::Box	 'r'
	     authenticate			 'AUTO'
	     body_delayed_type	Mail::Box	 Mail::Message::Body::Delayed
	     body_type		Mail::Box	 Mail::Message::Body::Lines
	     coerce_options	Mail::Box	 []
	     create		Mail::Box	 <not applicable>
	     extract		Mail::Box	 10240
	     field_type		Mail::Box	 undef
	     fix_headers	Mail::Box	 <false>
	     folder		Mail::Box	 <not applicable>
	     folderdir		Mail::Box	 <not used>
	     head_delayed_type	Mail::Box	 Mail::Message::Head::Delayed
	     head_type		Mail::Box	 Mail::Message::Head::Complete
	     keep_dups		Mail::Box	 <false>
	     lock_file		Mail::Box	 undef
	     lock_timeout	Mail::Box	 1 hour
	     lock_type		Mail::Box	 'NONE'
	     lock_wait		Mail::Box	 10 seconds
	     locker		Mail::Box	 undef
	     log		Mail::Reporter	 'WARNINGS'
	     manager		Mail::Box	 undef
	     message_type	Mail::Box	 Mail::Box::POP3::Message
	     multipart_type	Mail::Box	 Mail::Message::Body::Multipart
	     password		Mail::Box::Net	 undef
	     pop_client				 undef
	     remove_when_empty	Mail::Box	 <false>
	     save_on_exit	Mail::Box	 <true>
	     server_name	Mail::Box::Net	 undef
	     server_port	Mail::Box::Net	 110
	     trace		Mail::Reporter	 'WARNINGS'
	     trusted		Mail::Box	 <false>
	     username		Mail::Box::Net	 undef

	   access => MODE
	   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
	   body_type =>	CLASS|CODE
	   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_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
	   password => STRING
	   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
	   save_on_exit	=> BOOLEAN
	   server_name => HOSTNAME
	   server_port => INTEGER
	   trace => LEVEL
	   trusted => BOOLEAN
	   username => STRING

	   example:

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

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

   The folder
       See documentation in the	base class.

       $obj->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.

	    -Option--Defined in--Default
	     share   Mail::Box	 <not used>

	   share => BOOLEAN
       $obj->addMessages(MESSAGES)
	   As useless as addMessage().	The only acceptable call to this
	   method is without any message.

       Mail::Box::POP3->appendMessages(OPTIONS)
	   See "The folder" in Mail::Box

       $obj->close(OPTIONS)
	   See "The folder" in Mail::Box

       $obj->copyTo(FOLDER, OPTIONS)
	   See "The folder" in Mail::Box

       $obj->delete(OPTIONS)
	   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.

	    -Option   --Defined	in--Default
	     recursive	Mail::Box   <not used>

	   recursive =>	BOOLEAN
       $obj->folderdir([DIRECTORY])
	   See "METHODS" in Mail::Box::Net

       $obj->name()
	   See "The folder" in Mail::Box

       $obj->organization()
	   See "The folder" in Mail::Box

       $obj->size()
	   See "The folder" in Mail::Box

       $obj->type()
	   See "The folder" in Mail::Box

       $obj->update()
	   NOT IMPLEMENTED YET

       $obj->url()
	   See "The folder" in Mail::Box

   Folder flags
       See documentation in the	base class.

       $obj->access()
	   See "Folder flags" in Mail::Box

       $obj->isModified()
	   See "Folder flags" in Mail::Box

       $obj->modified([BOOLEAN])
	   See "Folder flags" in Mail::Box

       $obj->writable()
	   See "Folder flags" in Mail::Box

   The messages
       See documentation in the	base class.

       $obj->current([NUMBER|MESSAGE|MESSAGE-ID])
	   See "The messages" in Mail::Box

       $obj->find(MESSAGE-ID)
	   See "The messages" in Mail::Box

       $obj->findFirstLabeled(LABEL, [BOOLEAN, [ARRAY-OF-MSGS]])
	   See "The messages" in Mail::Box

       $obj->message(INDEX [,MESSAGE])
	   See "The messages" in Mail::Box

       $obj->messageId(MESSAGE-ID [,MESSAGE])
	   See "The messages" in Mail::Box

       $obj->messageIds()
	   See "The messages" in Mail::Box

       $obj->messages(['ALL',RANGE,'ACTIVE','DELETED',LABEL,!LABEL,FILTER])
	   See "The messages" in Mail::Box

       $obj->nrMessages(OPTIONS)
	   See "The messages" in Mail::Box

       $obj->scanForMessages(MESSAGE, MESSAGE-IDS, TIMESPAN, WINDOW)
	   See "The messages" in Mail::Box

   Sub-folders
       See documentation in the	base class.

       $obj->listSubFolders(OPTIONS)
       Mail::Box::POP3->listSubFolders(OPTIONS)
	   The standard	POP3 protocol does not support sub-folders, so an
	   empty list will be returned in any case.

	    -Option    --Defined in	--Default
	     check	 Mail::Box	  <false>
	     folder	 Mail::Box	  <from	calling	object>
	     folderdir	 Mail::Box	  <from	folder>
	     skip_empty	 Mail::Box	  <false>

	   check => BOOLEAN
	   folder => FOLDERNAME
	   folderdir =>	DIRECTORY
	   skip_empty => BOOL
       $obj->nameOfSubFolder(SUBNAME, [PARENTNAME])
       Mail::Box::POP3->nameOfSubFolder(SUBNAME, [PARENTNAME])
	   See "Sub-folders" in	Mail::Box

       $obj->openRelatedFolder(OPTIONS)
	   See "Sub-folders" in	Mail::Box

       $obj->openSubFolder(OPTIONS)
	   It is not possible to open a	sub-folder for a POP3 folder, because
	   that	is not supported by the	official POP3 protocol.	In any case,
	   "undef" is returned to indicate a failure.

       $obj->topFolderWithMessages()
       Mail::Box::POP3->topFolderWithMessages()
	   See "Sub-folders" in	Mail::Box

   Internals
       See documentation in the	base class.

       $obj->coerce(MESSAGE, OPTIONS)
	   See "Internals" in Mail::Box

       $obj->create(FOLDER, OPTIONS)
       Mail::Box::POP3->create(FOLDER, OPTIONS)
	   It is not possible to create	a new folder on	a POP3 server.	This
	   method will always return "false".

	    -Option   --Defined	in--Default
	     folderdir	Mail::Box   <not used>

	   folderdir =>	DIRECTORY
       $obj->determineBodyType(MESSAGE,	HEAD)
	   See "Internals" in Mail::Box

       Mail::Box::POP3->foundIn([FOLDERNAME], OPTIONS)
	   See "Internals" in Mail::Box

       $obj->getHead(MESSAGE)
	   Read	the header for the specified message from the remote server.

       $obj->getHeadAndBody(MESSAGE)
	   Read	all data for the specified message from	the remote server.

       $obj->lineSeparator([STRING|'CR'|'LF'|'CRLF'])
	   See "Internals" in Mail::Box

       $obj->locker()
	   See "Internals" in Mail::Box

       $obj->popClient(OPTIONS)
	   Returns the pop client object.  This	does not establish the
	   connection.

	    -Option --Default
	     use_ssl  <false>

	   use_ssl => BOOLEAN
       $obj->read(OPTIONS)
	   See "Internals" in Mail::Box

       $obj->readMessages(OPTIONS)
	   See "Internals" in Mail::Box

       $obj->storeMessage(MESSAGE)
	   See "Internals" in Mail::Box

       $obj->toBeThreaded(MESSAGES)
	   See "Internals" in Mail::Box

       $obj->toBeUnthreaded(MESSAGES)
	   See "Internals" in Mail::Box

       $obj->updateMessages(OPTIONS)
	   See "Internals" in Mail::Box

       $obj->write(OPTIONS)
	   See "Internals" in Mail::Box

       $obj->writeMessages(OPTIONS)
	    -Option  --Defined in--Default
	     messages  Mail::Box   <required>

	   messages => ARRAY

   Other methods
       See documentation in the	base class.

       $obj->timespan2seconds(TIME)
       Mail::Box::POP3->timespan2seconds(TIME)
	   See "Other methods" in Mail::Box

   Error handling
       See documentation in the	base class.

       $obj->AUTOLOAD()
	   See "Error handling"	in Mail::Reporter

       $obj->addReport(OBJECT)
	   See "Error handling"	in Mail::Reporter

       $obj->defaultTrace([LEVEL]|[LOGLEVEL, TRACELEVEL]|[LEVEL, CALLBACK])
       Mail::Box::POP3->defaultTrace([LEVEL]|[LOGLEVEL,	TRACELEVEL]|[LEVEL,
       CALLBACK])
	   See "Error handling"	in Mail::Reporter

       $obj->errors()
	   See "Error handling"	in Mail::Reporter

       $obj->log([LEVEL	[,STRINGS]])
       Mail::Box::POP3->log([LEVEL [,STRINGS]])
	   See "Error handling"	in Mail::Reporter

       $obj->logPriority(LEVEL)
       Mail::Box::POP3->logPriority(LEVEL)
	   See "Error handling"	in Mail::Reporter

       $obj->logSettings()
	   See "Error handling"	in Mail::Reporter

       $obj->notImplemented()
	   See "Error handling"	in Mail::Reporter

       $obj->report([LEVEL])
	   See "Error handling"	in Mail::Reporter

       $obj->reportAll([LEVEL])
	   See "Error handling"	in Mail::Reporter

       $obj->trace([LEVEL])
	   See "Error handling"	in Mail::Reporter

       $obj->warnings()
	   See "Error handling"	in Mail::Reporter

   Cleanup
       See documentation in the	base class.

       $obj->DESTROY()
	   See "Cleanup" in Mail::Box

DETAILS
       See documentation in the	base class.

   Different kinds of folders
       See documentation in the	base class.

   Available folder types
       See documentation in the	base class.

   Folder class	implementation
       See documentation in the	base class.

   How POP3 folders work
       Rfc1939 defines how POP3	works.	POP3 is	a really simple	protocol to
       receive messages	from a server to a user's client.  POP3	is also	really
       limited:	it can only be used to fetch messages, but has not many	ways
       to limit	the amount of network traffic, like the	IMAP4 protocol has.

       One POP3	account	represents only	one folder: there is no	way of sub-
       folders in POP3.	 POP3 doesn't support writing (except for some message
       status flags).

   This	implementation
       The protocol specifics are implemented in Mail::Transport::POP3,
       written by Liz Mattijsen.  That module does not use any of the other
       POP3 modules available on CPAN for the reason that MailBox tries	to be
       smarter:	it is capable of re-establishing broken	POP3 connection	when
       the server supports UIDs.

       The implementation has shown to work with many different	POP servers.
       In the test directory of	the distribution, you will find	a small	server
       implementation, which is	used to	test the client.

DIAGNOSTICS
       Error: Cannot create POP3 client	for $name.
	   The connection to the POP3 server cannot be established.  You may
	   see more, related, error messages about the failure.

       Error: Cannot find head back for	$uidl on POP3 server $name.
	   The server told to have this	message, but when asked	for its
	   headers, no single line was returned.  Did the message get
	   destroyed?

       Error: Cannot read body for $uidl on POP3 server	$name.
	   The message's headers are retrieved from the	server,	but the	body
	   seems to be lost.  Did the message get destroyed between reading
	   the header and reading the body?

       Warning:	Changes	not written to read-only folder	$self.
	   You have opened the folder read-only	--which	is the default set by
	   new(access)--, made modifications, and now want to close it.	 Set
	   close(force)	if you want to overrule	the access mode, or close the
	   folder with close(write) set	to "NEVER".

       Error: Copying failed for one message.
	   For some reason, for	instance disc full, removed by external
	   process, or read-protection,	it is impossible to copy one of	the
	   messages.  Copying will proceed for the other messages.

       Error: Destination folder $name is not writable.
	   The folder where the	messages are copied to is not opened with
	   write access	(see new(access)).  This has no	relation with write
	   permission to the folder which is controled by your operating
	   system.

       Warning:	Different messages with	id $msgid
	   The message id is discovered	more than once within the same folder,
	   but the content of the message seems	to be different.  This should
	   not be possible: each message must be unique.

       Error: Folder $name is opened read-only
	   You can not write to	this folder unless you have opened the folder
	   to write or append with new(access),	or the "force" option is set
	   true.

       Error: Invalid timespan '$timespan' specified.
	   The string does not follow the strict rules of the time span	syntax
	   which is permitted as parameter.

       Warning:	Message	$uidl on POP3 server $name disappeared.
	   The server indicated	the existence of this message before, however
	   it has no information about the message anymore.

       Warning:	Message-id '$msgid' does not contain a domain.
	   According to	the RFCs, message-ids need to contain a	unique random
	   part, then an "@", and then a domain	name.  This is made to avoid
	   the creation	of two messages	with the same id.  The warning emerges
	   when	the "@"	is missing from	the string.

       Warning:	POP3 folders cannot be deleted.
	   Each	user has only one POP3 folder on a server.  This folder	is
	   created and deleted by the server's administrator only.

       Error: Package $package does not	implement $method.
	   Fatal error:	the specific package (or one of	its superclasses) does
	   not implement this method where it should. This message means that
	   some	other related classes do implement this	method however the
	   class at hand does not.  Probably you should	investigate this and
	   probably inform the author of the package.

       Error: Unable to	create subfolder $name of $folder.
	   The copy includes the subfolders, but for some reason it was	not
	   possible to copy one	of these.  Copying will	proceed	for all	other
	   sub-folders.

       Error: Update of	$nr messages ignored for POP3 folder $name.
	   The standard	POP3 implementation does not support writing from
	   client back to the server.  Therefore, modifications	may be lost.

       Error: Writing folder $name failed
	   For some reason (you	probably got more error	messages about this
	   problem) it is impossible to	write the folder, although you should
	   because there were changes made.

       Error: You cannot write a message to a pop server (yet)
	   Some	extensions to the POP3 protocol	do permit writing messages to
	   the server, but the standard	protocol only implements retreival.
	   Feel	invited	to extend our implementation with writing.

SEE ALSO
       This module is part of Mail-Box distribution version 2.109, built on
       August 19, 2013.	Website: http://perl.overmeer.net/mailbox/

LICENSE
       Copyrights 2001-2013 by [Mark Overmeer].	For other contributors see
       ChangeLog.

       This program is free software; you can redistribute it and/or modify it
       under the same terms as Perl itself.  See
       http://www.perl.com/perl/misc/Artistic.html

perl v5.24.1			  2013-08-19		    Mail::Box::POP3(3)

NAME | INHERITANCE | SYNOPSIS | DESCRIPTION | OVERLOADED | METHODS | DETAILS | DIAGNOSTICS | SEE ALSO | LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Mail::Box::POP3&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help