1Mail::IMAPClient::BodySUtsreurctCuornet(r3i)buted Perl DMoaciulm:e:nItMaAtPiColnient::BodyStructure(3)
2
3
4

NAME

6       Mail::IMAPClient::BodyStructure - parse fetched results
7

SYNOPSIS

9         use Mail::IMAPClient;
10         use Mail::IMAPClient::BodyStructure;
11
12         my $imap = Mail::IMAPClient->new(
13             Server => $server, User => $login, Password => $pass
14         );
15
16         $imap->select("INBOX") or die "Could not select INBOX: $@\n";
17
18         my @recent = $imap->search("recent") or die "No recent msgs in INBOX\n";
19
20         foreach my $id (@recent) {
21             my $bsdat = $imap->fetch( $id, "bodystructure" );
22             my $bso   = Mail::IMAPClient::BodyStructure->new( join("", $imap->History) );
23             my $mime  = $bso->bodytype . "/" . $bso->bodysubtype;
24             my $parts = map( "\n\t" . $_, $bso->parts );
25             print "Msg $id (Content-type: $mime) contains these parts:$parts\n";
26         }
27

DESCRIPTION

29       This extension will parse the result of an IMAP FETCH BODYSTRUCTURE
30       command into a perl data structure.  It also provides helper methods to
31       help pull information out of the data structure.
32
33       This module requires Parse::RecDescent.
34

Class Methods

36       The following class method is available:
37
38   new
39       This class method is the constructor method for instantiating new
40       Mail::IMAPClient::BodyStructure objects.  The new method accepts one
41       argument, a string containing a server response to a FETCH
42       BODYSTRUCTURE directive.
43
44       The module Mail::IMAPClient provides the get_bodystructure convenience
45       method to simplify use of this module when starting with just a
46       messages sequence number or unique ID (UID).
47

Object Methods

49       The following object methods are available:
50
51   bodytype
52       The bodytype object method requires no arguments.  It returns the
53       bodytype for the message whose structure is described by the calling
54       Mail::IMAPClient::Bodystructure object.
55
56   bodysubtype
57       The bodysubtype object method requires no arguments.  It returns the
58       bodysubtype for the message whose structure is described by the calling
59       Mail::IMAPClient::Bodystructure object.
60
61   bodyparms
62       The bodyparms object method requires no arguments.  It returns the
63       bodyparms for the message whose structure is described by the calling
64       Mail::IMAPClient::Bodystructure object.
65
66   bodydisp
67       The bodydisp object method requires no arguments.  It returns the
68       bodydisp for the message whose structure is described by the calling
69       Mail::IMAPClient::Bodystructure object.
70
71   bodyid
72       The bodyid object method requires no arguments.  It returns the bodyid
73       for the message whose structure is described by the calling
74       Mail::IMAPClient::Bodystructure object.
75
76   bodydesc
77       The bodydesc object method requires no arguments.  It returns the
78       bodydesc for the message whose structure is described by the calling
79       Mail::IMAPClient::Bodystructure object.
80
81   bodyenc
82       The bodyenc object method requires no arguments.  It returns the
83       bodyenc for the message whose structure is described by the calling
84       Mail::IMAPClient::Bodystructure object.
85
86   bodysize
87       The bodysize object method requires no arguments.  It returns the
88       bodysize for the message whose structure is described by the calling
89       Mail::IMAPClient::Bodystructure object.
90
91   bodylang
92       The bodylang object method requires no arguments.  It returns the
93       bodylang for the message whose structure is described by the calling
94       Mail::IMAPClient::Bodystructure object.
95
96   bodystructure
97       The bodystructure object method requires no arguments.  It returns the
98       bodystructure for the message whose structure is described by the
99       calling Mail::IMAPClient::Bodystructure object.
100
101   envelopestruct
102       The envelopestruct object method requires no arguments.  It returns a
103       Mail::IMAPClient::BodyStructure::Envelope object for the message from
104       the calling Mail::IMAPClient::Bodystructure object.
105
106   textlines
107       The textlines object method requires no arguments.  It returns the
108       textlines for the message whose structure is described by the calling
109       Mail::IMAPClient::Bodystructure object.
110

Mail::IMAPClient::BodyStructure::Envelope

112       The IMAP standard specifies that output from the IMAP FETCH ENVELOPE
113       command will be an RFC2060 envelope structure.  It further specifies
114       that output from the FETCH BODYSTRUCTURE command may also contain
115       embedded envelope structures (if, for example, a message's subparts
116       contain one or more included messages).  Objects belonging to
117       Mail::IMAPClient::BodyStructure::Envelope are Perl representations of
118       these envelope structures, which is to say the nested parenthetical
119       lists of RFC2060 translated into a Perl datastructure.
120
121       Note that all of the fields relate to the specific part to which they
122       belong.  In other words, output from a FETCH nnnn ENVELOPE command (or,
123       in Mail::IMAPClient, "$imap-"fetch($msgid,"ENVELOPE")> or "my $env =
124       $imap-"get_envelope($msgid)>) are for the message, but fields from
125       within a bodystructure relate to the message subpart and not the parent
126       message.
127
128       An envelope structure's Mail::IMAPClient::BodyStructure::Envelope
129       representation is a hash of thingies that looks like this:
130
131         {
132            subject   => "subject",
133            inreplyto => "reference_message_id",
134            from      => [ addressStruct1 ],
135            messageid => "message_id",
136            bcc       => [ addressStruct1, addressStruct2 ],
137            date      => "Tue, 09 Jul 2002 14:15:53 -0400",
138            replyto   => [ adressStruct1, addressStruct2 ],
139            to        => [ adressStruct1, addressStruct2 ],
140            sender    => [ adressStruct1 ],
141            cc        => [ adressStruct1, addressStruct2 ],
142         }
143
144       The ...::Envelope object also has methods for accessing data in the
145       structure. They are:
146
147       date
148           Returns the date of the message.
149
150       inreplyto
151           Returns the message id of the message to which this message is a
152           reply.
153
154       subject
155           Returns the subject of the message.
156
157       messageid
158           Returns the message id of the message.
159
160       You can also use the following methods to get addressing information.
161       Each of these methods returns an array of
162       Mail::IMAPClient::BodyStructure::Address objects, which are perl data
163       structures representing RFC2060 address structures.  Some of these
164       arrays would naturally contain one element (such as from, which
165       normally contains a single "From:" address); others will often contain
166       more than one address.  However, because RFC2060 defines all of these
167       as "lists of address structures", they are all translated into arrays
168       of ...::Address objects.
169
170       See the section on Mail::IMAPClient::BodyStructure::Address, below, for
171       alternate (and preferred) ways of accessing these data.
172
173       The methods available are:
174
175       bcc Returns an array of blind cc'ed recipients' address structures.
176           (Don't expect much in here unless the message was sent from the
177           mailbox you're poking around in, by the way.)
178
179       cc  Returns an array of cc'ed recipients' address structures.
180
181       from
182           Returns an array of "From:" address structures--usually just one.
183
184       replyto
185           Returns an array of "Reply-to:" address structures.  Once again
186           there is usually just one address in the list.
187
188       sender
189           Returns an array of senders' address structures--usually just one
190           and usually the same as from.
191
192       to  Returns an array of recipients' address structures.
193
194       Each of the methods that returns a list of address structures (i.e. a
195       list of Mail::IMAPClient::BodyStructure::Address arrays) also has an
196       analogous method that will return a list of E-Mail addresses instead.
197       The addresses are in the format "personalname <mailboxname@hostname>"
198       (see the section on Mail::IMAPClient::BodyStructure::Address, below)
199       However, if the personal name is 'NIL' then it is omitted from the
200       address.
201
202       These methods are:
203
204       bcc_addresses
205           Returns a list (or an array reference if called in scalar context)
206           of blind cc'ed recipients' email addresses.  (Don't expect much in
207           here unless the message was sent from the mailbox you're poking
208           around in, by the way.)
209
210       cc_addresses
211           Returns a list of cc'ed recipients' email addresses.  If called in
212           a scalar context it returns a reference to an array of email
213           addresses.
214
215       from_addresses
216           Returns a list of "From:" email addresses.  If called in a scalar
217           context it returns the first email address in the list.  (It's
218           usually a list of just one anyway.)
219
220       replyto_addresses
221           Returns a list of "Reply-to:" email addresses.  If called in a
222           scalar context it returns the first email address in the list.
223
224       sender_addresses
225           Returns a list of senders' email addresses.  If called in a scalar
226           context it returns the first email address in the list.
227
228       to_addresses
229           Returns a list of recipients' email addresses.  If called in a
230           scalar context it returns a reference to an array of email
231           addresses.
232
233       Note that context affects the behavior of all of the above methods.
234
235       Those fields that will commonly contain multiple entries (i.e. they are
236       recipients) will return an array reference when called in scalar
237       context.  You can use this behavior to optimize performance.
238
239       Those fields that will commonly contain just one address (the sender's)
240       will return the first (and usually only) address.  You can use this
241       behavior to optimize your development time.
242

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

244       Several components of an envelope structure are address structures.
245       They are each parsed into their own object,
246       Mail::IMAPClient::BodyStructure::Address, which looks like this:
247
248          {
249             mailboxname  => 'somebody.special',
250             hostname     => 'somplace.weird.com'
251             personalname => 'Somebody Special
252             sourceroute  => 'NIL'
253          }
254
255       RFC2060 specifies that each address component of a bodystructure is a
256       list of address structures, so Mail::IMAPClient::BodyStructure parses
257       each of these into an array of Mail::IMAPClient::BodyStructure::Address
258       objects.
259
260       Each of these objects has the following methods available to it:
261
262       mailboxname
263           Returns the "mailboxname" portion of the address, which is the part
264           to the left of the '@' sign.
265
266       hostname
267           Returns the "hostname" portion of the address, which is the part to
268           the right of the '@' sign.
269
270       personalname
271           Returns the "personalname" portion of the address, which is the
272           part of the address that's treated like a comment.
273
274       sourceroute
275           Returns the "sourceroute" portion of the address, which is
276           typically "NIL".
277
278       Taken together, the parts of an address structure form an address that
279       will look something like this:
280
281       "personalname <mailboxname@hostname>"
282
283       Note that because the Mail::IMAPClient::BodyStructure::Address objects
284       come in arrays, it's generally easier to use the methods available to
285       Mail::IMAPClient::BodyStructure::Envelope to obtain all of the
286       addresses in a particular array in one operation.  These methods are
287       provided, however, in case you'd rather do things the hard way.  (And
288       also because the aforementioned methods from
289       Mail::IMAPClient::BodyStructure::Envelope need them anyway.)
290

AUTHOR

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

SEE ALSO

296       perl(1), Mail::IMAPClient, Parse::RecDescent, and RFC2060.
297
298
299
300perl v5.36.0                      2022-07-22Mail::IMAPClient::BodyStructure(3)
Impressum