1Mail::Box::POP3(3) User Contributed Perl Documentation Mail::Box::POP3(3)
2
6 Mail::Box::POP3 - handle POP3 folders as client
7
9 Mail::Box::POP3
10 is a Mail::Box::Net
11 is a Mail::Box
12 is a Mail::Reporter
13 Mail::Box::POP3 is extended by
15 Mail::Box::POP3s
16
18 use Mail::Box::POP3;
19 my $folder = new Mail::Box::POP3 folder => $ENV{MAIL}, ...;
20
22 Maintain a folder which has its messages stored on a remote server.
23 The communication between the client application and the server is
24 implemented using the POP3 protocol. This class uses
25 Mail::Transport::POP3 to hide the transport of information, and
26 focusses solely on the correct handling of messages within a POP3
27 folder.
28
30 overload: ""
31 See "OVERLOADED" in Mail::Box
32 overload: @{}
34 See "OVERLOADED" in Mail::Box
35 overload: cmp
37 See "OVERLOADED" in Mail::Box
38
40 Constructors
41 Mail::Box::POP3->new(OPTIONS)
42 For authentications, you have three choices: specify a foldername
43 which resembles an URL, or specify a pop-client object, or separate
44 options for user, password, pop-server and server-port.
45 -Option --Defined in --Default
47 access Mail::Box 'r'
48 authenticate 'AUTO'
49 body_delayed_type Mail::Box Mail::Message::Body::Delayed
50 body_type Mail::Box Mail::Message::Body::Lines
51 coerce_options Mail::Box []
52 create Mail::Box <not applicable>
53 extract Mail::Box 10240
54 field_type Mail::Box undef
55 fix_headers Mail::Box <false>
56 folder Mail::Box <not applicable>
57 folderdir Mail::Box <not used>
58 head_delayed_type Mail::Box Mail::Message::Head::Delayed
59 head_type Mail::Box Mail::Message::Head::Complete
60 keep_dups Mail::Box <false>
61 lock_file Mail::Box undef
62 lock_timeout Mail::Box 1 hour
63 lock_type Mail::Box 'NONE'
64 lock_wait Mail::Box 10 seconds
65 locker Mail::Box undef
66 log Mail::Reporter 'WARNINGS'
67 manager Mail::Box undef
68 message_type Mail::Box Mail::Box::POP3::Message
69 multipart_type Mail::Box Mail::Message::Body::Multipart
70 password Mail::Box::Net undef
71 pop_client undef
72 remove_when_empty Mail::Box <false>
73 save_on_exit Mail::Box <true>
74 server_name Mail::Box::Net undef
75 server_port Mail::Box::Net 110
76 trace Mail::Reporter 'WARNINGS'
77 trusted Mail::Box <false>
78 username Mail::Box::Net undef
79 access => MODE
81 authenticate => 'LOGIN'|'APOP'|'AUTO'
82 POP3 can use two methods of authentication: the old LOGIN
83 protocol, which transmits a username and password in plain text,
84 and the newer APOP protocol which uses MD5 encryption. APOP is
85 therefore much better, however not always supported by the
86 server. With AUTO, first APOP is tried and if that fails LOGIN.
87 body_delayed_type => CLASS
89 body_type => CLASS|CODE
90 coerce_options => ARRAY
91 create => BOOLEAN
92 extract => INTEGER | CODE | METHOD | 'LAZY'|'ALWAYS'
93 field_type => CLASS
94 fix_headers => BOOLEAN
95 folder => FOLDERNAME
96 folderdir => DIRECTORY
97 head_delayed_type => CLASS
98 head_type => CLASS
99 keep_dups => BOOLEAN
100 lock_file => FILENAME
101 lock_timeout => SECONDS
102 lock_type => CLASS|STRING|ARRAY
103 lock_wait => SECONDS
104 locker => OBJECT
105 log => LEVEL
106 manager => MANAGER
107 message_type => CLASS
108 multipart_type => CLASS
109 password => STRING
110 pop_client => OBJECT
111 You may want to specify your own pop-client object. The object
112 which is passed must extend Mail::Transport::POP3.
113 remove_when_empty => BOOLEAN
115 save_on_exit => BOOLEAN
116 server_name => HOSTNAME
117 server_port => INTEGER
118 trace => LEVEL
119 trusted => BOOLEAN
120 username => STRING
121 example:
123 my $url = 'pop3://user:password@pop.xs4all.nl'
125 my $pop = Mail::Box::POP3->new($url);
126 my $pop = $mgr->open(type => 'pop3',
128 username => 'myname', password => 'mypassword',
129 server_name => 'pop.xs4all.nl');
130 The folder
132 $obj->addMessage(MESSAGE)
133 It is impossible to write messages to the average POP3 server.
134 There are extensions to the protocol which do permit it, however
135 these are not implemented (yet, patches welcome).
136 "undef" is returned, and an error displayed. However, no complaint
138 is given when the MESSAGE is "undef" itself.
139 -Option--Defined in--Default
141 share Mail::Box <not used>
142 share => BOOLEAN
144 $obj->addMessages(MESSAGES)
145 As useless as addMessage(). The only acceptable call to this
146 method is without any message.
147 Mail::Box::POP3->appendMessages(OPTIONS)
149 See "The folder" in Mail::Box
150 $obj->close(OPTIONS)
152 See "The folder" in Mail::Box
153 $obj->copyTo(FOLDER, OPTIONS)
155 See "The folder" in Mail::Box
156 $obj->delete(OPTIONS)
158 It is not possible to delete a POP3 folder remotely: the best we
159 can do is remove all the messages in it... which is the action
160 implemented here. A notice is logged about this.
161 -Option --Defined in--Default
163 recursive Mail::Box <not used>
164 recursive => BOOLEAN
166 $obj->folderdir([DIRECTORY])
167 See "METHODS" in Mail::Box::Net
168 $obj->name
170 See "The folder" in Mail::Box
171 $obj->organization
173 See "The folder" in Mail::Box
174 $obj->size
176 See "The folder" in Mail::Box
177 $obj->type
179 See "The folder" in Mail::Box
180 $obj->update
182 NOT IMPLEMENTED YET
183 $obj->url
185 See "The folder" in Mail::Box
186 Folder flags
188 $obj->access
189 See "Folder flags" in Mail::Box
190 $obj->isModified
192 See "Folder flags" in Mail::Box
193 $obj->modified([BOOLEAN])
195 See "Folder flags" in Mail::Box
196 $obj->writable
198 See "Folder flags" in Mail::Box
199 The messages
201 $obj->current([NUMBER|MESSAGE|MESSAGE-ID])
202 See "The messages" in Mail::Box
203 $obj->find(MESSAGE-ID)
205 See "The messages" in Mail::Box
206 $obj->findFirstLabeled(LABEL, [BOOLEAN, [ARRAY-OF-MSGS]])
208 See "The messages" in Mail::Box
209 $obj->message(INDEX [,MESSAGE])
211 See "The messages" in Mail::Box
212 $obj->messageId(MESSAGE-ID [,MESSAGE])
214 See "The messages" in Mail::Box
215 $obj->messageIds
217 See "The messages" in Mail::Box
218 $obj->messages(['ALL',RANGE,'ACTIVE','DELETED',LABEL,!LABEL,FILTER])
220 See "The messages" in Mail::Box
221 $obj->nrMessages(OPTIONS)
223 See "The messages" in Mail::Box
224 $obj->scanForMessages(MESSAGE, MESSAGE-IDS, TIMESPAN, WINDOW)
226 See "The messages" in Mail::Box
227 Sub-folders
229 $obj->listSubFolders(OPTIONS)
230 Mail::Box::POP3->listSubFolders(OPTIONS)
231 The standard POP3 protocol does not support sub-folders, so an
233 empty list will be returned in any case.
234 -Option --Defined in --Default
236 check Mail::Box <false>
237 folder Mail::Box <from calling object>
238 folderdir Mail::Box <from folder>
239 skip_empty Mail::Box <false>
240 check => BOOLEAN
242 folder => FOLDERNAME
243 folderdir => DIRECTORY
244 skip_empty => BOOL
245 $obj->nameOfSubFolder(SUBNAME, [PARENTNAME])
246 Mail::Box::POP3->nameOfSubFolder(SUBNAME, [PARENTNAME])
247 See "Sub-folders" in Mail::Box
249 $obj->openRelatedFolder(OPTIONS)
251 See "Sub-folders" in Mail::Box
252 $obj->openSubFolder(OPTIONS)
254 It is not possible to open a sub-folder for a POP3 folder, because
255 that is not supported by the official POP3 protocol. In any case,
256 "undef" is returned to indicate a failure.
257 $obj->topFolderWithMessages
259 Mail::Box::POP3->topFolderWithMessages
260 See "Sub-folders" in Mail::Box
262 Internals
264 $obj->coerce(MESSAGE, OPTIONS)
265 See "Internals" in Mail::Box
266 $obj->create(FOLDER, OPTIONS)
268 Mail::Box::POP3->create(FOLDER, OPTIONS)
269 It is not possible to create a new folder on a POP3 server. This
271 method will always return "false".
272 -Option --Defined in--Default
274 folderdir Mail::Box <not used>
275 folderdir => DIRECTORY
277 $obj->determineBodyType(MESSAGE, HEAD)
278 See "Internals" in Mail::Box
279 Mail::Box::POP3->foundIn([FOLDERNAME], OPTIONS)
281 See "Internals" in Mail::Box
282 $obj->getHead(MESSAGE)
284 Read the header for the specified message from the remote server.
285 $obj->getHeadAndBody(MESSAGE)
287 Read all data for the specified message from the remote server.
288 $obj->lineSeparator([STRING|'CR'|'LF'|'CRLF'])
290 See "Internals" in Mail::Box
291 $obj->locker
293 See "Internals" in Mail::Box
294 $obj->popClient(OPTIONS)
296 Returns the pop client object. This does not establish the
297 connection.
298 -Option --Default
300 use_ssl <false>
301 use_ssl => BOOLEAN
303 $obj->read(OPTIONS)
304 See "Internals" in Mail::Box
305 $obj->readMessages(OPTIONS)
307 See "Internals" in Mail::Box
308 $obj->storeMessage(MESSAGE)
310 See "Internals" in Mail::Box
311 $obj->toBeThreaded(MESSAGES)
313 See "Internals" in Mail::Box
314 $obj->toBeUnthreaded(MESSAGES)
316 See "Internals" in Mail::Box
317 $obj->updateMessages(OPTIONS)
319 See "Internals" in Mail::Box
320 $obj->write(OPTIONS)
322 See "Internals" in Mail::Box
323 $obj->writeMessages(OPTIONS)
325 -Option --Defined in--Default
326 messages Mail::Box <required>
327 messages => ARRAY
329 Other methods
331 $obj->timespan2seconds(TIME)
332 Mail::Box::POP3->timespan2seconds(TIME)
333 See "Other methods" in Mail::Box
335 Error handling
337 $obj->AUTOLOAD
338 See "Error handling" in Mail::Reporter
339 $obj->addReport(OBJECT)
341 See "Error handling" in Mail::Reporter
342 $obj->defaultTrace([LEVEL]|[LOGLEVEL, TRACELEVEL]|[LEVEL, CALLBACK])
344 Mail::Box::POP3->defaultTrace([LEVEL]|[LOGLEVEL,
345 TRACELEVEL]|[LEVEL, CALLBACK])
346 See "Error handling" in Mail::Reporter
348 $obj->errors
350 See "Error handling" in Mail::Reporter
351 $obj->log([LEVEL [,STRINGS]])
353 Mail::Box::POP3->log([LEVEL [,STRINGS]])
354 See "Error handling" in Mail::Reporter
356 $obj->logPriority(LEVEL)
358 Mail::Box::POP3->logPriority(LEVEL)
359 See "Error handling" in Mail::Reporter
361 $obj->logSettings
363 See "Error handling" in Mail::Reporter
364 $obj->notImplemented
366 See "Error handling" in Mail::Reporter
367 $obj->report([LEVEL])
369 See "Error handling" in Mail::Reporter
370 $obj->reportAll([LEVEL])
372 See "Error handling" in Mail::Reporter
373 $obj->trace([LEVEL])
375 See "Error handling" in Mail::Reporter
376 $obj->warnings
378 See "Error handling" in Mail::Reporter
379 Cleanup
381 $obj->DESTROY
382 See "Cleanup" in Mail::Box
383 $obj->inGlobalDestruction
385 See "Cleanup" in Mail::Reporter
386
388 Different kinds of folders
389 Available folder types
390 Folder class implementation
391 How POP3 folders work
392 Rfc1939 defines how POP3 works. POP3 is a really simple protocol to
393 receive messages from a server to a user's client. POP3 is also really
394 limited: it can only be used to fetch messages, but has not many ways
395 to limit the amount of network traffic, like the IMAP4 protocol has.
396 One POP3 account represents only one folder: there is no way of sub-
398 folders in POP3. POP3 doesn't support writing (except for some message
399 status flags).
400 This implementation
402 The protocol specifics are implemented in Mail::Transport::POP3,
403 written by Liz Mattijsen. That module does not use any of the other
404 POP3 modules available on CPAN for the reason that MailBox tries to be
405 smarter: it is capable of re-establishing broken POP3 connection when
406 the server supports UIDs.
407 The implementation has shown to work with many different POP servers.
409 In the test directory of the distribution, you will find a small server
410 implementation, which is used to test the client.
411
413 Error: Cannot create POP3 client for $name.
414 The connection to the POP3 server cannot be established. You may
415 see more, related, error messages about the failure.
416 Error: Cannot find head back for $uidl on POP3 server $name.
418 The server told to have this message, but when asked for its
419 headers, no single line was returned. Did the message get
420 destroyed?
421 Error: Cannot read body for $uidl on POP3 server $name.
423 The message's headers are retreived from the server, but the body
424 seems to be lost. Did the message get destroyed between reading
425 the header and reading the body?
426 Warning: Changes not written to read-only folder $self.
428 You have opened the folder read-only --which is the default set by
429 new(access)--, made modifications, and now want to close it. Set
430 close(force) if you want to overrule the access mode, or close the
431 folder with close(write) set to "NEVER".
432 Error: Copying failed for one message.
434 For some reason, for instance disc full, removed by external
435 process, or read-protection, it is impossible to copy one of the
436 messages. Copying will proceed for the other messages.
437 Error: Destination folder $name is not writable.
439 The folder where the messages are copied to is not opened with
440 write access (see new(access)). This has no relation with write
441 permission to the folder which is controled by your operating
442 system.
443 Warning: Different messages with id $msgid
445 The message id is discovered more than once within the same folder,
446 but the content of the message seems to be different. This should
447 not be possible: each message must be unique.
448 Error: Folder $name is opened read-only
450 You can not write to this folder unless you have opened the folder
451 to write or append with new(access), or the "force" option is set
452 true.
453 Error: Invalid timespan '$timespan' specified.
455 The string does not follow the strict rules of the time span syntax
456 which is permitted as parameter.
457 Warning: Message $uidl on POP3 server $name disappeared.
459 The server indicated the existence of this message before, however
460 it has no information about the message anymore.
461 Warning: Message-id '$msgid' does not contain a domain.
463 According to the RFCs, message-ids need to contain a unique random
464 part, then an "@", and then a domain name. This is made to avoid
465 the creation of two messages with the same id. The warning emerges
466 when the "@" is missing from the string.
467 Warning: POP3 folders cannot be deleted.
469 Each user has only one POP3 folder on a server. This folder is
470 created and deleted by the server's administrator only.
471 Error: Package $package does not implement $method.
473 Fatal error: the specific package (or one of its superclasses) does
474 not implement this method where it should. This message means that
475 some other related classes do implement this method however the
476 class at hand does not. Probably you should investigate this and
477 probably inform the author of the package.
478 Error: Unable to create subfolder $name of $folder.
480 The copy includes the subfolders, but for some reason it was not
481 possible to copy one of these. Copying will proceed for all other
482 sub-folders.
483 Error: Update of $nr messages ignored for POP3 folder $name.
485 The standard POP3 implementation does not support writing from
486 client back to the server. Therefore, modifications may be lost.
487 Error: Writing folder $name failed
489 For some reason (you probably got more error messages about this
490 problem) it is impossible to write the folder, although you should
491 because there were changes made.
492 Error: You cannot write a message to a pop server (yet)
494 Some extensions to the POP3 protocol do permit writing messages to
495 the server, but the standard protocol only implements retreival.
496 Feel invited to extend our implementation with writing.
497
499 This module is part of Mail-Box distribution version 2.097, built on
500 January 26, 2011. Website: http://perl.overmeer.net/mailbox/
501
503 Copyrights 2001-2011 by Mark Overmeer. For other contributors see
504 ChangeLog.
505 This program is free software; you can redistribute it and/or modify it
507 under the same terms as Perl itself. See
508 http://www.perl.com/perl/misc/Artistic.html
509perl v5.12.3 2011-01-26 Mail::Box::POP3(3)