GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  MAIL::IMAPCLIENT::BODYSTRUCTURE (3)

.ds Aq ’

NAME

Mail::IMAPClient::BodyStructure - parse fetched results

CONTENTS

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 <B>newB> method accepts one argument, a string containing a server response to a FETCH BODYSTRUCTURE directive.

The module <B>Mail::IMAPClientB> provides the <B>get_bodystructureB> 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 <B>bodytypeB> object method requires no arguments. It returns the bodytype for the message whose structure is described by the calling <B>Mail::IMAPClient::BodystructureB> object.

    bodysubtype

The <B>bodysubtypeB> object method requires no arguments. It returns the bodysubtype for the message whose structure is described by the calling <B>Mail::IMAPClient::BodystructureB> object.

    bodyparms

The <B>bodyparmsB> object method requires no arguments. It returns the bodyparms for the message whose structure is described by the calling <B>Mail::IMAPClient::BodystructureB> object.

    bodydisp

The <B>bodydispB> object method requires no arguments. It returns the bodydisp for the message whose structure is described by the calling <B>Mail::IMAPClient::BodystructureB> object.

    bodyid

The <B>bodyidB> object method requires no arguments. It returns the bodyid for the message whose structure is described by the calling <B>Mail::IMAPClient::BodystructureB> object.

    bodydesc

The <B>bodydescB> object method requires no arguments. It returns the bodydesc for the message whose structure is described by the calling <B>Mail::IMAPClient::BodystructureB> object.

    bodyenc

The <B>bodyencB> object method requires no arguments. It returns the bodyenc for the message whose structure is described by the calling <B>Mail::IMAPClient::BodystructureB> object.

    bodysize

The <B>bodysizeB> object method requires no arguments. It returns the bodysize for the message whose structure is described by the calling <B>Mail::IMAPClient::BodystructureB> object.

    bodylang

The <B>bodylangB> object method requires no arguments. It returns the bodylang for the message whose structure is described by the calling <B>Mail::IMAPClient::BodystructureB> object.

    bodystructure

The <B>bodystructureB> object method requires no arguments. It returns the bodystructure for the message whose structure is described by the calling <B>Mail::IMAPClient::BodystructureB> object.

    envelopestruct

The <B>envelopestructB> object method requires no arguments. It returns a <B>Mail::IMAPClient::BodyStructure::EnvelopeB> object for the message from the calling <B>Mail::IMAPClient::BodystructureB> object.

    textlines

The <B>textlinesB> object method requires no arguments. It returns the textlines for the message whose structure is described by the calling <B>Mail::IMAPClient::BodystructureB> object.

Mail::IMAPClient::BodyStructure::Envelope

The IMAP standard specifies that output from the IMAP <B>FETCH ENVELOPEB> command will be an RFC2060 envelope structure. It further specifies that output from the <B>FETCH BODYSTRUCTUREB> command may also contain embedded envelope structures (if, for example, a message’s subparts contain one or more included messages). Objects belonging to <B>Mail::IMAPClient::BodyStructure::EnvelopeB> 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 <B>Mail::IMAPClientB>, $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 <B>Mail::IMAPClient::BodyStructure::EnvelopeB> 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 <B>...::EnvelopeB> 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 <B>Mail::IMAPClient::BodyStructure::AddressB> objects, which are perl data structures representing RFC2060 address structures. Some of these arrays would naturally contain one element (such as <B>fromB>, 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 <B>...::AddressB> objects.

See the section on <B>Mail::IMAPClient::BodyStructure::AddressB>, 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 <B>fromB>.
to Returns an array of recipients’ address structures.
Each of the methods that returns a list of address structures (i.e. a list of <B>Mail::IMAPClient::BodyStructure::AddressB> 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 <B>Mail::IMAPClient::BodyStructure::AddressB>, 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, <B>Mail::IMAPClient::BodyStructure::AddressB>, 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 <B>Mail::IMAPClient::BodyStructureB> parses each of these into an array of <B>Mail::IMAPClient::BodyStructure::AddressB> 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 <B>Mail::IMAPClient::BodyStructure::AddressB> objects come in arrays, it’s generally easier to use the methods available to <B>Mail::IMAPClient::BodyStructure::EnvelopeB> 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 <B>Mail::IMAPClient::BodyStructure::EnvelopeB> 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.
Search for    or go to Top of page |  Section 3 |  Main Index


perl v5.20.3 MAIL::IMAPCLIENT::BODYSTRUCTURE (3) 2015-08-13

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.