1Mail::Box::POP3(3) User Contributed Perl Documentation Mail::Box::POP3(3)
2
3
4
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
14 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
33 overload: @{}
34 See "OVERLOADED" in Mail::Box
35
36 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
46 -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
80 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
88 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
114 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
122 example:
123
124 my $url = 'pop3://user:password@pop.xs4all.nl'
125 my $pop = Mail::Box::POP3->new($url);
126
127 my $pop = $mgr->open(type => 'pop3',
128 username => 'myname', password => 'mypassword',
129 server_name => 'pop.xs4all.nl');
130
131 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
137 "undef" is returned, and an error displayed. However, no complaint
138 is given when the MESSAGE is "undef" itself.
139
140 -Option--Defined in--Default
141 share Mail::Box <not used>
142
143 share => BOOLEAN
144 $obj->addMessages(MESSAGES)
145 As useless as addMessage(). The only acceptable call to this
146 method is without any message.
147
148 Mail::Box::POP3->appendMessages(OPTIONS)
149 See "The folder" in Mail::Box
150
151 $obj->close(OPTIONS)
152 See "The folder" in Mail::Box
153
154 $obj->copyTo(FOLDER, OPTIONS)
155 See "The folder" in Mail::Box
156
157 $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
162 -Option --Defined in--Default
163 recursive Mail::Box <not used>
164
165 recursive => BOOLEAN
166 $obj->folderdir([DIRECTORY])
167 See "METHODS" in Mail::Box::Net
168
169 $obj->name
170 See "The folder" in Mail::Box
171
172 $obj->organization
173 See "The folder" in Mail::Box
174
175 $obj->size
176 See "The folder" in Mail::Box
177
178 $obj->type
179 See "The folder" in Mail::Box
180
181 $obj->update
182 NOT IMPLEMENTED YET
183
184 $obj->url
185 See "The folder" in Mail::Box
186
187 Folder flags
188 $obj->access
189 See "Folder flags" in Mail::Box
190
191 $obj->isModified
192 See "Folder flags" in Mail::Box
193
194 $obj->modified([BOOLEAN])
195 See "Folder flags" in Mail::Box
196
197 $obj->writable
198 See "Folder flags" in Mail::Box
199
200 The messages
201 $obj->current([NUMBER|MESSAGE|MESSAGE-ID])
202 See "The messages" in Mail::Box
203
204 $obj->find(MESSAGE-ID)
205 See "The messages" in Mail::Box
206
207 $obj->findFirstLabeled(LABEL, [BOOLEAN, [ARRAY-OF-MSGS]])
208 See "The messages" in Mail::Box
209
210 $obj->message(INDEX [,MESSAGE])
211 See "The messages" in Mail::Box
212
213 $obj->messageId(MESSAGE-ID [,MESSAGE])
214 See "The messages" in Mail::Box
215
216 $obj->messageIds
217 See "The messages" in Mail::Box
218
219 $obj->messages(['ALL',RANGE,'ACTIVE','DELETED',LABEL,!LABEL,FILTER])
220 See "The messages" in Mail::Box
221
222 $obj->nrMessages(OPTIONS)
223 See "The messages" in Mail::Box
224
225 $obj->scanForMessages(MESSAGE, MESSAGE-IDS, TIMESPAN, WINDOW)
226 See "The messages" in Mail::Box
227
228 Sub-folders
229 $obj->listSubFolders(OPTIONS)
230 Mail::Box::POP3->listSubFolders(OPTIONS)
231
232 The standard POP3 protocol does not support sub-folders, so an
233 empty list will be returned in any case.
234
235 -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
241 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
248 See "Sub-folders" in Mail::Box
249
250 $obj->openRelatedFolder(OPTIONS)
251 See "Sub-folders" in Mail::Box
252
253 $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
258 $obj->topFolderWithMessages
259 Mail::Box::POP3->topFolderWithMessages
260
261 See "Sub-folders" in Mail::Box
262
263 Internals
264 $obj->coerce(MESSAGE, OPTIONS)
265 See "Internals" in Mail::Box
266
267 $obj->create(FOLDER, OPTIONS)
268 Mail::Box::POP3->create(FOLDER, OPTIONS)
269
270 It is not possible to create a new folder on a POP3 server. This
271 method will always return "false".
272
273 -Option --Defined in--Default
274 folderdir Mail::Box <not used>
275
276 folderdir => DIRECTORY
277 $obj->determineBodyType(MESSAGE, HEAD)
278 See "Internals" in Mail::Box
279
280 Mail::Box::POP3->foundIn([FOLDERNAME], OPTIONS)
281 See "Internals" in Mail::Box
282
283 $obj->getHead(MESSAGE)
284 Read the header for the specified message from the remote server.
285
286 $obj->getHeadAndBody(MESSAGE)
287 Read all data for the specified message from the remote server.
288
289 $obj->lineSeparator([STRING|'CR'|'LF'|'CRLF'])
290 See "Internals" in Mail::Box
291
292 $obj->locker
293 See "Internals" in Mail::Box
294
295 $obj->popClient(OPTIONS)
296 Returns the pop client object. This does not establish the
297 connection.
298
299 -Option --Default
300 use_ssl <false>
301
302 use_ssl => BOOLEAN
303 $obj->read(OPTIONS)
304 See "Internals" in Mail::Box
305
306 $obj->readMessages(OPTIONS)
307 See "Internals" in Mail::Box
308
309 $obj->storeMessage(MESSAGE)
310 See "Internals" in Mail::Box
311
312 $obj->toBeThreaded(MESSAGES)
313 See "Internals" in Mail::Box
314
315 $obj->toBeUnthreaded(MESSAGES)
316 See "Internals" in Mail::Box
317
318 $obj->updateMessages(OPTIONS)
319 See "Internals" in Mail::Box
320
321 $obj->write(OPTIONS)
322 See "Internals" in Mail::Box
323
324 $obj->writeMessages(OPTIONS)
325 -Option --Defined in--Default
326 messages Mail::Box <required>
327
328 messages => ARRAY
329
330 Other methods
331 $obj->timespan2seconds(TIME)
332 Mail::Box::POP3->timespan2seconds(TIME)
333
334 See "Other methods" in Mail::Box
335
336 Error handling
337 $obj->AUTOLOAD
338 See "Error handling" in Mail::Reporter
339
340 $obj->addReport(OBJECT)
341 See "Error handling" in Mail::Reporter
342
343 $obj->defaultTrace([LEVEL]|[LOGLEVEL, TRACELEVEL]|[LEVEL, CALLBACK])
344 Mail::Box::POP3->defaultTrace([LEVEL]|[LOGLEVEL,
345 TRACELEVEL]|[LEVEL, CALLBACK])
346
347 See "Error handling" in Mail::Reporter
348
349 $obj->errors
350 See "Error handling" in Mail::Reporter
351
352 $obj->log([LEVEL [,STRINGS]])
353 Mail::Box::POP3->log([LEVEL [,STRINGS]])
354
355 See "Error handling" in Mail::Reporter
356
357 $obj->logPriority(LEVEL)
358 Mail::Box::POP3->logPriority(LEVEL)
359
360 See "Error handling" in Mail::Reporter
361
362 $obj->logSettings
363 See "Error handling" in Mail::Reporter
364
365 $obj->notImplemented
366 See "Error handling" in Mail::Reporter
367
368 $obj->report([LEVEL])
369 See "Error handling" in Mail::Reporter
370
371 $obj->reportAll([LEVEL])
372 See "Error handling" in Mail::Reporter
373
374 $obj->trace([LEVEL])
375 See "Error handling" in Mail::Reporter
376
377 $obj->warnings
378 See "Error handling" in Mail::Reporter
379
380 Cleanup
381 $obj->DESTROY
382 See "Cleanup" in Mail::Box
383
384 $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
397 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
401 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
408 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
417 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
422 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
427 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
433 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
438 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
444 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
449 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
454 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
458 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
462 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
468 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
472 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
479 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
484 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
488 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
493 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
506 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
509
510
511
512perl v5.12.3 2011-01-26 Mail::Box::POP3(3)