/ 
Mail-Box-2.002
River stage one • 8 direct dependents • 8 total dependents
/ Mail::Message::Body::Multipart

NAME

Mail::Message::Body::Multipart - body of a message with attachments

CLASS HIERARCHY

Mail::Message::Body::Multipart
is a Mail::Message::Body + ::Construct + ::Encode
is a Mail::Reporter

SYNOPSIS

See Mail::Message::Body, plus

if($body->isMultipart) {
   my @attachments = $body->parts;
   my $attachment3 = $body->part(2);
   my $before      = $body->preamble;
   my $after       = $body->epiloque;
   my $removed     = $body->removePart(1);
}

DESCRIPTION

READ Mail::Message::Body FIRST. This manual-page only describes the extentions to the default body functionality.

The body (content) of a message can be stored in various ways. In this manual-page you find the description of extra functionality you have when a message contains attachments (parts).

METHOD INDEX

The general methods for Mail::Message::Body::Multipart objects:

     attach MESSAGES|BODIES           MMB message [MESSAGE]
     boundary [STRING]                MMB mimeType
MMBE check                            MMB modified [BOOL]
 MMB checked [BOOLEAN]                    new OPTIONS
MMBC concatenate COMPONENTS           MMB nrLines
 MMB decoded OPTIONS                      part INDEX
 MMB disposition [STRING|FIELD]           parts
     encode OPTIONS                       preamble
MMBE encoded                          MMB print [FILE]
     epilogue                         MMB reply OPTIONS
  MR errors                            MR report [LEVEL]
 MMB file                              MR reportAll [LEVEL]
MMBC foreachLine CODE                 MMB size
MMBE isBinary                         MMB string
 MMB isDelayed                            stripSignature OPTIONS
 MMB isMultipart                       MR trace [LEVEL]
 MMB lines                            MMB transferEncoding [STRING|FI...
  MR log [LEVEL [,STRINGS]]           MMB type

The extra methods for extension writers:

  MR AUTOLOAD                         MMB load
  MR DESTROY                           MR logPriority LEVEL
MMBE addTransferEncHandler NAME,...    MR logSettings
 MMB clone                            MMB moveLocation [DISTANCE]
 MMB fileLocation                      MR notImplemented
MMBE getTransferEncHandler TYPE       MMB read PARSER, HEAD, BODYTYPE...
  MR inGlobalDestruction             MMBE unify BODY

Methods prefixed with an abbreviation are described in the following manual-pages:

  MR = L<Mail::Reporter>
 MMB = L<Mail::Message::Body>
MMBC = L<Mail::Message::Body::Construct>
MMBE = L<Mail::Message::Body::Encode>

METHODS

new OPTIONS
OPTION      DESCRIBED IN                   DEFAULT
based_on    Mail::Message::Body            undef
boundary    Mail::Message::Body::Multipart undef
charset     Mail::Message::Body            'us-ascii'
data        Mail::Message::Body            undef
disposition Mail::Message::Body            undef
epilogue    Mail::Message::Body::Multipart undef
log         Mail::Reporter                 'WARNINGS'
message     Mail::Message::Body            undef
mime_type   Mail::Message::Body            'multipart/mixed'
modified    Mail::Message::Body            0
parts       Mail::Message::Body::Multipart undef
preamble    Mail::Message::Body::Multipart undef
trace       Mail::Reporter                 'WARNINGS'
transfer_encoding Mail::Message::Body      'NONE'

  • boundary => STRING

    Seperatory to be used between parts of the message. This seperator must be unique in case the message contains nested multiparts (which are not unusual). If <undef>, a nice unique boundary will be generated.

  • epilogue => BODY

    The text which is included in the main body after the final boundary. This is usually empty, and has no meaning.

  • parts => ARRAY-OF-(MESSAGES|BODIES)

    Specifies an initial list of parts in this body. These may be full MESSAGES, or BODIES which transformed into messages before use. Each message is coerced into a Mail::Message::Part object.

    MIME::Entity and Mail::Internet objects are acceptable in the list, because they are coerceable into Mail::Message::Part's. Values of undef will be skipped silently.

  • preamble => BODY

    The text which is included in the body before the first part. It is common use to include a text to warn the user that the message is a multipart. However, this was useful in earlier days: most mail agents are very capable in warning the user themselves.

Example:

my $intro = Mail::Message::Body->new(data => ['part one']);
my $pgp   = Mail::Message::Body->new(data => ['part three']);

my $body  = Mail::Message::Body::Multipart->new
  ( boundary => time . '--it-s-mine'
  , parts    => [ $intro, $folder->message(3)->decoded, $pgp ]
  );
encode OPTIONS

Encode the body. An encode on a multipart body is recursive into each part. New bodies will be created if any of the parts is encoded.

OPTION            DESCRIBED IN         DEFAULT
charset           Mail::Message::Body  undef
mime_type         Mail::Message::Body  undef
transfer_encoding Mail::Message::Body  undef
preamble

Returns the preamble (the text before the first message part --attachment), The preamble is stored in a BODY object, and its encoding is derived from the multipart header.

epilogue

Returns the epilogue (the text after the last message part --attachment), The preamble is stored in a BODY object, and its encoding is derived from the multipart header.

parts

In LIST context, the current list of parts (attachments) is returned, In SCALAR context the length of the list is returned, so the number of parts for this multiparted body. This is normal behavior of Perl.

Examples:

print "Number of attachments: ", scalar $message->body->parts;

foreach my $part ($message->body->parts) {
    print "Type: ", $part->get('Content-Type');
}
part INDEX

Returns only the part with the specified INDEX. You may use a negative value here, which counts from the back in the list.

Example:

$message->body->part(2)->print;
boundary [STRING]

Returns the boundary which is used to separate the parts in this body. If none was read from file, then one will be assigned. With STRING you explicitly set the boundary to be used.

attach MESSAGES|BODIES

Attach a list of MESSAGES to this multipart. A new body is returned. When you specify BODIES, they will first be translated into real messages. MIME::Entity and Mail::Internet objects may be specified too. In any case, the parts will be coerced into Mail::Message::Part's.

stripSignature OPTIONS

Removes all parts which contains data usually defined as being signature. The MIME::Type module provides this knowledge. A new multipart is returned, containing the remaining parts. No OPTIONS are defined yet, although some may be specified, because this method overrules the stripSignature method for normal bodies.

METHODS for extension writers

SEE ALSO

Mail::Box-Overview

AUTHOR

Mark Overmeer (mailbox@overmeer.net). All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

VERSION

This code is beta, version 2.00_20.

Copyright (c) 2001 Mark Overmeer. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.