Mail::Transport::IMAP4(3pm)

1Mail::Transport::IMAP4(U3s)er Contributed Perl DocumentatMiaoinl::Transport::IMAP4(3)
2
3
4

NAME

6       Mail::Transport::IMAP4 - proxy to Mail::IMAPClient
7

INHERITANCE

9        Mail::Transport::IMAP4
10          is a Mail::Transport::Receive
11          is a Mail::Transport
12          is a Mail::Reporter
13

SYNOPSIS

15        my $imap = Mail::Transport::IMAP4->new(...);
16        my $message = $imap->receive($id);
17        $imap->send($message);
18

DESCRIPTION

20       ****** UNDER DEVELOPMENT *****, please help testing
21
22       The IMAP4 protocol is quite complicated: it is feature rich and allows
23       verious asynchronous actions.  The main document describing IMAP is
24       rfc3501 (which obsoleted the original specification of protocol 4r1 in
25       rfc2060 in March 2003).
26
27       This package, as part of MailBox, does not implement the actual proto‐
28       col itself but uses Mail::IMAPClient to do the work.  The task for this
29       package is to hide as many differences between that module's interface
30       and the common Mail::Box folder types.  Multiple Mail::Box::IMAP4 fold‐
31       ers can share one Mail::Transport::IMAP4 connection.
32

METHODS

34       $obj->url
35
36           Represent this imap4 connection as URL.
37
38       Constructors
39
40       Mail::Transport::IMAP4->new(OPTIONS)
41
42           Create the IMAP connection to the server.  IMAP servers can handle
43           multiple folders for a single user, which means that connections
44           may get shared.  This is sharing is hidden for the user.
45
46           When an "imap_client" is specified, then the options "hostname",
47           "port", "username", and "password" are extracted from it.
48
49            Option      --Defined in     --Default
50            authenticate                   'AUTO'
51            domain                         <server_name>
52            executable    Mail::Transport  undef
53            hostname      Mail::Transport  'localhost'
54            imap_client                    Mail::IMAPClient
55            interval      Mail::Transport  30
56            log           Mail::Reporter   'WARNINGS'
57            password      Mail::Transport  undef
58            port          Mail::Transport  143
59            proxy         Mail::Transport  undef
60            retry         Mail::Transport  <false>
61            timeout       Mail::Transport  120
62            trace         Mail::Reporter   'WARNINGS'
63            username      Mail::Transport  undef
64            via           Mail::Transport  'imap'
65
66           . authenticate TYPE⎪ARRAY-OF-TYPES
67
68               Authenthication method to login(), which will be passed to
69               Mail::IMAPClient method authenticate().  See the latter method
70               for the available types.
71
72           . domain WINDOWS_DOMAIN
73
74               Used for NTLM authentication.
75
76           . executable FILENAME
77
78           . hostname HOSTNAME⎪ARRAY-OF-HOSTNAMES
79
80           . imap_client OBJECT⎪CLASS
81
82               When an OBJECT is supplied, that client will be used for the
83               implementation of the IMAP4 protocol. Information about server
84               and such are extracted from the OBJECT to have the accessors to
85               produce correct results. The OBJECT shall be a Mail::IMAP‐
86               Client.
87
88               When a CLASS is given, an object of that type is created for
89               you.  The created object can be retreived via imapClient(), and
90               than configured as defined by Mail::IMAPClient.
91
92           . interval SECONDS
93
94           . log LEVEL
95
96           . password STRING
97
98           . port INTEGER
99
100           . proxy PATH
101
102           . retry NUMBER⎪undef
103
104           . timeout SECONDS
105
106           . trace LEVEL
107
108           . username STRING
109
110           . via CLASS⎪NAME
111
112       Receiving mail
113
114       $obj->receive([UNIQUE-MESSAGE-ID])
115
116           See "Receiving mail" in Mail::Transport::Receive
117
118       Server connection
119
120       $obj->findBinary(NAME [, DIRECTORIES])
121
122           See "Server connection" in Mail::Transport
123
124       $obj->remoteHost
125
126           See "Server connection" in Mail::Transport
127
128       $obj->retry
129
130           See "Server connection" in Mail::Transport
131
132       Attributes
133
134       $obj->authentication(['AUTO'⎪TYPE⎪LIST-OF-TYPES])
135
136           Returned is a list of pairs (ref arrays) each describing one possi‐
137           ble way to contact the server. Each pair contains a mechanism name
138           and a challange callback (which may be "undef").
139
140           The settings are used by login() to get server access.  The initial
141           value origins from new(authenticate), but may be changed later.
142
143           Available basic TYPES are "CRAM-MD5", "NTLM", and "PLAIN".  With
144           "AUTO", all available types will be tried.  When the Authen::NTLM
145           is not installed, the "NTLM" option will silently be skipped.  Be
146           warned that, because of "PLAIN", erroneous username/password combi‐
147           nations will be passed readible as last attempt!
148
149           The "NTLM" authentication requires Authen::NTLM to be installed.
150           Other methods may be added later.  Besides, you may also specify a
151           CODE reference which implements some authentication.
152
153           An ARRAY as TYPE can be used to specify both mechanism as callback.
154           When no array is used, callback of the pair is set to "undef".  See
155           "authenticate" in Mail::IMAPClient for the gory details.
156
157           Example:
158
159            $transporter->authentication('CRAM-MD5', [MY_AUTH => \&c], 'PLAIN');
160
161            foreach my $pair ($transporter->authentication)
162            {   my ($mechanism, $challange) = @$pair;
163                ...
164            }
165
166       $obj->domain([DOMAIN])
167
168           Used in NTLM authentication to define the Windows domain which is
169           accessed.  Initially set by new(domain) and defaults to the
170           server's name.
171
172       Exchanging Information
173
174       Protocol [internals]
175
176       The follow methods handle protocol internals, and should not be used by
177       a normal user of this class.
178
179       $obj->appendMessage(MESSAGE, FOLDERNAME)
180
181           Write the message to the server.
182
183       $obj->createFolder(NAME)
184
185           Add a folder.
186
187       $obj->createImapClient(CLASS)
188
189           Create an object of CLASS, which extends Mail::IMAPClient.
190
191       $obj->currentFolder([FOLDERNAME])
192
193           Be sure that the specific FOLDER is the current one selected.  If
194           the folder is already selected, no IMAP traffic will be produced.
195
196           The boolean return value indicates whether the folder is
197           selectable. It will return undef if it does not exist.
198
199       $obj->deleteFolder(NAME)
200
201           Remove one folder.
202
203       $obj->destroyDeleted
204
205           Command the server to delete for real all messages which are
206           flagged to be deleted.
207
208       $obj->fetch(ARRAY-OF-MESSAGES, INFO)
209
210           Get some INFO about the MESSAGES from the server.  The specified
211           messages shall extend Mail::Box::Net::Message, Returned is a list
212           of hashes, each info about one result.  The contents of the hash
213           differs per INFO, but at least a "message" field will be present,
214           to relate to the message in question.
215
216           The right folder should be selected before this method is called.
217           When the connection was lost, "undef" is returned.  Without any
218           messages, and empty array is returned.  The retrieval is done by
219           Mail::IMAPClient method "fetch()", which is then parsed.
220
221       $obj->flagsToLabels(WHAT⎪FLAGS)
222
223       Mail::Transport::IMAP4->flagsToLabels(WHAT⎪FLAGS)
224
225           In SCALAR context, a hash with labels is returned.  In LIST con‐
226           text, pairs are returned.
227
228           The WHAT parameter can be 'SET', 'CLEAR', or 'REPLACE'.  With the
229           latter, all standard imap flags do not appear in the list will be
230           ignored: their value may either by set or cleared.  See getFlags()
231
232           Unknown flags in LIST are stripped from their backslash and
233           lower-cased.  For instance, '\SomeWeirdFlag' will become
234           `someweirdflag => 1'.
235
236           Example: translating IMAP4 flags into MailBox flags
237
238            my @flags  = ('\Seen', '\Flagged');
239            my $labels = Mail::Transport::IMAP4->flags2labels(SET => @flags);
240
241       $obj->folders([FOLDERNAME])
242
243           Returns a list of folder names which are sub-folders of the speci‐
244           fied FOLDERNAME.  Without FOLDERNAME, the top-level foldernames are
245           returned.
246
247       $obj->getFields(UID, NAME, [NAME, ...])
248
249           Get the records with the specified NAMES from the header.  The
250           header fields are returned as list of Mail::Message::Field::Fast
251           objects.  When the name is "ALL", the whole header is returned.
252
253       $obj->getFlags(FOLDER, ID)
254
255           Returns the values of all flags which are related to the message
256           with the specified ID.  These flags are translated into the names
257           which are standard for the MailBox suite.
258
259           A HASH is returned.  Names which do not appear will also provide a
260           value in the returned: the negative for the value is it was
261           present.
262
263       $obj->getMessageAsString(MESSAGE⎪UID)
264
265           Returns the whole text of the specified message: the head and the
266           body.
267
268       $obj->ids
269
270           Returns a list of UIDs which are defined by the IMAP server.
271
272       $obj->imapClient
273
274           Returns the object which implements the IMAP4 protocol, an instance
275           of a Mail::IMAPClient, which is logged-in and ready to use.
276
277           If the contact to the server was still present or could be estab‐
278           lished, an Mail::IMAPClient object is returned.  Else, "undef" is
279           returned and no further actions should be tried on the object.
280
281       $obj->labelsToFlags(HASH⎪PAIRS)
282
283       Mail::Transport::IMAP4->labelsToFlags(HASH⎪PAIRS)
284
285           Convert MailBox labels into IMAP flags.  Returned is a string.
286           Unsupported labels are ignored.
287
288       $obj->listFlags
289
290           Returns all predefined flags as list.
291
292       $obj->login
293
294           Establish a new connection to the IMAP4 server, using username and
295           password.
296
297       $obj->setFlags(ID, LABEL, VALUE, [LABEL, VALUE], ...)
298
299           Change the flags on the message which are represented by the label.
300           The value which can be related to the label will be lost, because
301           IMAP only defines a boolean value, where MailBox labels can contain
302           strings.
303
304           Returned is a list of LABEL=>VALUE pairs which could not be send to
305           the IMAP server.  These values may be cached in a different way.
306
307       Error handling
308
309       $obj->AUTOLOAD
310
311           See "Error handling" in Mail::Reporter
312
313       $obj->addReport(OBJECT)
314
315           See "Error handling" in Mail::Reporter
316
317       $obj->defaultTrace([LEVEL]⎪[LOGLEVEL, TRACELEVEL]⎪[LEVEL, CALLBACK])
318
319       Mail::Transport::IMAP4->defaultTrace([LEVEL]⎪[LOGLEVEL,
320       TRACELEVEL]⎪[LEVEL, CALLBACK])
321
322           See "Error handling" in Mail::Reporter
323
324       $obj->errors
325
326           See "Error handling" in Mail::Reporter
327
328       $obj->log([LEVEL [,STRINGS]])
329
330       Mail::Transport::IMAP4->log([LEVEL [,STRINGS]])
331
332           See "Error handling" in Mail::Reporter
333
334       $obj->logPriority(LEVEL)
335
336       Mail::Transport::IMAP4->logPriority(LEVEL)
337
338           See "Error handling" in Mail::Reporter
339
340       $obj->logSettings
341
342           See "Error handling" in Mail::Reporter
343
344       $obj->notImplemented
345
346           See "Error handling" in Mail::Reporter
347
348       $obj->report([LEVEL])
349
350           See "Error handling" in Mail::Reporter
351
352       $obj->reportAll([LEVEL])
353
354           See "Error handling" in Mail::Reporter
355
356       $obj->trace([LEVEL])
357
358           See "Error handling" in Mail::Reporter
359
360       $obj->warnings
361
362           See "Error handling" in Mail::Reporter
363
364       Cleanup
365
366       $obj->DESTROY
367
368           The connection is cleanly terminated when the program is termi‐
369           nated.
370
371       $obj->inGlobalDestruction
372
373           See "Cleanup" in Mail::Reporter
374

DIAGNOSTICS

376       Error: Cannot connect to $host:$port for IMAP4: $!
377
378       Error: IMAP cannot connect to $host: $@
379
380       Notice: IMAP4 authenication $mechanism to $host:$port successful
381
382       Error: IMAP4 requires a username and password
383
384       Error: IMAP4 username $username requires a password
385
386       Error: Package $package does not implement $method.
387
388       Fatal error: the specific package (or one of its superclasses) does not
389       implement this method where it should. This message means that some
390       other related classes do implement this method however the class at
391       hand does not.  Probably you should investigate this and probably
392       inform the author of the package.
393

LICENSE

399       Copyrights 2001-2007 by Mark Overmeer.For other contributors see
400       ChangeLog.
401
402       This program is free software; you can redistribute it and/or modify it
403       under the same terms as Perl itself.  See
404       http://www.perl.com/perl/misc/Artistic.html
405
406
407
408perl v5.8.8                       2007-03-25         Mail::Transport::IMAP4(3)