Mail::Box::Message::Destructed(3pm)

1Mail::Box::Message::DesUtsreurctCeodn(t3r)ibuted Perl DoMcauimle:n:tBaotxi:o:nMessage::Destructed(3)
2
3
4

NAME

6       Mail::Box::Message::Destructed - a destructed message
7

INHERITANCE

9        Mail::Box::Message::Destructed
10          is a Mail::Box::Message
11          is a Mail::Message
12          is a Mail::Reporter
13

SYNOPSIS

15        $folder->message(3)->destruct;
16

DESCRIPTION

18       When a message folder is read, each message will be parsed into Perl
19       structures.  Especially the header structure can consume a huge amount
20       of memory (message bodies can be moved to external temporary files).
21       Destructed messages have forcefully cleaned-up all header and body
22       information, and are therefore much smaller.  Some useful information
23       is still in the object.
24
25       BE WARNED: once a message is destructed, it cannot be revived.
26       Destructing enforces irreversable deletion from the folder.  If you
27       have a folder opened for read-only, the message will stay in that
28       folder, but otherwise it may be deleted.
29
30       Extends "DESCRIPTION" in Mail::Box::Message.
31

METHODS

33       Extends "METHODS" in Mail::Box::Message.
34
35   Constructors
36       Extends "Constructors" in Mail::Box::Message.
37
38       $obj->clone(%options)
39           Inherited, see "Constructors" in Mail::Message
40
41       Mail::Box::Message::Destructed->new($message_id, %options)
42           You cannot instantiate a destructed message object.  Destruction is
43           done by calling Mail::Box::Message::destruct().
44
45            -Option    --Defined in        --Default
46             body        Mail::Message       undef
47             body_type   Mail::Box::Message  <from folder>
48             deleted     Mail::Message       <false>
49             field_type  Mail::Message       undef
50             folder      Mail::Box::Message  <required>
51             head        Mail::Message       undef
52             head_type   Mail::Message       Mail::Message::Head::Complete
53             labels      Mail::Message       {}
54             log         Mail::Reporter      'WARNINGS'
55             messageId   Mail::Message       undef
56             modified    Mail::Message       <false>
57             size        Mail::Box::Message  undef
58             trace       Mail::Reporter      'WARNINGS'
59             trusted     Mail::Message       <false>
60
61           body => OBJECT
62           body_type => CODE|CLASS
63           deleted => BOOLEAN
64           field_type => CLASS
65           folder => FOLDER
66           head => OBJECT
67           head_type => CLASS
68           labels => ARRAY|HASH
69           log => LEVEL
70           messageId => STRING
71           modified => BOOLEAN
72           size => INTEGER
73           trace => LEVEL
74           trusted => BOOLEAN
75
76   Constructing a message
77       Extends "Constructing a message" in Mail::Box::Message.
78
79       $obj->bounce( [<$rg_object|%options>] )
80           Inherited, see "Constructing a message" in
81           Mail::Message::Construct::Bounce
82
83       Mail::Box::Message::Destructed->build( [$message|$part|$body], $content
84       )
85           Inherited, see "Constructing a message" in
86           Mail::Message::Construct::Build
87
88       Mail::Box::Message::Destructed->buildFromBody($body, [$head], $headers)
89           Inherited, see "Constructing a message" in
90           Mail::Message::Construct::Build
91
92       $obj->forward(%options)
93           Inherited, see "Constructing a message" in
94           Mail::Message::Construct::Forward
95
96       $obj->forwardAttach(%options)
97           Inherited, see "Constructing a message" in
98           Mail::Message::Construct::Forward
99
100       $obj->forwardEncapsulate(%options)
101           Inherited, see "Constructing a message" in
102           Mail::Message::Construct::Forward
103
104       $obj->forwardInline(%options)
105           Inherited, see "Constructing a message" in
106           Mail::Message::Construct::Forward
107
108       $obj->forwardNo(%options)
109           Inherited, see "Constructing a message" in
110           Mail::Message::Construct::Forward
111
112       $obj->forwardPostlude()
113           Inherited, see "Constructing a message" in
114           Mail::Message::Construct::Forward
115
116       $obj->forwardPrelude()
117           Inherited, see "Constructing a message" in
118           Mail::Message::Construct::Forward
119
120       $obj->forwardSubject(STRING)
121           Inherited, see "Constructing a message" in
122           Mail::Message::Construct::Forward
123
124       Mail::Box::Message::Destructed->read($fh|STRING|SCALAR|ARRAY, %options)
125           Inherited, see "Constructing a message" in
126           Mail::Message::Construct::Read
127
128       $obj->rebuild(%options)
129           Inherited, see "Constructing a message" in
130           Mail::Message::Construct::Rebuild
131
132       $obj->reply(%options)
133           Inherited, see "Constructing a message" in
134           Mail::Message::Construct::Reply
135
136       $obj->replyPrelude( [STRING|$field|$address|ARRAY-$of-$things] )
137           Inherited, see "Constructing a message" in
138           Mail::Message::Construct::Reply
139
140       $obj->replySubject(STRING)
141       Mail::Box::Message::Destructed->replySubject(STRING)
142           Inherited, see "Constructing a message" in
143           Mail::Message::Construct::Reply
144
145   The message
146       Extends "The message" in Mail::Box::Message.
147
148       $obj->container()
149           Inherited, see "The message" in Mail::Message
150
151       $obj->copyTo($folder, %options)
152           Inherited, see "The message" in Mail::Box::Message
153
154       $obj->folder( [$folder] )
155           Inherited, see "The message" in Mail::Box::Message
156
157       $obj->isDummy()
158           Inherited, see "The message" in Mail::Message
159
160       $obj->isPart()
161           Inherited, see "The message" in Mail::Message
162
163       $obj->messageId()
164           Inherited, see "The message" in Mail::Message
165
166       $obj->moveTo($folder, %options)
167           Inherited, see "The message" in Mail::Box::Message
168
169       $obj->partNumber()
170           Inherited, see "The message" in Mail::Message
171
172       $obj->print( [$fh] )
173           Inherited, see "The message" in Mail::Message
174
175       $obj->send( [$mailer], %options )
176           Inherited, see "The message" in Mail::Message
177
178       $obj->seqnr( [$integer] )
179           Inherited, see "The message" in Mail::Box::Message
180
181       $obj->size()
182           Inherited, see "The message" in Mail::Message
183
184       $obj->toplevel()
185           Inherited, see "The message" in Mail::Message
186
187       $obj->write( [$fh] )
188           Inherited, see "The message" in Mail::Message
189
190   The header
191       Extends "The header" in Mail::Box::Message.
192
193       $obj->bcc()
194           Inherited, see "The header" in Mail::Message
195
196       $obj->cc()
197           Inherited, see "The header" in Mail::Message
198
199       $obj->date()
200           Inherited, see "The header" in Mail::Message
201
202       $obj->destinations()
203           Inherited, see "The header" in Mail::Message
204
205       $obj->from()
206           Inherited, see "The header" in Mail::Message
207
208       $obj->get($fieldname)
209           Inherited, see "The header" in Mail::Message
210
211       $obj->guessTimestamp()
212           Inherited, see "The header" in Mail::Message
213
214       $obj->head( [$head] )
215           When "undef" is specified for $head, no change has to take place
216           and the method returns silently.  In all other cases, this method
217           will complain that the header has been removed.
218
219       $obj->nrLines()
220           Inherited, see "The header" in Mail::Message
221
222       $obj->sender()
223           Inherited, see "The header" in Mail::Message
224
225       $obj->study($fieldname)
226           Inherited, see "The header" in Mail::Message
227
228       $obj->subject()
229           Inherited, see "The header" in Mail::Message
230
231       $obj->timestamp()
232           Inherited, see "The header" in Mail::Message
233
234       $obj->to()
235           Inherited, see "The header" in Mail::Message
236
237   The body
238       Extends "The body" in Mail::Box::Message.
239
240       $obj->body( [$body] )
241           When "undef" is specified for $body, no change has to take place
242           and the method returns silently.  In all other cases, this method
243           will complain that the body data has been removed.
244
245       $obj->contentType()
246           Inherited, see "The body" in Mail::Message
247
248       $obj->decoded(%options)
249           Inherited, see "The body" in Mail::Message
250
251       $obj->encode(%options)
252           Inherited, see "The body" in Mail::Message
253
254       $obj->isMultipart()
255           Inherited, see "The body" in Mail::Message
256
257       $obj->isNested()
258           Inherited, see "The body" in Mail::Message
259
260       $obj->parts( [<'ALL'|'ACTIVE'|'DELETED'|'RECURSE'|$filter>] )
261           Inherited, see "The body" in Mail::Message
262
263   Flags
264       Extends "Flags" in Mail::Box::Message.
265
266       $obj->delete()
267           Inherited, see "Flags" in Mail::Message
268
269       $obj->deleted( [BOOLEAN] )
270           Inherited, see "Flags" in Mail::Message
271
272       $obj->isDeleted()
273           Inherited, see "Flags" in Mail::Message
274
275       $obj->isModified()
276           Inherited, see "Flags" in Mail::Message
277
278       $obj->label($label|PAIRS)
279           It is possible to delete a destructed message, but not to undelete
280           it.
281
282       $obj->labels()
283           Inherited, see "Flags" in Mail::Message
284
285       $obj->labelsToStatus()
286           Inherited, see "Flags" in Mail::Message
287
288       $obj->modified( [BOOLEAN] )
289           Inherited, see "Flags" in Mail::Message
290
291       $obj->statusToLabels()
292           Inherited, see "Flags" in Mail::Message
293
294   The whole message as text
295       Extends "The whole message as text" in Mail::Box::Message.
296
297       $obj->file()
298           Inherited, see "The whole message as text" in
299           Mail::Message::Construct::Text
300
301       $obj->lines()
302           Inherited, see "The whole message as text" in
303           Mail::Message::Construct::Text
304
305       $obj->printStructure( [$fh|undef],[$indent] )
306           Inherited, see "The whole message as text" in
307           Mail::Message::Construct::Text
308
309       $obj->string()
310           Inherited, see "The whole message as text" in
311           Mail::Message::Construct::Text
312
313   Internals
314       Extends "Internals" in Mail::Box::Message.
315
316       $obj->clonedFrom()
317           Inherited, see "Internals" in Mail::Message
318
319       Mail::Box::Message::Destructed->coerce($message)
320           Coerce a Mail::Box::Message into destruction.
321
322           example: of coercion to death
323
324            Mail::Box::Message::Destructed->coerce($folder->message(1));
325            $folder->message(1)->destruct;  # same
326
327            my $msg = $folder->message(1);
328            Mail::Box::Message::Destructed->coerce($msg);
329            $msg->destruct;                 # same
330
331       $obj->diskDelete()
332           Inherited, see "Internals" in Mail::Box::Message
333
334       $obj->isDelayed()
335           Inherited, see "Internals" in Mail::Message
336
337       $obj->readBody( $parser, $head, [$bodytype] )
338           Inherited, see "Internals" in Mail::Box::Message
339
340       $obj->readFromParser( $parser, [$bodytype] )
341           Inherited, see "Internals" in Mail::Message
342
343       $obj->readHead( $parser, [$class] )
344           Inherited, see "Internals" in Mail::Message
345
346       $obj->recursiveRebuildPart($part, %options)
347           Inherited, see "Internals" in Mail::Message::Construct::Rebuild
348
349       $obj->storeBody($body)
350           Inherited, see "Internals" in Mail::Message
351
352       $obj->takeMessageId( [STRING] )
353           Inherited, see "Internals" in Mail::Message
354
355   Error handling
356       Extends "Error handling" in Mail::Box::Message.
357
358       $obj->AUTOLOAD()
359           Inherited, see "METHODS" in Mail::Message::Construct
360
361       $obj->addReport($object)
362           Inherited, see "Error handling" in Mail::Reporter
363
364       $obj->defaultTrace( [$level]|[$loglevel, $tracelevel]|[$level,
365       $callback] )
366       Mail::Box::Message::Destructed->defaultTrace( [$level]|[$loglevel,
367       $tracelevel]|[$level, $callback] )
368           Inherited, see "Error handling" in Mail::Reporter
369
370       $obj->errors()
371           Inherited, see "Error handling" in Mail::Reporter
372
373       $obj->log( [$level, [$strings]] )
374       Mail::Box::Message::Destructed->log( [$level, [$strings]] )
375           Inherited, see "Error handling" in Mail::Reporter
376
377       $obj->logPriority($level)
378       Mail::Box::Message::Destructed->logPriority($level)
379           Inherited, see "Error handling" in Mail::Reporter
380
381       $obj->logSettings()
382           Inherited, see "Error handling" in Mail::Reporter
383
384       $obj->notImplemented()
385           Inherited, see "Error handling" in Mail::Reporter
386
387       $obj->report( [$level] )
388           Inherited, see "Error handling" in Mail::Reporter
389
390       $obj->reportAll( [$level] )
391           Inherited, see "Error handling" in Mail::Reporter
392
393       $obj->shortSize( [$value] )
394       Mail::Box::Message::Destructed->shortSize( [$value] )
395           Inherited, see "Error handling" in Mail::Message
396
397       $obj->shortString()
398           Inherited, see "Error handling" in Mail::Message
399
400       $obj->trace( [$level] )
401           Inherited, see "Error handling" in Mail::Reporter
402
403       $obj->warnings()
404           Inherited, see "Error handling" in Mail::Reporter
405
406   Cleanup
407       Extends "Cleanup" in Mail::Box::Message.
408
409       $obj->DESTROY()
410           Inherited, see "Cleanup" in Mail::Reporter
411
412       $obj->destruct()
413           Inherited, see "Cleanup" in Mail::Box::Message
414

DETAILS

416       Extends "DETAILS" in Mail::Box::Message.
417

DIAGNOSTICS

419       Error: Cannot coerce a (class) into destruction
420           Only real Mail::Box::Message objects can get destructed into
421           Mail::Box::Message::Destructed objects.  Mail::Message free their
422           memory immediately when the last reference is lost.
423
424       Error: Cannot include forward source as $include.
425           Unknown alternative for the forward(include).  Valid choices are
426           "NO", "INLINE", "ATTACH", and "ENCAPSULATE".
427
428       Error: Cannot include reply source as $include.
429           Unknown alternative for the "include" option of reply().  Valid
430           choices are "NO", "INLINE", and "ATTACH".
431
432       Error: Destructed message has no labels except 'deleted'
433       Error: Destructed messages can not be undeleted
434           Once a message is destructed, it can not be revived.  Destruction
435           is an optimization in memory usage: if you need an undelete
436           functionality, then you can not use Mail::Box::Message::destruct().
437
438       Error: Method bounce requires To, Cc, or Bcc
439           The message bounce() method forwards a received message off to
440           someone else without modification; you must specified it's new
441           destination.  If you have the urge not to specify any destination,
442           you probably are looking for reply(). When you wish to modify the
443           content, use forward().
444
445       Error: Method forwardAttach requires a preamble
446       Error: Method forwardEncapsulate requires a preamble
447       Error: No address to create forwarded to.
448           If a forward message is created, a destination address must be
449           specified.
450
451       Error: No default mailer found to send message.
452           The message send() mechanism had not enough information to
453           automatically find a mail transfer agent to sent this message.
454           Specify a mailer explicitly using the "via" options.
455
456       Error: No rebuild rule $name defined.
457       Error: Only build() Mail::Message's; they are not in a folder yet
458           You may wish to construct a message to be stored in a some kind of
459           folder, but you need to do that in two steps.  First, create a
460           normal Mail::Message, and then add it to the folder.  During this
461           Mail::Box::addMessage() process, the message will get coerce()-d
462           into the right message type, adding storage information and the
463           like.
464
465       Error: Package $package does not implement $method.
466           Fatal error: the specific package (or one of its superclasses) does
467           not implement this method where it should. This message means that
468           some other related classes do implement this method however the
469           class at hand does not.  Probably you should investigate this and
470           probably inform the author of the package.
471
472       Error: You cannot instantiate a destructed message
473           You cannot instantiate a destructed message object directly.
474           Destruction is done by calling Mail::Box::Message::destruct() on
475           any existing folder message.
476
477       Error: You cannot take the head/body of a destructed message
478           The message originated from a folder, but its memory has been
479           freed-up forcefully by means of Mail::Box::Message::destruct().
480           Apparently, your program still tries to get to the header or body
481           data after this destruction, which is not possible.
482

LICENSE

488       Copyrights 2001-2020 by [Mark Overmeer]. For other contributors see
489       ChangeLog.
490
491       This program is free software; you can redistribute it and/or modify it
492       under the same terms as Perl itself.  See http://dev.perl.org/licenses/
493
494
495
496perl v5.36.0                      2023-01-20 Mail::Box::Message::Destructed(3)