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
24       information, and focusses solely on the correct handling of messages
25       within a IMAP4 folder.  More than one IMAP4 folder can be handled by
26       one single IMAP4 connection.
27

OVERLOADED

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

METHODS

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

DIAGNOSTICS

484       Warning: Cannot find head back for $uidl in $folder.
485           The header was read before, but now seems empty: the IMAP4 server
486           does not produce the header lines anymore.
487
488       Warning: Cannot read body for $uidl in $folder.
489           The header of the message was retreived from the IMAP4 server, but
490           the body is not read, for an unknown reason.
491
492       Error: Copying failed for one message.
493           For some reason, for instance disc full, removed by external
494           process, or read-protection, it is impossible to copy one of the
495           messages.  Copying will proceed for the other messages.
496
497       Error: Couldn't select IMAP4 folder $name
498       Error: Destination folder $name is not writable.
499           The folder where the messages are copied to is not opened with
500           write access (see new(access)).  This has no relation with write
501           permission to the folder which is controled by your operating
502           system.
503
504       Warning: Different messages with id $msgid
505           The message id is discovered more than once within the same folder,
506           but the content of the message seems to be different.  This should
507           not be possible: each message must be unique.
508
509       Error: Folder $name not deleted: not writable.
510           The folder must be opened with write access via new(access),
511           otherwise removing it will be refused.  So, you may have write-
512           access according to the operating system, but that will not
513           automatically mean that this "delete" method permits you to.  The
514           reverse remark is valid as well.
515
516       Notice: Impossible to keep deleted messages in IMAP
517           Some folder type have a 'deleted' flag which can be stored in the
518           folder to be performed later.  The folder keeps that knowledge even
519           when the folder is rewritten.  Well, IMAP4 cannot play that trick.
520
521       Error: Invalid timespan '$timespan' specified.
522           The string does not follow the strict rules of the time span syntax
523           which is permitted as parameter.
524
525       Warning: Message $uidl disappeared from $folder.
526           Trying to get the specific message from the server, but it appears
527           to be gone.
528
529       Warning: Message $uidl disappeared from $folder.
530           Trying to get the specific message from the server, but it appears
531           to be gone.
532
533       Warning: Message-id '$msgid' does not contain a domain.
534           According to the RFCs, message-ids need to contain a unique random
535           part, then an "@", and then a domain name.  This is made to avoid
536           the creation of two messages with the same id.  The warning emerges
537           when the "@" is missing from the string.
538
539       Error: No IMAP4 transporter configured
540       Error: Package $package does not implement $method.
541           Fatal error: the specific package (or one of its superclasses) does
542           not implement this method where it should. This message means that
543           some other related classes do implement this method however the
544           class at hand does not.  Probably you should investigate this and
545           probably inform the author of the package.
546
547       Error: Unable to create subfolder $name of $folder.
548           The copy includes the subfolders, but for some reason it was not
549           possible to copy one of these.  Copying will proceed for all other
550           sub-folders.
551

LICENSE

557       Copyrights 2001-2011 by Mark Overmeer. For other contributors see
558       ChangeLog.
559
560       This program is free software; you can redistribute it and/or modify it
561       under the same terms as Perl itself.  See
562       http://www.perl.com/perl/misc/Artistic.html
563
564
565
566perl v5.12.3                      2011-01-26               Mail::Box::IMAP4(3)