Mail::Box::IMAP4(3pm)

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

NAME

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

INHERITANCE

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

SYNOPSIS

15        use Mail::Box::IMAP4;
16        my $folder = new Mail::Box::IMAP4 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 IMAP4 protocol.  See also Mail::Server::IMAP4.
22
23       This class uses Mail::Transport::IMAP4 to hide the transport of infor‐
24       mation, and focusses solely on the correct handling of messages within
25       a IMAP4 folder.  More than one IMAP4 folder can be handled by one sin‐
26       gle IMAP4 connection.
27

OVERLOADED

29       overload: ""
30
31           See "OVERLOADED" in Mail::Box
32
33       overload: @{}
34
35           See "OVERLOADED" in Mail::Box
36
37       overload: cmp
38
39           See "OVERLOADED" in Mail::Box
40

METHODS

42       Constructors
43
44       Mail::Box::IMAP4->new(OPTIONS)
45
46           The "new" can have many OPTIONS.  Not only the ones listed here
47           below, but also all the OPTIONS for Mail::Transport::IMAP4::new()
48           can be passed.
49
50           The default depends on the value of new(cache_head).
51
52           Without folder name, no folder is selected.  Only few methods are
53           available now, for instance listSubFolders() to get the top-level
54           folder names.  Usually, the folder named "INBOX" will be present.
55
56            Option           --Defined in     --Default
57            access             Mail::Box        'r'
58            body_delayed_type  Mail::Box        Mail::Message::Body::Delayed
59            body_type          Mail::Box        Mail::Message::Body::Lines
60            cache_body                          NO
61            cache_head                          NO or DELAY
62            cache_labels                        NO or DELAY
63            coerce_options     Mail::Box        []
64            create             Mail::Box        <false>
65            extract            Mail::Box        10240
66            field_type         Mail::Box        undef
67            fix_headers        Mail::Box        <false>
68            folder             Mail::Box        /
69            folderdir          Mail::Box        <not used>
70            head_delayed_type  Mail::Box        Mail::Message::Head::Delayed
71            head_type          Mail::Box        Mail::Box::IMAP4::Head or Mail::Message::Head::Complete
72            join_connection                     true
73            keep_dups          Mail::Box        <false>
74            lock_file          Mail::Box        undef
75            lock_timeout       Mail::Box        1 hour
76            lock_type          Mail::Box        'NONE'
77            lock_wait          Mail::Box        10 seconds
78            locker             Mail::Box        undef
79            log                Mail::Reporter   'WARNINGS'
80            manager            Mail::Box        undef
81            message_type       Mail::Box        Mail::Box::IMAP4::Message
82            multipart_type     Mail::Box        Mail::Message::Body::Multipart
83            password           Mail::Box::Net   undef
84            remove_when_empty  Mail::Box        <false>
85            save_on_exit       Mail::Box        <true>
86            server_name        Mail::Box::Net   undef
87            server_port        Mail::Box::Net   143
88            trace              Mail::Reporter   'WARNINGS'
89            transporter                         Mail::Transport::IMAP4
90            trusted            Mail::Box        <false>
91            username           Mail::Box::Net   undef
92
93           . access MODE
94
95           . body_delayed_type CLASS
96
97           . body_type CLASS⎪CODE
98
99           . cache_body 'NO'⎪'YES'⎪'DELAY'
100
101               Body objects are immutable, but may still cached or not.  In
102               common case, the body of a message is requested via Mail::Mes‐
103               sage::body() or Mail::Message::decoded().  This returns a han‐
104               dle to a body object.  You may decide wether that body object
105               can be reused or not.  "NO" means: retreive the data each time
106               again, "YES" will cache the body data, "DELAY" will send the
107               whole message when the folder is closed.
108
109                       [local cache]  [write]
110                NO         no           no
111                YES        yes          no
112                DELAY      yes          yes
113
114           . cache_head 'NO'⎪'PARTIAL'⎪'DELAY'
115
116               For a read-only folder, "DELAY" is the default, otherwise "NO"
117               is choosen.  The four configuration parameter have subtile con‐
118               sequences.  To start with a table:
119
120                       [local cache]  [write]  [default head_type]
121                NO         no           no     Mail::Box::IMAP4::Head
122                PARTIAL    yes          no     Mail::Box::IMAP4::Head
123                DELAY      yes          yes    Mail::Message::Head::Complete
124
125               The default "head_type" is Mail::Box::IMAP4::Head, the default
126               "cached_head_type" is Mail::Message::Head::Complete.
127
128               Having a local cache means that a lookup for a field is first
129               done in a local data-structure (which extends Mail::Mes‐
130               sage::Head::Partial), and only on the remote server if it was
131               not found.  This is dangerous, because your locally cached data
132               can be out-of-sync with the server.  However, it may give you a
133               nice performance benefit.
134
135               "DELAY" will always collect the whole header for you.  This is
136               required when you want to look for Resent Groups (See
137               Mail::Message::Head::ResentGroup) or other field order depen‐
138               dent header access.  A Mail::Message::Head::Delayed will be
139               created first.
140
141           . cache_labels 'NO'⎪'WRITE'⎪'DELAY'
142
143               When labels from a message are received, these values can be
144               kept. However, this imposes dangers where the server's internal
145               label storage may get out of sync with your data.
146
147               With "NO", no caching will take place (but the performance will
148               be worse). With "WRITE", all label access will be cached, but
149               written to the server as well.  Both "NO" and "WRITE" will
150               update the labels on the served, even when the folder was
151               opened read-only.  "DELAY" will not write the changed informa‐
152               tion to the server, but delay that till the moment that the
153               folder is closed.  It only works when the folder is opened
154               read/write or write is enforced.
155
156               The default is "DELAY" for folders which where opened
157               read-only.  This means that you still can force an update with
158               close(write).  For folders which are opened read-write, the
159               default is the safeset setting, which is "NO".
160
161           . coerce_options ARRAY
162
163           . create BOOLEAN
164
165           . extract INTEGER ⎪ CODE ⎪ METHOD ⎪ 'LAZY'⎪'ALWAYS'
166
167           . field_type CLASS
168
169           . fix_headers BOOLEAN
170
171           . folder FOLDERNAME
172
173           . folderdir DIRECTORY
174
175           . head_delayed_type CLASS
176
177           . head_type CLASS
178
179           . join_connection BOOLEAN
180
181               Within this Mail::Box::IMAP4 class is registered which trans‐
182               porters are already in use, i.e. which connections to the IMAP
183               server are already in established.  When this option is set,
184               multiple folder openings on the same server will try to reuse
185               one connection.
186
187           . keep_dups BOOLEAN
188
189           . lock_file FILENAME
190
191           . lock_timeout SECONDS
192
193           . lock_type CLASS⎪STRING⎪ARRAY
194
195           . lock_wait SECONDS
196
197           . locker OBJECT
198
199           . log LEVEL
200
201           . manager MANAGER
202
203           . message_type CLASS
204
205           . multipart_type CLASS
206
207           . password STRING
208
209           . remove_when_empty BOOLEAN
210
211           . save_on_exit BOOLEAN
212
213           . server_name HOSTNAME
214
215           . server_port INTEGER
216
217           . trace LEVEL
218
219           . transporter OBJECT⎪CLASS
220
221               The name of the CLASS which will interface with the connection.
222               When you implement your own extension to Mail::Trans‐
223               port::IMAP4, you can either specify a fully instantiated trans‐
224               porter OBJECT, or the name of your own CLASS.  When an OBJECT
225               is given, most other options will be ignored.
226
227           . trusted BOOLEAN
228
229           . username STRING
230
231           Example:
232
233            my $imap   = Mail::Box::IMAP4->new(username => 'myname',
234               password => 'mypassword', server_name => 'imap.xs4all.nl');
235
236            my $url    = 'imap4://user:password@imap.xs4all.nl');
237            my $imap   = $mgr->open($url);
238
239            my $client = Mail::IMAPClient->new(...);
240            my $imap   = Mail::Box::IMAP4->new(imap_client => $client);
241
242       The folder
243
244       $obj->addMessage(MESSAGE, OPTIONS)
245
246           See "The folder" in Mail::Box
247
248       $obj->addMessages(MESSAGE [, MESSAGE, ...])
249
250           See "The folder" in Mail::Box
251
252       Mail::Box::IMAP4->appendMessages(OPTIONS)
253
254           See "The folder" in Mail::Box
255
256       $obj->close(OPTIONS)
257
258           Close the folder.  In the case of IMAP, more than one folder can
259           use the same connection, therefore, closing a folder does not
260           always close the connection to the server.  Only when no folder is
261           using the connection anymore, a logout will be invoked by
262           Mail::Transport::IMAP4::DESTROY()
263
264            Option      --Defined in     --Default
265            force         Mail::Box        <false>
266            save_deleted  Mail::Box        false
267            write         Mail::Box        MODIFIED
268
269           . force BOOLEAN
270
271           . save_deleted BOOLEAN
272
273           . write 'ALWAYS'⎪'NEVER'⎪'MODIFIED'
274
275       $obj->copyTo(FOLDER, OPTIONS)
276
277           See "The folder" in Mail::Box
278
279       $obj->delete(OPTIONS)
280
281           See "The folder" in Mail::Box
282
283       $obj->folderdir([DIRECTORY])
284
285           See "METHODS" in Mail::Box::Net
286
287       $obj->name
288
289           See "The folder" in Mail::Box
290
291       $obj->organization
292
293           See "The folder" in Mail::Box
294
295       $obj->size
296
297           See "The folder" in Mail::Box
298
299       $obj->type
300
301           See "The folder" in Mail::Box
302
303       $obj->update(OPTIONS)
304
305           See "The folder" in Mail::Box
306
307       $obj->url
308
309           See "The folder" in Mail::Box
310
311       Folder flags
312
313       $obj->access
314
315           See "Folder flags" in Mail::Box
316
317       $obj->isModified
318
319           See "Folder flags" in Mail::Box
320
321       $obj->modified([BOOLEAN])
322
323           See "Folder flags" in Mail::Box
324
325       $obj->writable
326
327           See "Folder flags" in Mail::Box
328
329       The messages
330
331       $obj->current([NUMBER⎪MESSAGE⎪MESSAGE-ID])
332
333           See "The messages" in Mail::Box
334
335       $obj->find(MESSAGE-ID)
336
337           See "The messages" in Mail::Box
338
339       $obj->findFirstLabeled(LABEL, [BOOLEAN, [ARRAY-OF-MSGS]])
340
341           See "The messages" in Mail::Box
342
343       $obj->message(INDEX [,MESSAGE])
344
345           See "The messages" in Mail::Box
346
347       $obj->messageId(MESSAGE-ID [,MESSAGE])
348
349           See "The messages" in Mail::Box
350
351       $obj->messageIds
352
353           See "The messages" in Mail::Box
354
355       $obj->messages(['ALL',RANGE,'ACTIVE','DELETED',LABEL,!LABEL,FILTER])
356
357           See "The messages" in Mail::Box
358
359       $obj->nrMessages(OPTIONS)
360
361           See "The messages" in Mail::Box
362
363       $obj->scanForMessages(MESSAGE, MESSAGE-IDS, TIMESPAN, WINDOW)
364
365           See "The messages" in Mail::Box
366
367       Sub-folders
368
369       $obj->listSubFolders(OPTIONS)
370
371       Mail::Box::IMAP4->listSubFolders(OPTIONS)
372
373           See "Sub-folders" in Mail::Box
374
375       $obj->nameOfSubFolder(SUBNAME, [PARENTNAME])
376
377       Mail::Box::IMAP4->nameOfSubFolder(SUBNAME, [PARENTNAME])
378
379           See "Sub-folders" in Mail::Box
380
381       $obj->openRelatedFolder(OPTIONS)
382
383           See "Sub-folders" in Mail::Box
384
385       $obj->openSubFolder(SUBNAME, OPTIONS)
386
387           See "Sub-folders" in Mail::Box
388
389       $obj->topFolderWithMessages
390
391       Mail::Box::IMAP4->topFolderWithMessages
392
393           See "Sub-folders" in Mail::Box
394
395       Internals
396
397       $obj->body([BODY])
398
399       $obj->coerce(MESSAGE, OPTIONS)
400
401           See "Internals" in Mail::Box
402
403       $obj->create(FOLDER, OPTIONS)
404
405       Mail::Box::IMAP4->create(FOLDER, OPTIONS)
406
407           See "METHODS" in Mail::Box::Net
408
409       $obj->createTransporter(CLASS, OPTIONS)
410
411           Create a transporter object (an instance of Mail::Trans‐
412           port::IMAP4), where CLASS defines the exact object type.  As
413           OPTIONS, everything which is acceptable to a transporter initiation
414           can be used (see Mail::Transport::IMAP4::new().
415
416            Option         --Default
417            join_connection  true
418
419           . join_connection BOOLEAN
420
421               See new(join_connection).  When false, the connection will
422               never be shared with other IMAP mail boxes.
423
424       $obj->determineBodyType(MESSAGE, HEAD)
425
426           See "Internals" in Mail::Box
427
428       $obj->fetch(ARRAY-OF-MESSAGES⎪MESSAGE-SELECTION, INFO)
429
430           Low-level data retreival about one or more messages via IMAP4 from
431           the remote server. Some of this data may differ from the informa‐
432           tion which is stored in the message objects which are created by
433           MailBox, so you should avoid the use of this method for your own
434           purposes.  The IMAP implementation provides some wrappers around
435           this, providing the correct behavior.
436
437           An array of MESSAGES may be specified or some MESSAGE SELECTION,
438           acceptable to Mail::Box::messages().  Examples of the latter are
439           'ALL', 'DELETED', or "spam" (messages labelled to contain spam).
440
441           The INFO contains one or more attributes as defined by the IMAP
442           protocol.  You have to read the full specs of the related RFCs to
443           see these.
444
445       Mail::Box::IMAP4->foundIn([FOLDERNAME], OPTIONS)
446
447           See "Internals" in Mail::Box
448
449       $obj->getHead(MESSAGE)
450
451           Read the header for the specified message from the remote server.
452           "undef" is returned in case the message disappeared.
453
454       $obj->getHeadAndBody(MESSAGE)
455
456           Read all data for the specified message from the remote server.
457           Return head and body of the mesasge as list, or an empty list if
458           the MESSAGE disappeared from the server.
459
460       $obj->lineSeparator([STRING⎪'CR'⎪'LF'⎪'CRLF'])
461
462           See "Internals" in Mail::Box
463
464       $obj->locker
465
466           See "Internals" in Mail::Box
467
468       $obj->read(OPTIONS)
469
470           See "Internals" in Mail::Box
471
472       $obj->readMessages(OPTIONS)
473
474           See "Internals" in Mail::Box
475
476       $obj->storeMessage(MESSAGE)
477
478           See "Internals" in Mail::Box
479
480       $obj->toBeThreaded(MESSAGES)
481
482           See "Internals" in Mail::Box
483
484       $obj->toBeUnthreaded(MESSAGES)
485
486           See "Internals" in Mail::Box
487
488       $obj->transporter([OBJECT])
489
490           Returns the object which is the interface to the IMAP4 protocol
491           handler.  The IMAP4 handler has the current folder selected.  When
492           an OBJECT is specified, it is set to be the transporter from that
493           moment on.  The OBJECT must extend Mail::Transport::IMAP4.
494
495       $obj->updateMessages(OPTIONS)
496
497           See "Internals" in Mail::Box
498
499       $obj->write(OPTIONS)
500
501           The IMAP protocol usually writes the data immediately to the remote
502           server, because that's what the protocol wants.  However, some
503           options to new() may delay that to boost performance.  This method
504           will, when the folder is being closed, write that info after all.
505
506            Option      --Defined in     --Default
507            force         Mail::Box        <false>
508            save_deleted                   <false>
509
510           . force BOOLEAN
511
512           . save_deleted BOOLEAN
513
514               You may be able to save the messages which are flagged for
515               deletion now, but they will be removed anyway when the folder
516               is closed.
517
518       $obj->writeMessages(OPTIONS)
519
520        Option     --Defined in     --Default
521        messages     Mail::Box        <required>
522        transporter                   <required>
523
524           . messages ARRAY
525
526           . transporter OBJECT
527
528       Other methods
529
530       $obj->timespan2seconds(TIME)
531
532       Mail::Box::IMAP4->timespan2seconds(TIME)
533
534           See "Other methods" in Mail::Box
535
536       Error handling
537
538       $obj->AUTOLOAD
539
540           See "Error handling" in Mail::Reporter
541
542       $obj->addReport(OBJECT)
543
544           See "Error handling" in Mail::Reporter
545
546       $obj->defaultTrace([LEVEL]⎪[LOGLEVEL, TRACELEVEL]⎪[LEVEL, CALLBACK])
547
548       Mail::Box::IMAP4->defaultTrace([LEVEL]⎪[LOGLEVEL, TRACELEVEL]⎪[LEVEL,
549       CALLBACK])
550
551           See "Error handling" in Mail::Reporter
552
553       $obj->errors
554
555           See "Error handling" in Mail::Reporter
556
557       $obj->log([LEVEL [,STRINGS]])
558
559       Mail::Box::IMAP4->log([LEVEL [,STRINGS]])
560
561           See "Error handling" in Mail::Reporter
562
563       $obj->logPriority(LEVEL)
564
565       Mail::Box::IMAP4->logPriority(LEVEL)
566
567           See "Error handling" in Mail::Reporter
568
569       $obj->logSettings
570
571           See "Error handling" in Mail::Reporter
572
573       $obj->notImplemented
574
575           See "Error handling" in Mail::Reporter
576
577       $obj->report([LEVEL])
578
579           See "Error handling" in Mail::Reporter
580
581       $obj->reportAll([LEVEL])
582
583           See "Error handling" in Mail::Reporter
584
585       $obj->trace([LEVEL])
586
587           See "Error handling" in Mail::Reporter
588
589       $obj->warnings
590
591           See "Error handling" in Mail::Reporter
592
593       Cleanup
594
595       $obj->DESTROY
596
597           See "Cleanup" in Mail::Box
598
599       $obj->inGlobalDestruction
600
601           See "Cleanup" in Mail::Reporter
602

DETAILS

604       How IMAP4 folders work
605

DIAGNOSTICS

607       Warning: Cannot find head back for $uidl in $folder.
608
609       The header was read before, but now seems empty: the IMAP4 server does
610       not produce the header lines anymore.
611
612       Warning: Cannot read body for $uidl in $folder.
613
614       The header of the message was retreived from the IMAP4 server, but the
615       body is not read, for an unknown reason.
616
617       Error: Copying failed for one message.
618
619       For some reason, for instance disc full, removed by external process,
620       or read-protection, it is impossible to copy one of the messages.
621       Copying will proceed for the other messages.
622
623       Error: Couldn't select IMAP4 folder $name
624
625       Error: Destination folder $name is not writable.
626
627       The folder where the messages are copied to is not opened with write
628       access (see new(access)).  This has no relation with write permission
629       to the folder which is controled by your operating system.
630
631       Warning: Different messages with id $msgid
632
633       The message id is discovered more than once within the same folder, but
634       the content of the message seems to be different.  This should not be
635       possible: each message must be unique.
636
637       Error: Folder $name not deleted: not writable.
638
639       The folder must be opened with write access via new(access), otherwise
640       removing it will be refused.  So, you may have write-access according
641       to the operating system, but that will not automatically mean that this
642       "delete" method permits you to.  The reverse remark is valid as well.
643
644       Notice: Impossible to keep deleted messages in IMAP
645
646       Some folder type have a 'deleted' flag which can be stored in the
647       folder to be performed later.  The folder keeps that knowledge even
648       when the folder is rewritten.  Well, IMAP4 cannot play that trick.
649
650       Error: Invalid timespan '$timespan' specified.
651
652       The string does not follow the strict rules of the time span syntax
653       which is permitted as parameter.
654
655       Warning: Message $uidl disappeared from $folder.
656
657       Trying to get the specific message from the server, but it appears to
658       be gone.
659
660       Warning: Message $uidl disappeared from $folder.
661
662       Trying to get the specific message from the server, but it appears to
663       be gone.
664
665       Warning: Message-id '$msgid' does not contain a domain.
666
667       According to the RFCs, message-ids need to contain a unique random
668       part, then an "@", and then a domain name.  This is made to avoid the
669       creation of two messages with the same id.  The warning emerges when
670       the "@" is missing from the string.
671
672       Error: No IMAP4 transporter configured
673
674       Error: Package $package does not implement $method.
675
676       Fatal error: the specific package (or one of its superclasses) does not
677       implement this method where it should. This message means that some
678       other related classes do implement this method however the class at
679       hand does not.  Probably you should investigate this and probably
680       inform the author of the package.
681
682       Error: Unable to create subfolder $name of $folder.
683
684       The copy includes the subfolders, but for some reason it was not possi‐
685       ble to copy one of these.  Copying will proceed for all other sub-fold‐
686       ers.
687

LICENSE

693       Copyrights 2001-2007 by Mark Overmeer.For other contributors see
694       ChangeLog.
695
696       This program is free software; you can redistribute it and/or modify it
697       under the same terms as Perl itself.  See
698       http://www.perl.com/perl/misc/Artistic.html
699
700
701
702perl v5.8.8                       2007-03-25               Mail::Box::IMAP4(3)