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

METHODS

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

DETAILS

DIAGNOSTICS

488       Error: Cannot coerce a (class) into destruction
489
490       Only real Mail::Box::Message objects can get destructed into
491       Mail::Box::Message::Destructed objects.  Mail::Message free their mem‐
492       ory immediately when the last reference is lost.
493
494       Error: Cannot include forward source as $include.
495
496       Unknown alternative for the forward(include).  Valid choices are "NO",
497       "INLINE", "ATTACH", and "ENCAPSULATE".
498
499       Error: Cannot include reply source as $include.
500
501       Unknown alternative for the "include" option of reply().  Valid choices
502       are "NO", "INLINE", and "ATTACH".
503
504       Error: Destructed message has no labels except 'deleted'
505
506       Error: Destructed messages can not be undeleted
507
508       Once a message is destructed, it can not be revived.  Destruction is an
509       optimization in memory usage: if you need an undelete functionality,
510       then you can not use Mail::Box::Message::destruct().
511
512       Error: Method bounce requires To, Cc, or Bcc
513
514       The message bounce() method forwards a received message off to someone
515       else without modification; you must specified it's new destination.  If
516       you have the urge not to specify any destination, you probably are
517       looking for reply(). When you wish to modify the content, use for‐
518       ward().
519
520       Error: Method forwardAttach requires a preamble
521
522       Error: Method forwardEncapsulate requires a preamble
523
524       Error: No address to create forwarded to.
525
526       If a forward message is created, a destination address must be speci‐
527       fied.
528
529       Error: No default mailer found to send message.
530
531       The message send() mechanism had not enough information to automati‐
532       cally find a mail transfer agent to sent this message.  Specify a
533       mailer explicitly using the "via" options.
534
535       Error: No rebuild rule $name defined.
536
537       Error: Only build() Mail::Message's; they are not in a folder yet
538
539       You may wish to construct a message to be stored in a some kind of
540       folder, but you need to do that in two steps.  First, create a normal
541       Mail::Message, and then add it to the folder.  During this
542       Mail::Box::addMessage() process, the message will get coerce()-d into
543       the right message type, adding storage information and the like.
544
545       Error: Package $package does not implement $method.
546
547       Fatal error: the specific package (or one of its superclasses) does not
548       implement this method where it should. This message means that some
549       other related classes do implement this method however the class at
550       hand does not.  Probably you should investigate this and probably
551       inform the author of the package.
552
553       Error: You cannot instantiate a destructed message
554
555       You cannot instantiate a destructed message object directly.  Destruc‐
556       tion is done by calling Mail::Box::Message::destruct() on any existing
557       folder message.
558
559       Error: You cannot take the head/body of a destructed message
560
561       The message originated from a folder, but its memory has been freed-up
562       forcefully by means of Mail::Box::Message::destruct().  Apparently,
563       your program still tries to get to the header or body data after this
564       destruction, which is not possible.
565

LICENSE

571       Copyrights 2001-2007 by Mark Overmeer.For other contributors see
572       ChangeLog.
573
574       This program is free software; you can redistribute it and/or modify it
575       under the same terms as Perl itself.  See
576       http://www.perl.com/perl/misc/Artistic.html
577
578
579
580perl v5.8.8                       2007-03-25 Mail::Box::Message::Destructed(3)