Mail::IMAPClient::BodyUsercContributed Perl Mail::IMAPClient::BodyStructure(3)NAMEMail::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($bsdat);
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 conveniece
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
analagous 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 ALSOperl(1), Mail::IMAPClient, Parse::RecDescent, and RFC2060.
perl v5.14.22012-05-08Mail::IMAPClient::BodyStructure(3)
