1Mail::Server::IMAP4::UsUesre(r3)Contributed Perl DocumenMtaaitli:o:nServer::IMAP4::User(3)
2
6 Mail::Server::IMAP4::User - manage the folders of one user
7
9 Mail::Server::IMAP4::User
10 is a Mail::Box::Manage::User
11 is a Mail::Box::Manager
12 is a Mail::Reporter
13
15 my $mgr = Mail::Server::IMAP4::User->new(...);
16
18 This class adds IMAP protocol features to the normal
19 Mail::Box::Manager.
20 Extends "DESCRIPTION" in Mail::Box::Manage::User.
22
24 Extends "METHODS" in Mail::Box::Manage::User.
25 Constructors
27 Extends "Constructors" in Mail::Box::Manage::User.
28 Mail::Server::IMAP4::User->new(%options)
30 -Option --Defined in --Default
31 autodetect Mail::Box::Manager undef
32 collection_type Mail::Box::Manage::User Mail::Box::Collection
33 default_folder_type Mail::Box::Manager 'mbox'
34 delimiter Mail::Box::Manage::User "/"
35 folder_id_type Mail::Box::Manage::User Mail::Box::Identity
36 folder_types Mail::Box::Manager <all standard types>
37 folderdir Mail::Box::Manager [ '.' ]
38 folderdirs Mail::Box::Manager <synonym for C<folderdir>>
39 identity Mail::Box::Manage::User <required>
40 inbox Mail::Box::Manage::User undef
41 index_filename $folderdir/index
42 log Mail::Reporter 'WARNINGS'
43 topfolder_name Mail::Box::Manage::User '='
44 trace Mail::Reporter 'WARNINGS'
45 autodetect => TYPE|ARRAY-OF-TYPES
47 collection_type => CLASS
48 default_folder_type => NAME|CLASS
49 delimiter => STRING
50 folder_id_type => CLASS|OBJECT
51 folder_types => NEW-TYPE | ARRAY-OF-NEW-TYPES
52 folderdir => DIRECTORY
53 folderdirs => [DIRECTORIES]
54 identity => OBJECT
55 inbox => NAME
56 index_filename => FILENAME
57 log => LEVEL
58 topfolder_name => STRING
59 trace => LEVEL
60 Attributes
62 Extends "Attributes" in Mail::Box::Manage::User.
63 $obj->defaultFolderType()
65 Inherited, see "Attributes" in Mail::Box::Manager
66 $obj->folderTypes()
68 Inherited, see "Attributes" in Mail::Box::Manager
69 $obj->folderdir()
71 Inherited, see "Attributes" in Mail::Box::Manager
72 $obj->identity()
74 Inherited, see "Attributes" in Mail::Box::Manage::User
75 $obj->inbox( [$name] )
77 Inherited, see "Attributes" in Mail::Box::Manage::User
78 $obj->indexFilename()
80 Returns the filename of the index file.
81 $obj->registerType($type, $class, %options)
83 Inherited, see "Attributes" in Mail::Box::Manager
84 Manage open folders
86 Extends "Manage open folders" in Mail::Box::Manage::User.
87 $obj->close($folder, %options)
89 Inherited, see "Manage open folders" in Mail::Box::Manager
90 $obj->closeAllFolders(, %options)
92 Inherited, see "Manage open folders" in Mail::Box::Manager
93 $obj->isOpenFolder($folder)
95 Inherited, see "Manage open folders" in Mail::Box::Manager
96 $obj->open( [$foldername], %options )
98 Inherited, see "Manage open folders" in Mail::Box::Manager
99 $obj->openFolders()
101 Inherited, see "Manage open folders" in Mail::Box::Manager
102 Manage existing folders
104 Extends "Manage existing folders" in Mail::Box::Manage::User.
105 Manage folders
107 Extends "Manage folders" in Mail::Box::Manage::User.
108 $obj->create($name, %options)
110 Creates a new folder with the specified name. Folder info is
111 returned, which will be very simple. In the accidental case that
112 the folder already exists, a warning will be issued, and that
113 folder's data returned.
114 -Option --Defined in --Default
116 create_real Mail::Box::Manage::User <true>
117 create_supers Mail::Box::Manage::User <false>
118 deleted Mail::Box::Manage::User <false>
119 id_options Mail::Box::Manage::User []
120 create_real => BOOLEAN
122 create_supers => BOOLEAN
123 deleted => BOOLEAN
124 id_options => ARRAY
125 $obj->delete($name, %options)
126 Remove all signs from the folder on the file-system. Messages
127 still in the folder will be removed. This method returns a true
128 value when the folder has been removed or not found, so "false"
129 means failure.
130 It is also possible to delete a folder using "$folder->delete",
132 which will call this method here. %options, which are used for
133 some other folder types, will be ignored here: the user's index
134 contains the required details.
135 -Option --Defined in --Default
137 recursive Mail::Box::Manager <folder's default>
138 recursive => BOOLEAN
140 example: how to delete a folder
142 print "no xyz (anymore)\n" if $user->delete('xyz');
144 $obj->folder($name)
146 Inherited, see "Manage folders" in Mail::Box::Manage::User
147 $obj->folderCollection($name)
149 Inherited, see "Manage folders" in Mail::Box::Manage::User
150 $obj->folderInfo($name)
152 Returns a hash with folder information. In normal circumstances,
153 it is cheap to get these details, because they are cached in an
154 index file, maintained by Mail::Box::Netzwert::UserIndex.
155 DO NOT modify the values you find in the hash, because that data
157 may or may not be lost (see Mail::Box::Netzwert::UserIndex
158 subroutine change).
159 DO NOT trust on the existence of any field in the info: fields may
161 get renamed, removed, or added over time. Not all folder indexes
162 will be generated by the same software release.
163 example: how to get global info about a folder
165 my $info = $user->folderInfo($name); # get info
167 $obj->rename($oldname, $newname, %options)
169 Inherited, see "Manage folders" in Mail::Box::Manage::User
170 $obj->topfolder()
172 Inherited, see "Manage folders" in Mail::Box::Manage::User
173 Move messages to folders
175 Extends "Move messages to folders" in Mail::Box::Manage::User.
176 $obj->appendMessage( [$folder|$foldername], $messages, %options )
178 Inherited, see "Move messages to folders" in Mail::Box::Manager
179 $obj->copyMessage( [$folder|$foldername], $messages, %options )
181 Inherited, see "Move messages to folders" in Mail::Box::Manager
182 $obj->moveMessage( [$folder|$foldername], $messages, %options )
184 Inherited, see "Move messages to folders" in Mail::Box::Manager
185 Manage message threads
187 Extends "Manage message threads" in Mail::Box::Manage::User.
188 $obj->threads( [$folders], %options )
190 Inherited, see "Manage message threads" in Mail::Box::Manager
191 Internals
193 Extends "Internals" in Mail::Box::Manage::User.
194 $obj->decodeFolderURL($url)
196 Inherited, see "Internals" in Mail::Box::Manager
197 $obj->toBeThreaded($folder, $messages)
199 Inherited, see "Internals" in Mail::Box::Manager
200 $obj->toBeUnthreaded($folder, $messages)
202 Inherited, see "Internals" in Mail::Box::Manager
203 Error handling
205 Extends "Error handling" in Mail::Box::Manage::User.
206 $obj->AUTOLOAD()
208 Inherited, see "Error handling" in Mail::Reporter
209 $obj->addReport($object)
211 Inherited, see "Error handling" in Mail::Reporter
212 $obj->defaultTrace( [$level]|[$loglevel, $tracelevel]|[$level,
214 $callback] )
215 Mail::Server::IMAP4::User->defaultTrace( [$level]|[$loglevel,
216 $tracelevel]|[$level, $callback] )
217 Inherited, see "Error handling" in Mail::Reporter
218 $obj->errors()
220 Inherited, see "Error handling" in Mail::Reporter
221 $obj->log( [$level, [$strings]] )
223 Mail::Server::IMAP4::User->log( [$level, [$strings]] )
224 Inherited, see "Error handling" in Mail::Reporter
225 $obj->logPriority($level)
227 Mail::Server::IMAP4::User->logPriority($level)
228 Inherited, see "Error handling" in Mail::Reporter
229 $obj->logSettings()
231 Inherited, see "Error handling" in Mail::Reporter
232 $obj->notImplemented()
234 Inherited, see "Error handling" in Mail::Reporter
235 $obj->report( [$level] )
237 Inherited, see "Error handling" in Mail::Reporter
238 $obj->reportAll( [$level] )
240 Inherited, see "Error handling" in Mail::Reporter
241 $obj->trace( [$level] )
243 Inherited, see "Error handling" in Mail::Reporter
244 $obj->warnings()
246 Inherited, see "Error handling" in Mail::Reporter
247 Cleanup
249 Extends "Cleanup" in Mail::Box::Manage::User.
250 $obj->DESTROY()
252 Inherited, see "Cleanup" in Mail::Reporter
253
255 Extends "DETAILS" in Mail::Box::Manage::User.
256
258 Error: Cannot create folder directory $dir: $!
259 Error: Cannot rename $name to $new: higher levels missing
260 Unless you set create(create_supers), all higher level folders must
261 exist before this new one can be created.
262 Error: Cannot write name for folder in $file: $!
264 Error: Failed writing folder name to $file: $!
265 Warning: Folder $name already exists, creation skipped
266 Error: Folder $name is already open.
267 You cannot ask the manager for a folder which is already open. In
268 some older releases (before MailBox 2.049), this was permitted, but
269 then behaviour changed, because many nasty side-effects are to be
270 expected. For instance, an Mail::Box::update() on one folder
271 handle would influence the second, probably unexpectedly.
272 Error: Folder $name is not a Mail::Box; cannot add a message.
274 The folder where the message should be appended to is an object
275 which is not a folder type which extends Mail::Box. Probably, it
276 is not a folder at all.
277 Warning: Folder does not exist, failed opening $type folder $name.
279 The folder does not exist and creating is not permitted (see
280 open(create)) or did not succeed. When you do not have sufficient
281 access rights to the folder (for instance wrong password for POP3),
282 this warning will be produced as well.
283 The manager tried to open a folder of the specified type. It may
285 help to explicitly state the type of your folder with the "type"
286 option. There will probably be another warning or error message
287 which is related to this report and provides more details about its
288 cause. You may also have a look at new(autodetect) and
289 new(folder_types).
290 Warning: Folder type $type is unknown, using autodetect.
292 The specified folder type (see open(type), possibly derived from
293 the folder name when specified as url) is not known to the manager.
294 This may mean that you forgot to require the Mail::Box extension
295 which implements this folder type, but probably it is a typo.
296 Usually, the manager is able to figure-out which type to use by
297 itself.
298 Error: Illegal folder URL '$url'.
300 The folder name was specified as URL, but not according to the
301 syntax. See decodeFolderURL() for an description of the syntax.
302 Error: No foldername specified to open.
304 open() needs a folder name as first argument (before the list of
305 options), or with the "folder" option within the list. If no name
306 was found, the MAIL environment variable is checked. When even
307 that does not result in a usable folder, then this error is
308 produced. The error may be caused by an accidental odd-length
309 option list.
310 Error: Package $package does not implement $method.
312 Fatal error: the specific package (or one of its superclasses) does
313 not implement this method where it should. This message means that
314 some other related classes do implement this method however the
315 class at hand does not. Probably you should investigate this and
316 probably inform the author of the package.
317 Error: Unable to remove folder $dir
319 Error: Use appendMessage() to add messages which are not in a folder.
320 You do not need to copy this message into the folder, because you
321 do not share the message between folders.
322 Warning: Use moveMessage() or copyMessage() to move between open
324 folders.
325 The message is already part of a folder, and now it should be
326 appended to a different folder. You need to decide between copy or
327 move, which both will clone the message (not the body, because they
328 are immutable).
329 Warning: Will never create a folder $name without having write access.
331 You have set open(create), but only want to read the folder.
332 Create is only useful for folders which have write or append access
333 modes (see Mail::Box::new(access)).
334
336 This module is part of Mail-Box-IMAP4 distribution version 3.008, built
337 on August 09, 2023. Website: http://perl.overmeer.net/CPAN/
338
340 Copyrights 2001-2023 by [Mark Overmeer]. For other contributors see
341 ChangeLog.
342 This program is free software; you can redistribute it and/or modify it
344 under the same terms as Perl itself. See http://dev.perl.org/licenses/
345perl v5.38.0 2023-08-21 Mail::Server::IMAP4::User(3)