Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Mail::IMAPClient::BodyUsercContributed Perl Mail::IMAPClient::BodyStructure(3)

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.

perl v5.24.1			  2015-08-13Mail::IMAPClient::BodyStructure(3)

NAME | SYNOPSIS | DESCRIPTION | Class Methods | Object Methods | Mail::IMAPClient::BodyStructure::Envelope | Addresses and the Mail::IMAPClient::BodyStructure::Address | AUTHOR | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Mail::IMAPClient::BodyStructure&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help