Provided by: libmail-imapclient-perl_3.43-1_all bug

NAME

       Mail::IMAPClient::BodyStructure - parse fetched results

SYNOPSIS

         use Mail::IMAPClient;
         use Mail::IMAPClient::BodyStructure;

         my $imap = Mail::IMAPClient->new(
             Server => $server, User => $login, Password => $pass
         );

         $imap->select("INBOX") or die "Could not select INBOX: $@\n";

         my @recent = $imap->search("recent") or die "No recent msgs in INBOX\n";

         foreach my $id (@recent) {
             my $bsdat = $imap->fetch( $id, "bodystructure" );
             my $bso   = Mail::IMAPClient::BodyStructure->new( join("", $imap->History) );
             my $mime  = $bso->bodytype . "/" . $bso->bodysubtype;
             my $parts = map( "\n\t" . $_, $bso->parts );
             print "Msg $id (Content-type: $mime) contains these parts:$parts\n";
         }

DESCRIPTION

       This extension will parse the result of an IMAP FETCH BODYSTRUCTURE command into a perl
       data structure.  It also provides helper methods to help pull information out of the data
       structure.

       This module requires Parse::RecDescent.

Class Methods

       The following class method is available:

   new
       This class method is the constructor method for instantiating new
       Mail::IMAPClient::BodyStructure objects.  The new method accepts one argument, a string
       containing a server response to a FETCH BODYSTRUCTURE directive.

       The module Mail::IMAPClient provides the get_bodystructure convenience method to simplify
       use of this module when starting with just a messages sequence number or unique ID (UID).

Object Methods

       The following object methods are available:

   bodytype
       The bodytype object method requires no arguments.  It returns the bodytype for the message
       whose structure is described by the calling Mail::IMAPClient::Bodystructure object.

   bodysubtype
       The bodysubtype object method requires no arguments.  It returns the bodysubtype for the
       message whose structure is described by the calling Mail::IMAPClient::Bodystructure
       object.

   bodyparms
       The bodyparms object method requires no arguments.  It returns the bodyparms for the
       message whose structure is described by the calling Mail::IMAPClient::Bodystructure
       object.

   bodydisp
       The bodydisp object method requires no arguments.  It returns the bodydisp for the message
       whose structure is described by the calling Mail::IMAPClient::Bodystructure object.

   bodyid
       The bodyid object method requires no arguments.  It returns the bodyid for the message
       whose structure is described by the calling Mail::IMAPClient::Bodystructure object.

   bodydesc
       The bodydesc object method requires no arguments.  It returns the bodydesc for the message
       whose structure is described by the calling Mail::IMAPClient::Bodystructure object.

   bodyenc
       The bodyenc object method requires no arguments.  It returns the bodyenc for the message
       whose structure is described by the calling Mail::IMAPClient::Bodystructure object.

   bodysize
       The bodysize object method requires no arguments.  It returns the bodysize for the message
       whose structure is described by the calling Mail::IMAPClient::Bodystructure object.

   bodylang
       The bodylang object method requires no arguments.  It returns the bodylang for the message
       whose structure is described by the calling Mail::IMAPClient::Bodystructure object.

   bodystructure
       The bodystructure object method requires no arguments.  It returns the bodystructure for
       the message whose structure is described by the calling Mail::IMAPClient::Bodystructure
       object.

   envelopestruct
       The envelopestruct object method requires no arguments.  It returns a
       Mail::IMAPClient::BodyStructure::Envelope object for the message from the calling
       Mail::IMAPClient::Bodystructure object.

   textlines
       The textlines object method requires no arguments.  It returns the textlines for the
       message whose structure is described by the calling Mail::IMAPClient::Bodystructure
       object.

Mail::IMAPClient::BodyStructure::Envelope

       The IMAP standard specifies that output from the IMAP FETCH ENVELOPE command will be an
       RFC2060 envelope structure.  It further specifies that output from the FETCH BODYSTRUCTURE
       command may also contain embedded envelope structures (if, for example, a message's
       subparts contain one or more included messages).  Objects belonging to
       Mail::IMAPClient::BodyStructure::Envelope are Perl representations of these envelope
       structures, which is to say the nested parenthetical lists of RFC2060 translated into a
       Perl datastructure.

       Note that all of the fields relate to the specific part to which they belong.  In other
       words, output from a FETCH nnnn ENVELOPE command (or, in Mail::IMAPClient,
       "$imap-"fetch($msgid,"ENVELOPE")> or "my $env = $imap-"get_envelope($msgid)>) are for the
       message, but fields from within a bodystructure relate to the message subpart and not the
       parent message.

       An envelope structure's Mail::IMAPClient::BodyStructure::Envelope representation is a hash
       of thingies that looks like this:

         {
            subject   => "subject",
            inreplyto => "reference_message_id",
            from      => [ addressStruct1 ],
            messageid => "message_id",
            bcc       => [ addressStruct1, addressStruct2 ],
            date      => "Tue, 09 Jul 2002 14:15:53 -0400",
            replyto   => [ adressStruct1, addressStruct2 ],
            to        => [ adressStruct1, addressStruct2 ],
            sender    => [ adressStruct1 ],
            cc        => [ adressStruct1, addressStruct2 ],
         }

       The ...::Envelope object also has methods for accessing data in the structure. They are:

       date
           Returns the date of the message.

       inreplyto
           Returns the message id of the message to which this message is a reply.

       subject
           Returns the subject of the message.

       messageid
           Returns the message id of the message.

       You can also use the following methods to get addressing information.  Each of these
       methods returns an array of Mail::IMAPClient::BodyStructure::Address objects, which are
       perl data structures representing RFC2060 address structures.  Some of these arrays would
       naturally contain one element (such as from, which normally contains a single "From:"
       address); others will often contain more than one address.  However, because RFC2060
       defines all of these as "lists of address structures", they are all translated into arrays
       of ...::Address objects.

       See the section on Mail::IMAPClient::BodyStructure::Address, below, for alternate (and
       preferred) ways of accessing these data.

       The methods available are:

       bcc Returns an array of blind cc'ed recipients' address structures.  (Don't expect much in
           here unless the message was sent from the mailbox you're poking around in, by the
           way.)

       cc  Returns an array of cc'ed recipients' address structures.

       from
           Returns an array of "From:" address structures--usually just one.

       replyto
           Returns an array of "Reply-to:" address structures.  Once again there is usually just
           one address in the list.

       sender
           Returns an array of senders' address structures--usually just one and usually the same
           as from.

       to  Returns an array of recipients' address structures.

       Each of the methods that returns a list of address structures (i.e. a list of
       Mail::IMAPClient::BodyStructure::Address arrays) also has an analogous method that will
       return a list of E-Mail addresses instead.  The addresses are in the format "personalname
       <mailboxname@hostname>" (see the section on Mail::IMAPClient::BodyStructure::Address,
       below) However, if the personal name is 'NIL' then it is omitted from the address.

       These methods are:

       bcc_addresses
           Returns a list (or an array reference if called in scalar context) of blind cc'ed
           recipients' email addresses.  (Don't expect much in here unless the message was sent
           from the mailbox you're poking around in, by the way.)

       cc_addresses
           Returns a list of cc'ed recipients' email addresses.  If called in a scalar context it
           returns a reference to an array of email addresses.

       from_addresses
           Returns a list of "From:" email addresses.  If called in a scalar context it returns
           the first email address in the list.  (It's usually a list of just one anyway.)

       replyto_addresses
           Returns a list of "Reply-to:" email addresses.  If called in a scalar context it
           returns the first email address in the list.

       sender_addresses
           Returns a list of senders' email addresses.  If called in a scalar context it returns
           the first email address in the list.

       to_addresses
           Returns a list of recipients' email addresses.  If called in a scalar context it
           returns a reference to an array of email addresses.

       Note that context affects the behavior of all of the above methods.

       Those fields that will commonly contain multiple entries (i.e. they are recipients) will
       return an array reference when called in scalar context.  You can use this behavior to
       optimize performance.

       Those fields that will commonly contain just one address (the sender's) will return the
       first (and usually only) address.  You can use this behavior to optimize your development
       time.

Addresses and the Mail::IMAPClient::BodyStructure::Address

       Several components of an envelope structure are address structures.  They are each parsed
       into their own object, Mail::IMAPClient::BodyStructure::Address, which looks like this:

          {
             mailboxname  => 'somebody.special',
             hostname     => 'somplace.weird.com'
             personalname => 'Somebody Special
             sourceroute  => 'NIL'
          }

       RFC2060 specifies that each address component of a bodystructure is a list of address
       structures, so Mail::IMAPClient::BodyStructure parses each of these into an array of
       Mail::IMAPClient::BodyStructure::Address objects.

       Each of these objects has the following methods available to it:

       mailboxname
           Returns the "mailboxname" portion of the address, which is the part to the left of the
           '@' sign.

       hostname
           Returns the "hostname" portion of the address, which is the part to the right of the
           '@' sign.

       personalname
           Returns the "personalname" portion of the address, which is the part of the address
           that's treated like a comment.

       sourceroute
           Returns the "sourceroute" portion of the address, which is typically "NIL".

       Taken together, the parts of an address structure form an address that will look something
       like this:

       "personalname <mailboxname@hostname>"

       Note that because the Mail::IMAPClient::BodyStructure::Address objects come in arrays,
       it's generally easier to use the methods available to
       Mail::IMAPClient::BodyStructure::Envelope to obtain all of the addresses in a particular
       array in one operation.  These methods are provided, however, in case you'd rather do
       things the hard way.  (And also because the aforementioned methods from
       Mail::IMAPClient::BodyStructure::Envelope need them anyway.)

AUTHOR

       Original author: David J. Kernen; Reworked by: Mark Overmeer; Maintained by Phil Pearl.

SEE ALSO

       perl(1), Mail::IMAPClient, Parse::RecDescent, and RFC2060.