1MIME::Entity(3)       User Contributed Perl Documentation      MIME::Entity(3)
2
3
4

NAME

6       MIME::Entity - class for parsed-and-decoded MIME message
7

SYNOPSIS

9       Before reading further, you should see MIME::Tools to make sure that
10       you understand where this module fits into the grand scheme of things.
11       Go on, do it now.  I'll wait.
12
13       Ready?  Ok...
14
15           ### Create an entity:
16           $top = MIME::Entity->build(From    => 'me@myhost.com',
17                                      To      => 'you@yourhost.com',
18                                      Subject => "Hello, nurse!",
19                                      Data    => \@my_message);
20
21           ### Attach stuff to it:
22           $top->attach(Path     => $gif_path,
23                        Type     => "image/gif",
24                        Encoding => "base64");
25
26           ### Sign it:
27           $top->sign;
28
29           ### Output it:
30           $top->print(\*STDOUT);
31

DESCRIPTION

33       A subclass of Mail::Internet.
34
35       This package provides a class for representing MIME message entities,
36       as specified in RFCs 2045, 2046, 2047, 2048 and 2049.
37

EXAMPLES

39   Construction examples
40       Create a document for an ordinary 7-bit ASCII text file (lots of stuff
41       is defaulted for us):
42
43           $ent = MIME::Entity->build(Path=>"english-msg.txt");
44
45       Create a document for a text file with 8-bit (Latin-1) characters:
46
47           $ent = MIME::Entity->build(Path     =>"french-msg.txt",
48                                      Encoding =>"quoted-printable",
49                                      From     =>'jean.luc@inria.fr',
50                                      Subject  =>"C'est bon!");
51
52       Create a document for a GIF file (the description is completely
53       optional; note that we have to specify content-type and encoding since
54       they're not the default values):
55
56           $ent = MIME::Entity->build(Description => "A pretty picture",
57                                      Path        => "./docs/mime-sm.gif",
58                                      Type        => "image/gif",
59                                      Encoding    => "base64");
60
61       Create a document that you already have the text for, using "Data":
62
63           $ent = MIME::Entity->build(Type        => "text/plain",
64                                      Encoding    => "quoted-printable",
65                                      Data        => ["First line.\n",
66                                                     "Second line.\n",
67                                                     "Last line.\n"]);
68
69       Create a multipart message, with the entire structure given explicitly:
70
71           ### Create the top-level, and set up the mail headers:
72           $top = MIME::Entity->build(Type     => "multipart/mixed",
73                                      From     => 'me@myhost.com',
74                                      To       => 'you@yourhost.com',
75                                      Subject  => "Hello, nurse!");
76
77           ### Attachment #1: a simple text document:
78           $top->attach(Path=>"./testin/short.txt");
79
80           ### Attachment #2: a GIF file:
81           $top->attach(Path        => "./docs/mime-sm.gif",
82                        Type        => "image/gif",
83                        Encoding    => "base64");
84
85           ### Attachment #3: text we'll create with text we have on-hand:
86           $top->attach(Data => $contents);
87
88       Suppose you don't know ahead of time that you'll have attachments?  No
89       problem: you can "attach" to singleparts as well:
90
91           $top = MIME::Entity->build(From    => 'me@myhost.com',
92                                      To      => 'you@yourhost.com',
93                                      Subject => "Hello, nurse!",
94                                      Data    => \@my_message);
95           if ($GIF_path) {
96               $top->attach(Path     => $GIF_path,
97                            Type     => 'image/gif');
98           }
99
100       Copy an entity (headers, parts... everything but external body data):
101
102           my $deepcopy = $top->dup;
103
104   Access examples
105           ### Get the head, a MIME::Head:
106           $head = $ent->head;
107
108           ### Get the body, as a MIME::Body;
109           $bodyh = $ent->bodyhandle;
110
111           ### Get the intended MIME type (as declared in the header):
112           $type = $ent->mime_type;
113
114           ### Get the effective MIME type (in case decoding failed):
115           $eff_type = $ent->effective_type;
116
117           ### Get preamble, parts, and epilogue:
118           $preamble   = $ent->preamble;          ### ref to array of lines
119           $num_parts  = $ent->parts;
120           $first_part = $ent->parts(0);          ### an entity
121           $epilogue   = $ent->epilogue;          ### ref to array of lines
122
123   Manipulation examples
124       Muck about with the body data:
125
126           ### Read the (unencoded) body data:
127           if ($io = $ent->open("r")) {
128               while (defined($_ = $io->getline)) { print $_ }
129               $io->close;
130           }
131
132           ### Write the (unencoded) body data:
133           if ($io = $ent->open("w")) {
134               foreach (@lines) { $io->print($_) }
135               $io->close;
136           }
137
138           ### Delete the files for any external (on-disk) data:
139           $ent->purge;
140
141       Muck about with the signature:
142
143           ### Sign it (automatically removes any existing signature):
144           $top->sign(File=>"$ENV{HOME}/.signature");
145
146           ### Remove any signature within 15 lines of the end:
147           $top->remove_sig(15);
148
149       Muck about with the headers:
150
151           ### Compute content-lengths for singleparts based on bodies:
152           ###   (Do this right before you print!)
153           $entity->sync_headers(Length=>'COMPUTE');
154
155       Muck about with the structure:
156
157           ### If a 0- or 1-part multipart, collapse to a singlepart:
158           $top->make_singlepart;
159
160           ### If a singlepart, inflate to a multipart with 1 part:
161           $top->make_multipart;
162
163       Delete parts:
164
165           ### Delete some parts of a multipart message:
166           my @keep = grep { keep_part($_) } $msg->parts;
167           $msg->parts(\@keep);
168
169   Output examples
170       Print to filehandles:
171
172           ### Print the entire message:
173           $top->print(\*STDOUT);
174
175           ### Print just the header:
176           $top->print_header(\*STDOUT);
177
178           ### Print just the (encoded) body... includes parts as well!
179           $top->print_body(\*STDOUT);
180
181       Stringify... note that "stringify_xx" can also be written
182       "xx_as_string"; the methods are synonymous, and neither form will be
183       deprecated:
184
185           ### Stringify the entire message:
186           print $top->stringify;              ### or $top->as_string
187
188           ### Stringify just the header:
189           print $top->stringify_header;       ### or $top->header_as_string
190
191           ### Stringify just the (encoded) body... includes parts as well!
192           print $top->stringify_body;         ### or $top->body_as_string
193
194       Debug:
195
196           ### Output debugging info:
197           $entity->dump_skeleton(\*STDERR);
198

PUBLIC INTERFACE

200   Construction
201       new [SOURCE]
202           Class method.  Create a new, empty MIME entity.  Basically, this
203           uses the Mail::Internet constructor...
204
205           If SOURCE is an ARRAYREF, it is assumed to be an array of lines
206           that will be used to create both the header and an in-core body.
207
208           Else, if SOURCE is defined, it is assumed to be a filehandle from
209           which the header and in-core body is to be read.
210
211           Note: in either case, the body will not be parsed: merely read!
212
213       add_part ENTITY, [OFFSET]
214           Instance method.  Assuming we are a multipart message, add a body
215           part (a MIME::Entity) to the array of body parts.  Returns the part
216           that was just added.
217
218           If OFFSET is positive, the new part is added at that offset from
219           the beginning of the array of parts.  If it is negative, it counts
220           from the end of the array.  (An INDEX of -1 will place the new part
221           at the very end of the array, -2 will place it as the penultimate
222           item in the array, etc.)  If OFFSET is not given, the new part is
223           added to the end of the array.  Thanks to Jason L Tibbitts III for
224           providing support for OFFSET.
225
226           Warning: in general, you only want to attach parts to entities with
227           a content-type of "multipart/*").
228
229       attach PARAMHASH
230           Instance method.  The real quick-and-easy way to create multipart
231           messages.  The PARAMHASH is used to "build" a new entity; this
232           method is basically equivalent to:
233
234               $entity->add_part(ref($entity)->build(PARAMHASH, Top=>0));
235
236           Note: normally, you attach to multipart entities; however, if you
237           attach something to a singlepart (like attaching a GIF to a text
238           message), the singlepart will be coerced into a multipart
239           automatically.
240
241       build PARAMHASH
242           Class/instance method.  A quick-and-easy catch-all way to create an
243           entity.  Use it like this to build a "normal" single-part entity:
244
245              $ent = MIME::Entity->build(Type     => "image/gif",
246                                         Encoding => "base64",
247                                         Path     => "/path/to/xyz12345.gif",
248                                         Filename => "saveme.gif",
249                                         Disposition => "attachment");
250
251           And like this to build a "multipart" entity:
252
253              $ent = MIME::Entity->build(Type     => "multipart/mixed",
254                                         Boundary => "---1234567");
255
256           A minimal MIME header will be created.  If you want to add or
257           modify any header fields afterwards, you can of course do so via
258           the underlying head object... but hey, there's now a prettier
259           syntax!
260
261              $ent = MIME::Entity->build(Type          =>"multipart/mixed",
262                                         From          => $myaddr,
263                                         Subject       => "Hi!",
264                                         'X-Certified' => ['SINED',
265                                                           'SEELED',
266                                                           'DELIVERED']);
267
268           Normally, an "X-Mailer" header field is output which contains this
269           toolkit's name and version (plus this module's RCS version).  This
270           will allow any bad MIME we generate to be traced back to us.  You
271           can of course overwrite that header with your own:
272
273              $ent = MIME::Entity->build(Type        => "multipart/mixed",
274                                         'X-Mailer'  => "myprog 1.1");
275
276           Or remove it entirely:
277
278              $ent = MIME::Entity->build(Type       => "multipart/mixed",
279                                         'X-Mailer' => undef);
280
281           OK, enough hype.  The parameters are:
282
283           (FIELDNAME)
284               Any field you want placed in the message header, taken from the
285               standard list of header fields (you don't need to worry about
286               case):
287
288                   Bcc           Encrypted     Received      Sender
289                   Cc            From          References    Subject
290                   Comments      Keywords      Reply-To      To
291                   Content-*     Message-ID    Resent-*      X-*
292                   Date          MIME-Version  Return-Path
293                                 Organization
294
295               To give experienced users some veto power, these fields will be
296               set after the ones I set... so be careful: don't set any MIME
297               fields (like "Content-type") unless you know what you're doing!
298
299               To specify a fieldname that's not in the above list, even one
300               that's identical to an option below, just give it with a
301               trailing ":", like "My-field:".  When in doubt, that always
302               signals a mail field (and it sort of looks like one too).
303
304           Boundary
305               Multipart entities only. Optional.  The boundary string.  As
306               per RFC-2046, it must consist only of the characters
307               "[0-9a-zA-Z'()+_,-./:=?]" and space (you'll be warned, and your
308               boundary will be ignored, if this is not the case).  If you
309               omit this, a random string will be chosen... which is probably
310               safer.
311
312           Charset
313               Optional.  The character set.
314
315           Data
316               Single-part entities only. Optional.  An alternative to Path
317               (q.v.): the actual data, either as a scalar or an array
318               reference (whose elements are joined together to make the
319               actual scalar).  The body is opened on the data using
320               MIME::Body::InCore.
321
322           Description
323               Optional.  The text of the content-description.  If you don't
324               specify it, the field is not put in the header.
325
326           Disposition
327               Optional.  The basic content-disposition ("attachment" or
328               "inline").  If you don't specify it, it defaults to "inline"
329               for backwards compatibility.  Thanks to Kurt Freytag for
330               suggesting this feature.
331
332           Encoding
333               Optional.  The content-transfer-encoding.  If you don't specify
334               it, a reasonable default is put in.  You can also give the
335               special value '-SUGGEST', to have it chosen for you in a heavy-
336               duty fashion which scans the data itself.
337
338           Filename
339               Single-part entities only. Optional.  The recommended filename.
340               Overrides any name extracted from "Path".  The information is
341               stored both the deprecated (content-type) and preferred
342               (content-disposition) locations.  If you explicitly want to
343               avoid a recommended filename (even when Path is used), supply
344               this as empty or undef.
345
346           Id  Optional.  Set the content-id.
347
348           Path
349               Single-part entities only. Optional.  The path to the file to
350               attach.  The body is opened on that file using
351               MIME::Body::File.
352
353           Top Optional.  Is this a top-level entity?  If so, it must sport a
354               MIME-Version.  The default is true.  (NB: look at how
355               "attach()" uses it.)
356
357           Type
358               Optional.  The basic content-type ("text/plain", etc.).  If you
359               don't specify it, it defaults to "text/plain" as per RFC 2045.
360               Do yourself a favor: put it in.
361
362       dup Instance method.  Duplicate the entity.  Does a deep, recursive
363           copy, but beware: external data in bodyhandles is not copied to new
364           files!  Changing the data in one entity's data file, or purging
365           that entity, will affect its duplicate.  Entities with in-core data
366           probably need not worry.
367
368   Access
369       body [VALUE]
370           Instance method.  Get the encoded (transport-ready) body, as an
371           array of lines.  Returns an array reference.  Each array entry is a
372           newline-terminated line.
373
374           This is a read-only data structure: changing its contents will have
375           no effect.  Its contents are identical to what is printed by
376           print_body().
377
378           Provided for compatibility with Mail::Internet, so that methods
379           like "smtpsend()" will work.  Note however that if VALUE is given,
380           a fatal exception is thrown, since you cannot use this method to
381           set the lines of the encoded message.
382
383           If you want the raw (unencoded) body data, use the bodyhandle()
384           method to get and use a MIME::Body.  The content-type of the entity
385           will tell you whether that body is best read as text (via
386           getline()) or raw data (via read()).
387
388       bodyhandle [VALUE]
389           Instance method.  Get or set an abstract object representing the
390           body of the message.  The body holds the decoded message data.
391
392           Note that not all entities have bodies!  An entity will have either
393           a body or parts: not both.  This method will only return an object
394           if this entity can have a body; otherwise, it will return
395           undefined.  Whether-or-not a given entity can have a body is
396           determined by (1) its content type, and (2) whether-or-not the
397           parser was told to extract nested messages:
398
399               Type:        | Extract nested? | bodyhandle() | parts()
400               -----------------------------------------------------------------------
401               multipart/*  | -               | undef        | 0 or more MIME::Entity
402               message/*    | true            | undef        | 0 or 1 MIME::Entity
403               message/*    | false           | MIME::Body   | empty list
404               (other)      | -               | MIME::Body   | empty list
405
406           If "VALUE" is not given, the current bodyhandle is returned, or
407           undef if the entity cannot have a body.
408
409           If "VALUE" is given, the bodyhandle is set to the new value, and
410           the previous value is returned.
411
412           See "parts" for more info.
413
414       effective_type [MIMETYPE]
415           Instance method.  Set/get the effective MIME type of this entity.
416           This is usually identical to the actual (or defaulted) MIME type,
417           but in some cases it differs.  For example, from RFC-2045:
418
419              Any entity with an unrecognized Content-Transfer-Encoding must be
420              treated as if it has a Content-Type of "application/octet-stream",
421              regardless of what the Content-Type header field actually says.
422
423           Why? because if we can't decode the message, then we have to take
424           the bytes as-is, in their (unrecognized) encoded form.  So the
425           message ceases to be a "text/foobar" and becomes a bunch of
426           undecipherable bytes -- in other words, an
427           "application/octet-stream".
428
429           Such an entity, if parsed, would have its effective_type() set to
430           "application/octet_stream", although the mime_type() and the
431           contents of the header would remain the same.
432
433           If there is no effective type, the method just returns what
434           mime_type() would.
435
436           Warning: the effective type is "sticky"; once set, that
437           effective_type() will always be returned even if the conditions
438           that necessitated setting the effective type become no longer true.
439
440       epilogue [LINES]
441           Instance method.  Get/set the text of the epilogue, as an array of
442           newline-terminated LINES.  Returns a reference to the array of
443           lines, or undef if no epilogue exists.
444
445           If there is a epilogue, it is output when printing this entity;
446           otherwise, a default epilogue is used.  Setting the epilogue to
447           undef (not []!) causes it to fallback to the default.
448
449       head [VALUE]
450           Instance method.  Get/set the head.
451
452           If there is no VALUE given, returns the current head.  If none
453           exists, an empty instance of MIME::Head is created, set, and
454           returned.
455
456           Note: This is a patch over a problem in Mail::Internet, which
457           doesn't provide a method for setting the head to some given object.
458
459       is_multipart
460           Instance method.  Does this entity's effective MIME type indicate
461           that it's a multipart entity?  Returns undef (false) if the answer
462           couldn't be determined, 0 (false) if it was determined to be false,
463           and true otherwise.  Note that this says nothing about whether or
464           not parts were extracted.
465
466           NOTE: we switched to effective_type so that multiparts with bad or
467           missing boundaries could be coerced to an effective type of
468           "application/x-unparseable-multipart".
469
470       mime_type
471           Instance method.  A purely-for-convenience method.  This simply
472           relays the request to the associated MIME::Head object.  If there
473           is no head, returns undef in a scalar context and the empty array
474           in a list context.
475
476           Before you use this, consider using effective_type() instead,
477           especially if you obtained the entity from a MIME::Parser.
478
479       open READWRITE
480           Instance method.  A purely-for-convenience method.  This simply
481           relays the request to the associated MIME::Body object (see
482           MIME::Body::open()).  READWRITE is either 'r' (open for read) or
483           'w' (open for write).
484
485           If there is no body, returns false.
486
487       parts
488       parts INDEX
489       parts ARRAYREF
490           Instance method.  Return the MIME::Entity objects which are the sub
491           parts of this entity (if any).
492
493           If no argument is given, returns the array of all sub parts,
494           returning the empty array if there are none (e.g., if this is a
495           single part message, or a degenerate multipart).  In a scalar
496           context, this returns you the number of parts.
497
498           If an integer INDEX is given, return the INDEXed part, or undef if
499           it doesn't exist.
500
501           If an ARRAYREF to an array of parts is given, then this method sets
502           the parts to a copy of that array, and returns the parts.  This can
503           be used to delete parts, as follows:
504
505               ### Delete some parts of a multipart message:
506               $msg->parts([ grep { keep_part($_) } $msg->parts ]);
507
508           Note: for multipart messages, the preamble and epilogue are not
509           considered parts.  If you need them, use the "preamble()" and
510           "epilogue()" methods.
511
512           Note: there are ways of parsing with a MIME::Parser which cause
513           certain message parts (such as those of type "message/rfc822") to
514           be "reparsed" into pseudo-multipart entities.  You should read the
515           documentation for those options carefully: it is possible for a
516           diddled entity to not be multipart, but still have parts attached
517           to it!
518
519           See "bodyhandle" for a discussion of parts vs. bodies.
520
521       parts_DFS
522           Instance method.  Return the list of all MIME::Entity objects
523           included in the entity, starting with the entity itself, in depth-
524           first-search order.  If the entity has no parts, it alone will be
525           returned.
526
527           Thanks to Xavier Armengou for suggesting this method.
528
529       preamble [LINES]
530           Instance method.  Get/set the text of the preamble, as an array of
531           newline-terminated LINES.  Returns a reference to the array of
532           lines, or undef if no preamble exists (e.g., if this is a single-
533           part entity).
534
535           If there is a preamble, it is output when printing this entity;
536           otherwise, a default preamble is used.  Setting the preamble to
537           undef (not []!) causes it to fallback to the default.
538
539   Manipulation
540       make_multipart [SUBTYPE], OPTSHASH...
541           Instance method.  Force the entity to be a multipart, if it isn't
542           already.  We do this by replacing the original [singlepart] entity
543           with a new multipart that has the same non-MIME headers ("From",
544           "Subject", etc.), but all-new MIME headers ("Content-type", etc.).
545           We then create a copy of the original singlepart, strip out the
546           non-MIME headers from that, and make it a part of the new
547           multipart.  So this:
548
549               From: me
550               To: you
551               Content-type: text/plain
552               Content-length: 12
553
554               Hello there!
555
556           Becomes something like this:
557
558               From: me
559               To: you
560               Content-type: multipart/mixed; boundary="----abc----"
561
562               ------abc----
563               Content-type: text/plain
564               Content-length: 12
565
566               Hello there!
567               ------abc------
568
569           The actual type of the new top-level multipart will be
570           "multipart/SUBTYPE" (default SUBTYPE is "mixed").
571
572           Returns 'DONE'    if we really did inflate a singlepart to a
573           multipart.  Returns 'ALREADY' (and does nothing) if entity is
574           already multipart and Force was not chosen.
575
576           If OPTSHASH contains Force=>1, then we always bump the top-level's
577           content and content-headers down to a subpart of this entity, even
578           if this entity is already a multipart.  This is apparently of use
579           to people who are tweaking messages after parsing them.
580
581       make_singlepart
582           Instance method.  If the entity is a multipart message with one
583           part, this tries hard to rewrite it as a singlepart, by replacing
584           the content (and content headers) of the top level with those of
585           the part.  Also crunches 0-part multiparts into singleparts.
586
587           Returns 'DONE'    if we really did collapse a multipart to a
588           singlepart.  Returns 'ALREADY' (and does nothing) if entity is
589           already a singlepart.  Returns '0'       (and does nothing) if it
590           can't be made into a singlepart.
591
592       purge
593           Instance method.  Recursively purge (e.g., unlink) all external
594           (e.g., on-disk) body parts in this message.  See
595           MIME::Body::purge() for details.
596
597           Note: this does not delete the directories that those body parts
598           are contained in; only the actual message data files are deleted.
599           This is because some parsers may be customized to create
600           intermediate directories while others are not, and it's impossible
601           for this class to know what directories are safe to remove.  Only
602           your application program truly knows that.
603
604           If you really want to "clean everything up", one good way is to use
605           "MIME::Parser::file_under()", and then do this before parsing your
606           next message:
607
608               $parser->filer->purge();
609
610           I wouldn't attempt to read those body files after you do this, for
611           obvious reasons.  As of MIME-tools 4.x, each body's path is
612           undefined after this operation.  I warned you I might do this;
613           truly I did.
614
615           Thanks to Jason L. Tibbitts III for suggesting this method.
616
617       remove_sig [NLINES]
618           Instance method, override.  Attempts to remove a user's signature
619           from the body of a message.
620
621           It does this by looking for a line matching "/^-- $/" within the
622           last "NLINES" of the message.  If found then that line and all
623           lines after it will be removed. If "NLINES" is not given, a default
624           value of 10 will be used.  This would be of most use in auto-reply
625           scripts.
626
627           For MIME entity, this method is reasonably cautious: it will only
628           attempt to un-sign a message with a content-type of "text/*".
629
630           If you send remove_sig() to a multipart entity, it will relay it to
631           the first part (the others usually being the "attachments").
632
633           Warning: currently slurps the whole message-part into core as an
634           array of lines, so you probably don't want to use this on extremely
635           long messages.
636
637           Returns truth on success, false on error.
638
639       sign PARAMHASH
640           Instance method, override.  Append a signature to the message.  The
641           params are:
642
643           Attach
644               Instead of appending the text, add it to the message as an
645               attachment.  The disposition will be "inline", and the
646               description will indicate that it is a signature.  The default
647               behavior is to append the signature to the text of the message
648               (or the text of its first part if multipart).  MIME-specific;
649               new in this subclass.
650
651           File
652               Use the contents of this file as the signature.  Fatal error if
653               it can't be read.  As per superclass method.
654
655           Force
656               Sign it even if the content-type isn't "text/*".  Useful for
657               non-standard types like "x-foobar", but be careful!  MIME-
658               specific; new in this subclass.
659
660           Remove
661               Normally, we attempt to strip out any existing signature.  If
662               true, this gives us the NLINES parameter of the remove_sig
663               call.  If zero but defined, tells us not to remove any existing
664               signature.  If undefined, removal is done with the default of
665               10 lines.  New in this subclass.
666
667           Signature
668               Use this text as the signature.  You can supply it as either a
669               scalar, or as a ref to an array of newline-terminated scalars.
670               As per superclass method.
671
672           For MIME messages, this method is reasonably cautious: it will only
673           attempt to sign a message with a content-type of "text/*", unless
674           "Force" is specified.
675
676           If you send this message to a multipart entity, it will relay it to
677           the first part (the others usually being the "attachments").
678
679           Warning: currently slurps the whole message-part into core as an
680           array of lines, so you probably don't want to use this on extremely
681           long messages.
682
683           Returns true on success, false otherwise.
684
685       suggest_encoding
686           Instance method.  Based on the effective content type, return a
687           good suggested encoding.
688
689           "text" and "message" types have their bodies scanned line-by-line
690           for 8-bit characters and long lines; lack of either means that the
691           message is 7bit-ok.  Other types are chosen independent of their
692           body:
693
694               Major type:      7bit ok?    Suggested encoding:
695               -----------------------------------------------------------
696               text             yes         7bit
697               text             no          quoted-printable
698               message          yes         7bit
699               message          no          binary
700               multipart        *           binary (in case some parts are bad)
701               image, etc...    *           base64
702
703       sync_headers OPTIONS
704           Instance method.  This method does a variety of activities which
705           ensure that the MIME headers of an entity "tree" are in-synch with
706           the body parts they describe.  It can be as expensive an operation
707           as printing if it involves pre-encoding the body parts; however,
708           the aim is to produce fairly clean MIME.  You will usually only
709           need to invoke this if processing and re-sending MIME from an
710           outside source.
711
712           The OPTIONS is a hash, which describes what is to be done.
713
714           Length
715               One of the "official unofficial" MIME fields is "Content-
716               Length".  Normally, one doesn't care a whit about this field;
717               however, if you are preparing output destined for HTTP, you
718               may.  The value of this option dictates what will be done:
719
720               COMPUTE means to set a "Content-Length" field for every non-
721               multipart part in the entity, and to blank that field out for
722               every multipart part in the entity.
723
724               ERASE means that "Content-Length" fields will all be blanked
725               out.  This is fast, painless, and safe.
726
727               Any false value (the default) means to take no action.
728
729           Nonstandard
730               Any header field beginning with "Content-" is, according to the
731               RFC, a MIME field.  However, some are non-standard, and may
732               cause problems with certain MIME readers which interpret them
733               in different ways.
734
735               ERASE means that all such fields will be blanked out.  This is
736               done before the Length option (q.v.) is examined and acted
737               upon.
738
739               Any false value (the default) means to take no action.
740
741           Returns a true value if everything went okay, a false value
742           otherwise.
743
744       tidy_body
745           Instance method, override.  Currently unimplemented for MIME
746           messages.  Does nothing, returns false.
747
748   Output
749       dump_skeleton [FILEHANDLE]
750           Instance method.  Dump the skeleton of the entity to the given
751           FILEHANDLE, or to the currently-selected one if none given.
752
753           Each entity is output with an appropriate indentation level, the
754           following selection of attributes:
755
756               Content-type: multipart/mixed
757               Effective-type: multipart/mixed
758               Body-file: NONE
759               Subject: Hey there!
760               Num-parts: 2
761
762           This is really just useful for debugging purposes; I make no
763           guarantees about the consistency of the output format over time.
764
765       print [OUTSTREAM]
766           Instance method, override.  Print the entity to the given
767           OUTSTREAM, or to the currently-selected filehandle if none given.
768           OUTSTREAM can be a filehandle, or any object that reponds to a
769           print() message.
770
771           The entity is output as a valid MIME stream!  This means that the
772           header is always output first, and the body data (if any) will be
773           encoded if the header says that it should be.  For example, your
774           output may look like this:
775
776               Subject: Greetings
777               Content-transfer-encoding: base64
778
779               SGkgdGhlcmUhCkJ5ZSB0aGVyZSEK
780
781           If this entity has MIME type "multipart/*", the preamble, parts,
782           and epilogue are all output with appropriate boundaries separating
783           each.  Any bodyhandle is ignored:
784
785               Content-type: multipart/mixed; boundary="*----*"
786               Content-transfer-encoding: 7bit
787
788               [Preamble]
789               --*----*
790               [Entity: Part 0]
791               --*----*
792               [Entity: Part 1]
793               --*----*--
794               [Epilogue]
795
796           If this entity has a single-part MIME type with no attached parts,
797           then we're looking at a normal singlepart entity: the body is
798           output according to the encoding specified by the header.  If no
799           body exists, a warning is output and the body is treated as empty:
800
801               Content-type: image/gif
802               Content-transfer-encoding: base64
803
804               [Encoded body]
805
806           If this entity has a single-part MIME type but it also has parts,
807           then we're probably looking at a "re-parsed" singlepart, usually
808           one of type "message/*" (you can get entities like this if you set
809           the "parse_nested_messages(NEST)" option on the parser to true).
810           In this case, the parts are output with single blank lines
811           separating each, and any bodyhandle is ignored:
812
813               Content-type: message/rfc822
814               Content-transfer-encoding: 7bit
815
816               [Entity: Part 0]
817
818               [Entity: Part 1]
819
820           In all cases, when outputting a "part" of the entity, this method
821           is invoked recursively.
822
823           Note: the output is very likely not going to be identical to any
824           input you parsed to get this entity.  If you're building some sort
825           of email handler, it's up to you to save this information.
826
827       print_body [OUTSTREAM]
828           Instance method, override.  Print the body of the entity to the
829           given OUTSTREAM, or to the currently-selected filehandle if none
830           given.  OUTSTREAM can be a filehandle, or any object that reponds
831           to a print() message.
832
833           The body is output for inclusion in a valid MIME stream; this means
834           that the body data will be encoded if the header says that it
835           should be.
836
837           Note: by "body", we mean "the stuff following the header".  A
838           printed multipart body includes the printed representations of its
839           subparts.
840
841           Note: The body is stored in an un-encoded form; however, the idea
842           is that the transfer encoding is used to determine how it should be
843           output.  This means that the "print()" method is always guaranteed
844           to get you a sendmail-ready stream whose body is consistent with
845           its head.  If you want the raw body data to be output, you can
846           either read it from the bodyhandle yourself, or use:
847
848               $ent->bodyhandle->print($outstream);
849
850           which uses read() calls to extract the information, and thus will
851           work with both text and binary bodies.
852
853           Warning: Please supply an OUTSTREAM.  This override method differs
854           from Mail::Internet's behavior, which outputs to the STDOUT if no
855           filehandle is given: this may lead to confusion.
856
857       print_header [OUTSTREAM]
858           Instance method, inherited.  Output the header to the given
859           OUTSTREAM.  You really should supply the OUTSTREAM.
860
861       stringify
862           Instance method.  Return the entity as a string, exactly as "print"
863           would print it.  The body will be encoded as necessary, and will
864           contain any subparts.  You can also use "as_string()".
865
866       stringify_body
867           Instance method.  Return the encoded message body as a string,
868           exactly as "print_body" would print it.  You can also use
869           "body_as_string()".
870
871           If you want the unencoded body, and you are dealing with a
872           singlepart message (like a "text/plain"), use "bodyhandle()"
873           instead:
874
875               if ($ent->bodyhandle) {
876                   $unencoded_data = $ent->bodyhandle->as_string;
877               }
878               else {
879                   ### this message has no body data (but it might have parts!)
880               }
881
882       stringify_header
883           Instance method.  Return the header as a string, exactly as
884           "print_header" would print it.  You can also use
885           "header_as_string()".
886

NOTES

888   Under the hood
889       A MIME::Entity is composed of the following elements:
890
891       ·   A head, which is a reference to a MIME::Head object containing the
892           header information.
893
894       ·   A bodyhandle, which is a reference to a MIME::Body object
895           containing the decoded body data.  This is only defined if the
896           message is a "singlepart" type:
897
898               application/*
899               audio/*
900               image/*
901               text/*
902               video/*
903
904       ·   An array of parts, where each part is a MIME::Entity object.  The
905           number of parts will only be nonzero if the content-type is not one
906           of the "singlepart" types:
907
908               message/*        (should have exactly one part)
909               multipart/*      (should have one or more parts)
910
911   The "two-body problem"
912       MIME::Entity and Mail::Internet see message bodies differently, and
913       this can cause confusion and some inconvenience.  Sadly, I can't change
914       the behavior of MIME::Entity without breaking lots of code already out
915       there.  But let's open up the floor for a few questions...
916
917       What is the difference between a "message" and an "entity"?
918           A message is the actual data being sent or received; usually this
919           means a stream of newline-terminated lines.  An entity is the
920           representation of a message as an object.
921
922           This means that you get a "message" when you print an "entity" to a
923           filehandle, and you get an "entity" when you parse a message from a
924           filehandle.
925
926       What is a message body?
927           Mail::Internet: The portion of the printed message after the
928           header.
929
930           MIME::Entity: The portion of the printed message after the header.
931
932       How is a message body stored in an entity?
933           Mail::Internet: As an array of lines.
934
935           MIME::Entity: It depends on the content-type of the message.  For
936           "container" types ("multipart/*", "message/*"), we store the
937           contained entities as an array of "parts", accessed via the
938           "parts()" method, where each part is a complete MIME::Entity.  For
939           "singlepart" types ("text/*", "image/*", etc.), the unencoded body
940           data is referenced via a MIME::Body object, accessed via the
941           "bodyhandle()" method:
942
943                                 bodyhandle()   parts()
944               Content-type:     returns:       returns:
945               ------------------------------------------------------------
946               application/*     MIME::Body     empty
947               audio/*           MIME::Body     empty
948               image/*           MIME::Body     empty
949               message/*         undef          MIME::Entity list (usually 1)
950               multipart/*       undef          MIME::Entity list (usually >0)
951               text/*            MIME::Body     empty
952               video/*           MIME::Body     empty
953               x-*/*             MIME::Body     empty
954
955           As a special case, "message/*" is currently ambiguous: depending on
956           the parser, a "message/*" might be treated as a singlepart, with a
957           MIME::Body and no parts.  Use bodyhandle() as the final arbiter.
958
959       What does the body() method return?
960           Mail::Internet: As an array of lines, ready for sending.
961
962           MIME::Entity: As an array of lines, ready for sending.
963
964       What's the best way to get at the body data?
965           Mail::Internet: Use the body() method.
966
967           MIME::Entity: Depends on what you want... the encoded data (as it
968           is transported), or the unencoded data?  Keep reading...
969
970       How do I get the "encoded" body data?
971           Mail::Internet: Use the body() method.
972
973           MIME::Entity: Use the body() method.  You can also use:
974
975               $entity->print_body()
976               $entity->stringify_body()   ### a.k.a. $entity->body_as_string()
977
978       How do I get the "unencoded" body data?
979           Mail::Internet: Use the body() method.
980
981           MIME::Entity: Use the bodyhandle() method!  If bodyhandle() method
982           returns true, then that value is a MIME::Body which can be used to
983           access the data via its open() method.  If bodyhandle() method
984           returns an undefined value, then the entity is probably a
985           "container" that has no real body data of its own (e.g., a
986           "multipart" message): in this case, you should access the
987           components via the parts() method.  Like this:
988
989               if ($bh = $entity->bodyhandle) {
990                   $io = $bh->open;
991                   ...access unencoded data via $io->getline or $io->read...
992                   $io->close;
993               }
994               else {
995                   foreach my $part (@parts) {
996                       ...do something with the part...
997                   }
998               }
999
1000           You can also use:
1001
1002               if ($bh = $entity->bodyhandle) {
1003                   $unencoded_data = $bh->as_string;
1004               }
1005               else {
1006                   ...do stuff with the parts...
1007               }
1008
1009       What does the body() method return?
1010           Mail::Internet: The transport-encoded message body, as an array of
1011           lines.
1012
1013           MIME::Entity: The transport-encoded message body, as an array of
1014           lines.
1015
1016       What does print_body() print?
1017           Mail::Internet: Exactly what body() would return to you.
1018
1019           MIME::Entity: Exactly what body() would return to you.
1020
1021       Say I have an entity which might be either singlepart or multipart. How
1022       do I print out just "the stuff after the header"?
1023           Mail::Internet: Use print_body().
1024
1025           MIME::Entity: Use print_body().
1026
1027       Why is MIME::Entity so different from Mail::Internet?
1028           Because MIME streams are expected to have non-textual data...
1029           possibly, quite a lot of it, such as a tar file.
1030
1031           Because MIME messages can consist of multiple parts, which are
1032           most-easily manipulated as MIME::Entity objects themselves.
1033
1034           Because in the simpler world of Mail::Internet, the data of a
1035           message and its printed representation are identical... and in the
1036           MIME world, they're not.
1037
1038           Because parsing multipart bodies on-the-fly, or formatting
1039           multipart bodies for output, is a non-trivial task.
1040
1041       This is confusing.  Can the two classes be made more compatible?
1042           Not easily; their implementations are necessarily quite different.
1043           Mail::Internet is a simple, efficient way of dealing with a "black
1044           box" mail message... one whose internal data you don't care much
1045           about.  MIME::Entity, in contrast, cares very much about the
1046           message contents: that's its job!
1047
1048   Design issues
1049       Some things just can't be ignored
1050           In multipart messages, the "preamble" is the portion that precedes
1051           the first encapsulation boundary, and the "epilogue" is the portion
1052           that follows the last encapsulation boundary.
1053
1054           According to RFC 2046:
1055
1056               There appears to be room for additional information prior
1057               to the first encapsulation boundary and following the final
1058               boundary.  These areas should generally be left blank, and
1059               implementations must ignore anything that appears before the
1060               first boundary or after the last one.
1061
1062               NOTE: These "preamble" and "epilogue" areas are generally
1063               not used because of the lack of proper typing of these parts
1064               and the lack of clear semantics for handling these areas at
1065               gateways, particularly X.400 gateways.  However, rather than
1066               leaving the preamble area blank, many MIME implementations
1067               have found this to be a convenient place to insert an
1068               explanatory note for recipients who read the message with
1069               pre-MIME software, since such notes will be ignored by
1070               MIME-compliant software.
1071
1072           In the world of standards-and-practices, that's the standard.  Now
1073           for the practice:
1074
1075           Some "MIME" mailers may incorrectly put a "part" in the preamble.
1076           Since we have to parse over the stuff anyway, in the future I may
1077           allow the parser option of creating special MIME::Entity objects
1078           for the preamble and epilogue, with bogus MIME::Head objects.
1079
1080           For now, though, we're MIME-compliant, so I probably won't change
1081           how we work.
1082

SEE ALSO

1084       MIME::Tools, MIME::Head, MIME::Body, MIME::Decoder, Mail::Internet
1085

AUTHOR

1087       Eryq (eryq@zeegee.com), ZeeGee Software Inc (http://www.zeegee.com).
1088       David F. Skoll (dfs@roaringpenguin.com) http://www.roaringpenguin.com
1089
1090       All rights reserved.  This program is free software; you can
1091       redistribute it and/or modify it under the same terms as Perl itself.
1092
1093
1094
1095perl v5.12.0                      2010-04-22                   MIME::Entity(3)
Impressum