Mail::Box::POP3(3pm)

1Mail::Box::POP3(3)    User Contributed Perl Documentation   Mail::Box::POP3(3)
2
3
4

NAME

6       Mail::Box::POP3 - handle POP3 folders as client
7

INHERITANCE

9        Mail::Box::POP3
10          is a Mail::Box::Net
11          is a Mail::Box
12          is a Mail::Reporter
13

SYNOPSIS

15        use Mail::Box::POP3;
16        my $folder = new Mail::Box::POP3 folder => $ENV{MAIL}, ...;
17

DESCRIPTION

19       Maintain a folder which has its messages stored on a remote server.
20       The communication between the client application and the server is
21       implemented using the POP3 protocol.  This class uses Mail::Trans‐
22       port::POP3 to hide the transport of information, and focusses solely on
23       the correct handling of messages within a POP3 folder.
24

OVERLOADED

26       overload: ""
27
28           See "OVERLOADED" in Mail::Box
29
30       overload: @{}
31
32           See "OVERLOADED" in Mail::Box
33
34       overload: cmp
35
36           See "OVERLOADED" in Mail::Box
37

METHODS

39       Constructors
40
41       Mail::Box::POP3->new(OPTIONS)
42
43           For authentications, you have three choices: specify a foldername
44           which resembles an URL, or specify a pop-client object, or separate
45           options for user, password, pop-server and server-port.
46
47            Option           --Defined in     --Default
48            access             Mail::Box        'r'
49            authenticate                        'AUTO'
50            body_delayed_type  Mail::Box        Mail::Message::Body::Delayed
51            body_type          Mail::Box        Mail::Message::Body::Lines
52            coerce_options     Mail::Box        []
53            create             Mail::Box        <not applicable>
54            extract            Mail::Box        10240
55            field_type         Mail::Box        undef
56            fix_headers        Mail::Box        <false>
57            folder             Mail::Box        <not applicable>
58            folderdir          Mail::Box        <not used>
59            head_delayed_type  Mail::Box        Mail::Message::Head::Delayed
60            head_type          Mail::Box        Mail::Message::Head::Complete
61            keep_dups          Mail::Box        <false>
62            lock_file          Mail::Box        undef
63            lock_timeout       Mail::Box        1 hour
64            lock_type          Mail::Box        'NONE'
65            lock_wait          Mail::Box        10 seconds
66            locker             Mail::Box        undef
67            log                Mail::Reporter   'WARNINGS'
68            manager            Mail::Box        undef
69            message_type       Mail::Box        Mail::Box::POP3::Message
70            multipart_type     Mail::Box        Mail::Message::Body::Multipart
71            password           Mail::Box::Net   undef
72            pop_client                          undef
73            remove_when_empty  Mail::Box        <false>
74            save_on_exit       Mail::Box        <true>
75            server_name        Mail::Box::Net   undef
76            server_port        Mail::Box::Net   110
77            trace              Mail::Reporter   'WARNINGS'
78            trusted            Mail::Box        <false>
79            username           Mail::Box::Net   undef
80
81           . access MODE
82
83           . authenticate 'LOGIN'⎪'APOP'⎪'AUTO'
84
85               POP3 can use two methods of authentication: the old LOGIN pro‐
86               tocol, which transmits a username and password in plain text,
87               and the newer APOP protocol which uses MD5 encryption.  APOP is
88               therefore much better, however not always supported by the
89               server.  With AUTO, first APOP is tried and if that fails
90               LOGIN.
91
92           . body_delayed_type CLASS
93
94           . body_type CLASS⎪CODE
95
96           . coerce_options ARRAY
97
98           . create BOOLEAN
99
100           . extract INTEGER ⎪ CODE ⎪ METHOD ⎪ 'LAZY'⎪'ALWAYS'
101
102           . field_type CLASS
103
104           . fix_headers BOOLEAN
105
106           . folder FOLDERNAME
107
108           . folderdir DIRECTORY
109
110           . head_delayed_type CLASS
111
112           . head_type CLASS
113
114           . keep_dups BOOLEAN
115
116           . lock_file FILENAME
117
118           . lock_timeout SECONDS
119
120           . lock_type CLASS⎪STRING⎪ARRAY
121
122           . lock_wait SECONDS
123
124           . locker OBJECT
125
126           . log LEVEL
127
128           . manager MANAGER
129
130           . message_type CLASS
131
132           . multipart_type CLASS
133
134           . password STRING
135
136           . pop_client OBJECT
137
138               You may want to specify your own pop-client object.  The object
139               which is passed must extend Mail::Transport::POP3.
140
141           . remove_when_empty BOOLEAN
142
143           . save_on_exit BOOLEAN
144
145           . server_name HOSTNAME
146
147           . server_port INTEGER
148
149           . trace LEVEL
150
151           . trusted BOOLEAN
152
153           . username STRING
154
155           Example:
156
157            my $url = 'pop3://user:password@pop.xs4all.nl'
158            my $pop = Mail::Box::POP3->new($url);
159
160            my $pop = $mgr->open(type => 'pop3',
161               username => 'myname', password => 'mypassword',
162               server_name => 'pop.xs4all.nl');
163
164       The folder
165
166       $obj->addMessage(MESSAGE)
167
168           It is impossible to write messages to the average POP3 server.
169           There are extensions to the protocol which do permit it, however
170           these are not implemented (yet, patches welcome).
171
172           "undef" is returned, and an error displayed.  However, no complaint
173           is given when the MESSAGE is "undef" itself.
174
175            Option--Defined in--Default
176            share   Mail::Box   <not used>
177
178           . share BOOLEAN
179
180       $obj->addMessages(MESSAGES)
181
182           As useless as addMessage().  The only acceptable call to this
183           method is without any message.
184
185       Mail::Box::POP3->appendMessages(OPTIONS)
186
187           See "The folder" in Mail::Box
188
189       $obj->close(OPTIONS)
190
191           See "The folder" in Mail::Box
192
193       $obj->copyTo(FOLDER, OPTIONS)
194
195           See "The folder" in Mail::Box
196
197       $obj->delete(OPTIONS)
198
199           It is not possible to delete a POP3 folder remotely: the best we
200           can do is remove all the messages in it... which is the action
201           implemented here.  A notice is logged about this.
202
203            Option   --Defined in--Default
204            recursive  Mail::Box   <not used>
205
206           . recursive BOOLEAN
207
208       $obj->folderdir([DIRECTORY])
209
210           See "METHODS" in Mail::Box::Net
211
212       $obj->name
213
214           See "The folder" in Mail::Box
215
216       $obj->organization
217
218           See "The folder" in Mail::Box
219
220       $obj->size
221
222           See "The folder" in Mail::Box
223
224       $obj->type
225
226           See "The folder" in Mail::Box
227
228       $obj->update
229
230           NOT IMPLEMENTED YET
231
232       $obj->url
233
234           See "The folder" in Mail::Box
235
236       Folder flags
237
238       $obj->access
239
240           See "Folder flags" in Mail::Box
241
242       $obj->isModified
243
244           See "Folder flags" in Mail::Box
245
246       $obj->modified([BOOLEAN])
247
248           See "Folder flags" in Mail::Box
249
250       $obj->writable
251
252           See "Folder flags" in Mail::Box
253
254       The messages
255
256       $obj->current([NUMBER⎪MESSAGE⎪MESSAGE-ID])
257
258           See "The messages" in Mail::Box
259
260       $obj->find(MESSAGE-ID)
261
262           See "The messages" in Mail::Box
263
264       $obj->findFirstLabeled(LABEL, [BOOLEAN, [ARRAY-OF-MSGS]])
265
266           See "The messages" in Mail::Box
267
268       $obj->message(INDEX [,MESSAGE])
269
270           See "The messages" in Mail::Box
271
272       $obj->messageId(MESSAGE-ID [,MESSAGE])
273
274           See "The messages" in Mail::Box
275
276       $obj->messageIds
277
278           See "The messages" in Mail::Box
279
280       $obj->messages(['ALL',RANGE,'ACTIVE','DELETED',LABEL,!LABEL,FILTER])
281
282           See "The messages" in Mail::Box
283
284       $obj->nrMessages(OPTIONS)
285
286           See "The messages" in Mail::Box
287
288       $obj->scanForMessages(MESSAGE, MESSAGE-IDS, TIMESPAN, WINDOW)
289
290           See "The messages" in Mail::Box
291
292       Sub-folders
293
294       $obj->listSubFolders(OPTIONS)
295
296       Mail::Box::POP3->listSubFolders(OPTIONS)
297
298           The standard POP3 protocol does not support sub-folders, so an
299           empty list will be returned in any case.
300
301            Option    --Defined in     --Default
302            check       Mail::Box        <false>
303            folder      Mail::Box        <from calling object>
304            folderdir   Mail::Box        <from folder>
305            skip_empty  Mail::Box        <false>
306
307           . check BOOLEAN
308
309           . folder FOLDERNAME
310
311           . folderdir DIRECTORY
312
313           . skip_empty BOOL
314
315       $obj->nameOfSubFolder(SUBNAME, [PARENTNAME])
316
317       Mail::Box::POP3->nameOfSubFolder(SUBNAME, [PARENTNAME])
318
319           See "Sub-folders" in Mail::Box
320
321       $obj->openRelatedFolder(OPTIONS)
322
323           See "Sub-folders" in Mail::Box
324
325       $obj->openSubFolder(OPTIONS)
326
327           It is not possible to open a sub-folder for a POP3 folder, because
328           that is not supported by the official POP3 protocol. In any case,
329           "undef" is returned to indicate a failure.
330
331       $obj->topFolderWithMessages
332
333       Mail::Box::POP3->topFolderWithMessages
334
335           See "Sub-folders" in Mail::Box
336
337       Internals
338
339       $obj->coerce(MESSAGE, OPTIONS)
340
341           See "Internals" in Mail::Box
342
343       $obj->create(FOLDER, OPTIONS)
344
345       Mail::Box::POP3->create(FOLDER, OPTIONS)
346
347           It is not possible to create a new folder on a POP3 server.  This
348           method will always return "false".
349
350            Option   --Defined in--Default
351            folderdir  Mail::Box   <not used>
352
353           . folderdir DIRECTORY
354
355       $obj->determineBodyType(MESSAGE, HEAD)
356
357           See "Internals" in Mail::Box
358
359       Mail::Box::POP3->foundIn([FOLDERNAME], OPTIONS)
360
361           See "Internals" in Mail::Box
362
363       $obj->getHead(MESSAGE)
364
365           Read the header for the specified message from the remote server.
366
367       $obj->getHeadAndBody(MESSAGE)
368
369           Read all data for the specified message from the remote server.
370
371       $obj->lineSeparator([STRING⎪'CR'⎪'LF'⎪'CRLF'])
372
373           See "Internals" in Mail::Box
374
375       $obj->locker
376
377           See "Internals" in Mail::Box
378
379       $obj->popClient
380
381           Returns the pop client object.  This does not establish the connec‐
382           tion.
383
384       $obj->read(OPTIONS)
385
386           See "Internals" in Mail::Box
387
388       $obj->readMessages(OPTIONS)
389
390           See "Internals" in Mail::Box
391
392       $obj->storeMessage(MESSAGE)
393
394           See "Internals" in Mail::Box
395
396       $obj->toBeThreaded(MESSAGES)
397
398           See "Internals" in Mail::Box
399
400       $obj->toBeUnthreaded(MESSAGES)
401
402           See "Internals" in Mail::Box
403
404       $obj->updateMessages(OPTIONS)
405
406           See "Internals" in Mail::Box
407
408       $obj->write(OPTIONS)
409
410           See "Internals" in Mail::Box
411
412       $obj->writeMessages(OPTIONS)
413
414        Option  --Defined in--Default
415        messages  Mail::Box   <required>
416
417           . messages ARRAY
418
419       Other methods
420
421       $obj->timespan2seconds(TIME)
422
423       Mail::Box::POP3->timespan2seconds(TIME)
424
425           See "Other methods" in Mail::Box
426
427       Error handling
428
429       $obj->AUTOLOAD
430
431           See "Error handling" in Mail::Reporter
432
433       $obj->addReport(OBJECT)
434
435           See "Error handling" in Mail::Reporter
436
437       $obj->defaultTrace([LEVEL]⎪[LOGLEVEL, TRACELEVEL]⎪[LEVEL, CALLBACK])
438
439       Mail::Box::POP3->defaultTrace([LEVEL]⎪[LOGLEVEL, TRACELEVEL]⎪[LEVEL,
440       CALLBACK])
441
442           See "Error handling" in Mail::Reporter
443
444       $obj->errors
445
446           See "Error handling" in Mail::Reporter
447
448       $obj->log([LEVEL [,STRINGS]])
449
450       Mail::Box::POP3->log([LEVEL [,STRINGS]])
451
452           See "Error handling" in Mail::Reporter
453
454       $obj->logPriority(LEVEL)
455
456       Mail::Box::POP3->logPriority(LEVEL)
457
458           See "Error handling" in Mail::Reporter
459
460       $obj->logSettings
461
462           See "Error handling" in Mail::Reporter
463
464       $obj->notImplemented
465
466           See "Error handling" in Mail::Reporter
467
468       $obj->report([LEVEL])
469
470           See "Error handling" in Mail::Reporter
471
472       $obj->reportAll([LEVEL])
473
474           See "Error handling" in Mail::Reporter
475
476       $obj->trace([LEVEL])
477
478           See "Error handling" in Mail::Reporter
479
480       $obj->warnings
481
482           See "Error handling" in Mail::Reporter
483
484       Cleanup
485
486       $obj->DESTROY
487
488           See "Cleanup" in Mail::Box
489
490       $obj->inGlobalDestruction
491
492           See "Cleanup" in Mail::Reporter
493

DETAILS

495       How POP3 folders work
496
497       Rfc1939 defines how POP3 works.  POP3 is a really simple protocol to
498       receive messages from a server to a user's client.  POP3 is also really
499       limited: it can only be used to fetch messages, but has not many ways
500       to limit the amount of network traffic, like the IMAP4 protocol has.
501
502       One POP3 account represents only one folder: there is no way of sub-
503       folders in POP3.  POP3 doesn't support writing (except for some message
504       status flags).
505
506       This implementation
507
508       The protocol specifics are implemented in Mail::Transport::POP3, writ‐
509       ten by Liz Mattijsen.  That module does not use any of the other POP3
510       modules available on CPAN for the reason that MailBox tries to be
511       smarter: it is capable of re-establishing broken POP3 connection when
512       the server supports UIDs.
513
514       The implementation has shown to work with many different POP servers.
515       In the test directory of the distribution, you will find a small server
516       implementation, which is used to test the client.
517

DIAGNOSTICS

519       Error: Cannot create POP3 client for $name.
520
521       The connection to the POP3 server cannot be established.  You may see
522       more, related, error messages about the failure.
523
524       Error: Cannot find head back for $uidl on POP3 server $name.
525
526       The server told to have this message, but when asked for its headers,
527       no single line was returned.  Did the message get destroyed?
528
529       Error: Cannot read body for $uidl on POP3 server $name.
530
531       The message's headers are retreived from the server, but the body seems
532       to be lost.  Did the message get destroyed between reading the header
533       and reading the body?
534
535       Warning: Changes not written to read-only folder $self.
536
537       You have opened the folder read-only --which is the default set by
538       new(access)--, made modifications, and now want to close it.  Set
539       close(force) if you want to overrule the access mode, or close the
540       folder with close(write) set to "NEVER".
541
542       Error: Copying failed for one message.
543
544       For some reason, for instance disc full, removed by external process,
545       or read-protection, it is impossible to copy one of the messages.
546       Copying will proceed for the other messages.
547
548       Error: Destination folder $name is not writable.
549
550       The folder where the messages are copied to is not opened with write
551       access (see new(access)).  This has no relation with write permission
552       to the folder which is controled by your operating system.
553
554       Warning: Different messages with id $msgid
555
556       The message id is discovered more than once within the same folder, but
557       the content of the message seems to be different.  This should not be
558       possible: each message must be unique.
559
560       Error: Folder $name is opened read-only
561
562       You can not write to this folder unless you have opened the folder to
563       write or append with new(access), or the "force" option is set true.
564
565       Error: Invalid timespan '$timespan' specified.
566
567       The string does not follow the strict rules of the time span syntax
568       which is permitted as parameter.
569
570       Warning: Message $uidl on POP3 server $name disappeared.
571
572       The server indicated the existence of this message before, however it
573       has no information about the message anymore.
574
575       Warning: Message-id '$msgid' does not contain a domain.
576
577       According to the RFCs, message-ids need to contain a unique random
578       part, then an "@", and then a domain name.  This is made to avoid the
579       creation of two messages with the same id.  The warning emerges when
580       the "@" is missing from the string.
581
582       Warning: POP3 folders cannot be deleted.
583
584       Each user has only one POP3 folder on a server.  This folder is created
585       and deleted by the server's administrator only.
586
587       Error: Package $package does not implement $method.
588
589       Fatal error: the specific package (or one of its superclasses) does not
590       implement this method where it should. This message means that some
591       other related classes do implement this method however the class at
592       hand does not.  Probably you should investigate this and probably
593       inform the author of the package.
594
595       Error: Unable to create subfolder $name of $folder.
596
597       The copy includes the subfolders, but for some reason it was not possi‐
598       ble to copy one of these.  Copying will proceed for all other sub-fold‐
599       ers.
600
601       Error: Update of $nr messages ignored for POP3 folder $name.
602
603       The standard POP3 implementation does not support writing from client
604       back to the server.  Therefore, modifications may be lost.
605
606       Error: Writing folder $name failed
607
608       For some reason (you probably got more error messages about this prob‐
609       lem) it is impossible to write the folder, although you should because
610       there were changes made.
611
612       Error: You cannot write a message to a pop server (yet)
613
614       Some extensions to the POP3 protocol do permit writing messages to the
615       server, but the standard protocol only implements retreival.  Feel
616       invited to extend our implementation with writing.
617

LICENSE

623       Copyrights 2001-2007 by Mark Overmeer.For other contributors see
624       ChangeLog.
625
626       This program is free software; you can redistribute it and/or modify it
627       under the same terms as Perl itself.  See
628       http://www.perl.com/perl/misc/Artistic.html
629
630
631
632perl v5.8.8                       2007-03-25                Mail::Box::POP3(3)