NAME¶
Mail::IMAPClient::BodyStructure - parse fetched results
SYNOPSIS¶
use Mail::IMAPClient::BodyStructure;
use Mail::IMAPClient;
my $imap = Mail::IMAPClient->new(Server=>$serv,User=>$usr,Password=>$pwd);
$imap->select("INBOX") or die "cannot select the inbox for $usr: $@\n";
my @recent = $imap->search("recent");
foreach my $id (@recent)
{ my $fetched = $imap->fetch($id, "bodystructure");
my $struct = Mail::IMAPClient::BodyStructure->new($fetched);
my $mime = $struct->bodytype."/".$struct->bodysubtype;
my $parts =join "\n\t", $struct->parts;
print "Msg $id (Content-type: $mime) contains these parts:\n\t$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 that will help you pull
information out of the data structure.
Use of this extension requires Parse::RecDescent. If you don't have
Parse::RecDescent then you must either get it or refrain from using this
module.
EXPORT¶
Nothing is exported by default. $parser is exported upon request. $parser is the
BodyStucture object's Parse::RecDescent object, which you'll probably only
need for debugging purposes.
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. Only one message's body structure should be described in this
string, although that message may contain an arbitrary number of parts.
If you know the messages sequence number or unique ID (UID) but haven't got its
body structure, and you want to get the body structure and parse it into a
Mail::IMAPClient::BodyStructure object, then you might as well save
yourself some work and use
Mail::IMAPClient's
get_bodystructure
method, which accepts a message sequence number (or UID if
Uid is true)
and returns a
Mail::IMAPClient::BodyStructure object. It's functionally
equivalent to issuing the FETCH BODYSTRUCTURE IMAP client command and then
passing the results to
Mail::IMAPClient::BodyStructure's
new
method but it does those things in one simple method call.
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 the
envelopestruct for the message whose structure is described by the calling
Mail::IMAPClient::Bodystructure object. This envelope structure is
blessed into the
Mail::IMAPClient::BodyStructure::Envelope subclass,
which is explained more fully below.
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.
Envelopes and the Mail::IMAPClient::BodyStructure::Envelope
Subclass¶
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¶
David J. Kernen
Reworked and maintained by Mark Overmeer.
SEE ALSO¶
perl(1), Mail::IMAPClient, and RFC2060. See also Parse::RecDescent if you
want to understand the internals of this module.