1Mail::IMAPClient::BodySUtsreurctCuornet(r3i)buted Perl DMoaciulm:e:nItMaAtPiColnient::BodyStructure(3)
2
6 Mail::IMAPClient::BodyStructure - parse fetched results
7
9 use Mail::IMAPClient::BodyStructure;
10 use Mail::IMAPClient;
11 my $imap = Mail::IMAPClient->new(Server=>$serv,User=>$usr,Password=>$pwd);
13 $imap->select("INBOX") or die "cannot select the inbox for $usr: $@\n";
14 my @recent = $imap->search("recent");
16 foreach my $id (@recent)
18 { my $fetched = $imap->fetch($id, "bodystructure");
19 my $struct = Mail::IMAPClient::BodyStructure->new($fetched);
20 my $mime = $struct->bodytype."/".$struct->bodysubtype;
22 my $parts =join "\n\t", $struct->parts;
23 print "Msg $id (Content-type: $mime) contains these parts:\n\t$parts\n";
24 }
25
27 This extension will parse the result of an IMAP FETCH BODYSTRUCTURE
28 command into a perl data structure. It also provides helper methods
29 that will help you pull information out of the data structure.
30 Use of this extension requires Parse::RecDescent. If you don't have
32 Parse::RecDescent then you must either get it or refrain from using
33 this module.
34 EXPORT
36 Nothing is exported by default. $parser is exported upon request.
37 $parser is the BodyStucture object's Parse::RecDescent object, which
38 you'll probably only need for debugging purposes.
39
41 The following class method is available:
42 new
44 This class method is the constructor method for instantiating new
45 Mail::IMAPClient::BodyStructure objects. The new method accepts one
46 argument, a string containing a server response to a FETCH
47 BODYSTRUCTURE directive. Only one message's body structure should be
48 described in this string, although that message may contain an
49 arbitrary number of parts.
50 If you know the messages sequence number or unique ID (UID) but haven't
52 got its body structure, and you want to get the body structure and
53 parse it into a Mail::IMAPClient::BodyStructure object, then you might
54 as well save yourself some work and use Mail::IMAPClient's
55 get_bodystructure method, which accepts a message sequence number (or
56 UID if Uid is true) and returns a Mail::IMAPClient::BodyStructure
57 object. It's functionally equivalent to issuing the FETCH BODYSTRUCTURE
58 IMAP client command and then passing the results to
59 Mail::IMAPClient::BodyStructure's new method but it does those things
60 in one simple method call.
61
63 The following object methods are available:
64 bodytype
66 The bodytype object method requires no arguments. It returns the
67 bodytype for the message whose structure is described by the calling
68 Mail::IMAPClient::Bodystructure object.
69 bodysubtype
71 The bodysubtype object method requires no arguments. It returns the
72 bodysubtype for the message whose structure is described by the calling
73 Mail::IMAPClient::Bodystructure object.
74 bodyparms
76 The bodyparms object method requires no arguments. It returns the
77 bodyparms for the message whose structure is described by the calling
78 Mail::IMAPClient::Bodystructure object.
79 bodydisp
81 The bodydisp object method requires no arguments. It returns the
82 bodydisp for the message whose structure is described by the calling
83 Mail::IMAPClient::Bodystructure object.
84 bodyid
86 The bodyid object method requires no arguments. It returns the bodyid
87 for the message whose structure is described by the calling
88 Mail::IMAPClient::Bodystructure object.
89 bodydesc
91 The bodydesc object method requires no arguments. It returns the
92 bodydesc for the message whose structure is described by the calling
93 Mail::IMAPClient::Bodystructure object.
94 bodyenc
96 The bodyenc object method requires no arguments. It returns the
97 bodyenc for the message whose structure is described by the calling
98 Mail::IMAPClient::Bodystructure object.
99 bodysize
101 The bodysize object method requires no arguments. It returns the
102 bodysize for the message whose structure is described by the calling
103 Mail::IMAPClient::Bodystructure object.
104 bodylang
106 The bodylang object method requires no arguments. It returns the
107 bodylang for the message whose structure is described by the calling
108 Mail::IMAPClient::Bodystructure object.
109 bodystructure
111 The bodystructure object method requires no arguments. It returns the
112 bodystructure for the message whose structure is described by the
113 calling Mail::IMAPClient::Bodystructure object.
114 envelopestruct
116 The envelopestruct object method requires no arguments. It returns the
117 envelopestruct for the message whose structure is described by the
118 calling Mail::IMAPClient::Bodystructure object. This envelope structure
119 is blessed into the Mail::IMAPClient::BodyStructure::Envelope subclass,
120 which is explained more fully below.
121 textlines
123 The textlines object method requires no arguments. It returns the
124 textlines for the message whose structure is described by the calling
125 Mail::IMAPClient::Bodystructure object.
126
128 The IMAP standard specifies that output from the IMAP FETCH ENVELOPE
129 command will be an RFC2060 envelope structure. It further specifies
130 that output from the FETCH BODYSTRUCTURE command may also contain
131 embedded envelope structures (if, for example, a message's subparts
132 contain one or more included messages). Objects belonging to
133 Mail::IMAPClient::BodyStructure::Envelope are Perl representations of
134 these envelope structures, which is to say the nested parenthetical
135 lists of RFC2060 translated into a Perl datastructure.
136 Note that all of the fields relate to the specific part to which they
138 belong. In other words, output from a FETCH nnnn ENVELOPE command (or,
139 in Mail::IMAPClient, "$imap-"fetch($msgid,"ENVELOPE")> or "my $env =
140 $imap-"get_envelope($msgid)>) are for the message, but fields from
141 within a bodystructure relate to the message subpart and not the parent
142 message.
143 An envelope structure's Mail::IMAPClient::BodyStructure::Envelope
145 representation is a hash of thingies that looks like this:
146 {
148 subject => "subject",
149 inreplyto => "reference_message_id",
150 from => [ addressStruct1 ],
151 messageid => "message_id",
152 bcc => [ addressStruct1, addressStruct2 ],
153 date => "Tue, 09 Jul 2002 14:15:53 -0400",
154 replyto => [ adressStruct1, addressStruct2 ],
155 to => [ adressStruct1, addressStruct2 ],
156 sender => [ adressStruct1 ],
157 cc => [ adressStruct1, addressStruct2 ],
158 }
159 The ...::Envelope object also has methods for accessing data in the
161 structure. They are:
162 date
164 Returns the date of the message.
165 inreplyto
167 Returns the message id of the message to which this message is a
168 reply.
169 subject
171 Returns the subject of the message.
172 messageid
174 Returns the message id of the message.
175 You can also use the following methods to get addressing information.
177 Each of these methods returns an array of
178 Mail::IMAPClient::BodyStructure::Address objects, which are perl data
179 structures representing RFC2060 address structures. Some of these
180 arrays would naturally contain one element (such as from, which
181 normally contains a single "From:" address); others will often contain
182 more than one address. However, because RFC2060 defines all of these as
183 "lists of address structures", they are all translated into arrays of
184 ...::Address objects.
185 See the section on Mail::IMAPClient::BodyStructure::Address", below,
187 for alternate (and preferred) ways of accessing these data.
188 The methods available are:
190 bcc Returns an array of blind cc'ed recipients' address structures.
192 (Don't expect much in here unless the message was sent from the
193 mailbox you're poking around in, by the way.)
194 cc Returns an array of cc'ed recipients' address structures.
196 from
198 Returns an array of "From:" address structures--usually just one.
199 replyto
201 Returns an array of "Reply-to:" address structures. Once again
202 there is usually just one address in the list.
203 sender
205 Returns an array of senders' address structures--usually just one
206 and usually the same as from.
207 to Returns an array of recipients' address structures.
209 Each of the methods that returns a list of address structures (i.e. a
211 list of Mail::IMAPClient::BodyStructure::Address arrays) also has an
212 analagous method that will return a list of E-Mail addresses instead.
213 The addresses are in the format "personalname <mailboxname@hostname>"
214 (see the section on Mail::IMAPClient::BodyStructure::Address, below)
215 However, if the personal name is 'NIL' then it is omitted from the
216 address.
217 These methods are:
219 bcc_addresses
221 Returns a list (or an array reference if called in scalar context)
222 of blind cc'ed recipients' email addresses. (Don't expect much in
223 here unless the message was sent from the mailbox you're poking
224 around in, by the way.)
225 cc_addresses
227 Returns a list of cc'ed recipients' email addresses. If called in a
228 scalar context it returns a reference to an array of email
229 addresses.
230 from_addresses
232 Returns a list of "From:" email addresses. If called in a scalar
233 context it returns the first email address in the list. (It's
234 usually a list of just one anyway.)
235 replyto_addresses
237 Returns a list of "Reply-to:" email addresses. If called in a
238 scalar context it returns the first email address in the list.
239 sender_addresses
241 Returns a list of senders' email addresses. If called in a scalar
242 context it returns the first email address in the list.
243 to_addresses
245 Returns a list of recipients' email addresses. If called in a
246 scalar context it returns a reference to an array of email
247 addresses.
248 Note that context affects the behavior of all of the above methods.
250 Those fields that will commonly contain multiple entries (i.e. they are
252 recipients) will return an array reference when called in scalar
253 context. You can use this behavior to optimize performance.
254 Those fields that will commonly contain just one address (the sender's)
256 will return the first (and usually only) address. You can use this
257 behavior to optimize your development time.
258
260 Several components of an envelope structure are address structures.
261 They are each parsed into their own object,
262 Mail::IMAPClient::BodyStructure::Address, which looks like this:
263 { mailboxname => 'somebody.special'
265 , hostname => 'somplace.weird.com'
266 , personalname => 'Somebody Special
267 , sourceroute => 'NIL'
268 }
269 RFC2060 specifies that each address component of a bodystructure is a
271 list of address structures, so Mail::IMAPClient::BodyStructure parses
272 each of these into an array of Mail::IMAPClient::BodyStructure::Address
273 objects.
274 Each of these objects has the following methods available to it:
276 mailboxname
278 Returns the "mailboxname" portion of the address, which is the part
279 to the left of the '@' sign.
280 hostname
282 Returns the "hostname" portion of the address, which is the part to
283 the right of the '@' sign.
284 personalname
286 Returns the "personalname" portion of the address, which is the
287 part of the address that's treated like a comment.
288 sourceroute
290 Returns the "sourceroute" portion of the address, which is
291 typically "NIL".
292 Taken together, the parts of an address structure form an address that
294 will look something like this:
295 "personalname <mailboxname@hostname>"
297 Note that because the Mail::IMAPClient::BodyStructure::Address objects
299 come in arrays, it's generally easier to use the methods available to
300 Mail::IMAPClient::BodyStructure::Envelope to obtain all of the
301 addresses in a particular array in one operation. These methods are
302 provided, however, in case you'd rather do things the hard way. (And
303 also because the aforementioned methods from
304 Mail::IMAPClient::BodyStructure::Envelope need them anyway.)
305
307 David J. Kernen
308 Reworked and maintained by Mark Overmeer.
310
312 perl(1), Mail::IMAPClient, and RFC2060. See also Parse::RecDescent if
313 you want to understand the internals of this module.
314perl v5.12.3 2010-10-04Mail::IMAPClient::BodyStructure(3)