1BodyStructure(3) User Contributed Perl Documentation BodyStructure(3)
2
6 Mail::IMAPClient::BodyStructure - Perl extension to Mail::IMAPClient to
7 facilitate the parsing of server responses to the FETCH BODYSTRUCTURE
8 and FETCH ENVELOPE IMAP client commands.
9
11 use Mail::IMAPClient::BodyStructure;
12 use Mail::IMAPClient;
13 my $imap = Mail::IMAPClient->new(Server=>$serv,User=>$usr,Password=>$pwd);
15 $imap->select("INBOX") or die "cannot select the inbox for $usr: $@\n";
16 my @recent = $imap->search("recent");
18 foreach my $new (@recent) {
20 my $struct = Mail::IMAPClient::BodyStructure->new(
22 $imap->fetch($new,"bodystructure")
23 );
24 print "Msg $new (Content-type: ",$struct->bodytype,"/",$struct->bodysubtype,
26 ") contains these parts:\n\t",join("\n\t",$struct->parts),"\n\n";
27 }
29
31 This extension will parse the result of an IMAP FETCH BODYSTRUCTURE
32 command into a perl data structure. It also provides helper methods
33 that will help you pull information out of the data structure.
34 Use of this extension requires Parse::RecDescent. If you don't have
36 Parse::RecDescent then you must either get it or refrain from using
37 this module.
38 EXPORT
40 Nothing is exported by default. $parser is exported upon request.
42 $parser is the BodyStucture object's Parse::RecDescent object, which
43 you'll probably only need for debugging purposes.
44
46 The following class method is available:
47 new
49 This class method is the constructor method for instantiating new
51 Mail::IMAPClient::BodyStructure objects. The new method accepts one
52 argument, a string containing a server response to a FETCH BODYSTRUC‐
53 TURE directive. Only one message's body structure should be described
54 in this string, although that message may contain an arbitrary number
55 of parts.
56 If you know the messages sequence number or unique ID (UID) but haven't
58 got its body structure, and you want to get the body structure and
59 parse it into a Mail::IMAPClient::BodyStructure object, then you might
60 as well save yourself some work and use Mail::IMAPClient's get_bodys‐
61 tructure method, which accepts a message sequence number (or UID if Uid
62 is true) and returns a Mail::IMAPClient::BodyStructure object. It's
63 functionally equivalent to issuing the FETCH BODYSTRUCTURE IMAP client
64 command and then passing the results to Mail::IMAPClient::BodyStruc‐
65 ture's new method but it does those things in one simple method call.
66
68 The following object methods are available:
69 bodytype
71 The bodytype object method requires no arguments. It returns the body‐
73 type for the message whose structure is described by the calling
74 Mail::IMAPClient::Bodystructure object.
75 bodysubtype
77 The bodysubtype object method requires no arguments. It returns the
79 bodysubtype for the message whose structure is described by the calling
80 Mail::IMAPClient::Bodystructure object.
81 bodyparms
83 The bodyparms object method requires no arguments. It returns the
85 bodyparms for the message whose structure is described by the calling
86 Mail::IMAPClient::Bodystructure object.
87 bodydisp
89 The bodydisp object method requires no arguments. It returns the body‐
91 disp for the message whose structure is described by the calling
92 Mail::IMAPClient::Bodystructure object.
93 bodyid
95 The bodyid object method requires no arguments. It returns the bodyid
97 for the message whose structure is described by the calling Mail::IMAP‐
98 Client::Bodystructure object.
99 bodydesc
101 The bodydesc object method requires no arguments. It returns the body‐
103 desc for the message whose structure is described by the calling
104 Mail::IMAPClient::Bodystructure object.
105 bodyenc
107 The bodyenc object method requires no arguments. It returns the
109 bodyenc for the message whose structure is described by the calling
110 Mail::IMAPClient::Bodystructure object.
111 bodysize
113 The bodysize object method requires no arguments. It returns the body‐
115 size for the message whose structure is described by the calling
116 Mail::IMAPClient::Bodystructure object.
117 bodylang
119 The bodylang object method requires no arguments. It returns the body‐
121 lang for the message whose structure is described by the calling
122 Mail::IMAPClient::Bodystructure object.
123 bodystructure
125 The bodystructure object method requires no arguments. It returns the
127 bodystructure for the message whose structure is described by the call‐
128 ing Mail::IMAPClient::Bodystructure object.
129 envelopestruct
131 The envelopestruct object method requires no arguments. It returns the
133 envelopestruct for the message whose structure is described by the
134 calling Mail::IMAPClient::Bodystructure object. This envelope structure
135 is blessed into the Mail::IMAPClient::BodyStructure::Envelope subclass,
136 which is explained more fully below.
137 textlines
139 The textlines object method requires no arguments. It returns the
141 textlines for the message whose structure is described by the calling
142 Mail::IMAPClient::Bodystructure object.
143
145 The IMAP standard specifies that output from the IMAP FETCH ENVELOPE
146 command will be an RFC2060 envelope structure. It further specifies
147 that output from the FETCH BODYSTRUCTURE command may also contain
148 embedded envelope structures (if, for example, a message's subparts
149 contain one or more included messages). Objects belonging to
150 Mail::IMAPClient::BodyStructure::Envelope are Perl representations of
151 these envelope structures, which is to say the nested parenthetical
152 lists of RFC2060 translated into a Perl datastructure.
153 Note that all of the fields relate to the specific part to which they
155 belong. In other words, output from a FETCH nnnn ENVELOPE command (or,
156 in Mail::IMAPClient, "$imap-"fetch($msgid,"ENVELOPE")> or "my $env =
157 $imap-"get_envelope($msgid)>) are for the message, but fields from
158 within a bodystructure relate to the message subpart and not the parent
159 message.
160 An envelope structure's Mail::IMAPClient::BodyStructure::Envelope rep‐
162 resentation is a hash of thingies that looks like this:
163 {
165 subject => "subject",
166 inreplyto => "reference_message_id",
167 from => [ addressStruct1 ],
168 messageid => "message_id",
169 bcc => [ addressStruct1, addressStruct2 ],
170 date => "Tue, 09 Jul 2002 14:15:53 -0400",
171 replyto => [ adressStruct1, addressStruct2 ],
172 to => [ adressStruct1, addressStruct2 ],
173 sender => [ adressStruct1 ],
174 cc => [ adressStruct1, addressStruct2 ], }
175 The ...::Envelope object also has methods for accessing data in the
177 structure. They are:
178 date
180 Returns the date of the message.
181 inreplyto
183 Returns the message id of the message to which this message is a
184 reply.
185 subject
187 Returns the subject of the message.
188 messageid
190 Returns the message id of the message.
191 You can also use the following methods to get addressing information.
193 Each of these methods returns an array of Mail::IMAPClient::BodyStruc‐
194 ture::Address objects, which are perl data structures representing
195 RFC2060 address structures. Some of these arrays would naturally con‐
196 tain one element (such as from, which normally contains a single
197 "From:" address); others will often contain more than one address. How‐
198 ever, because RFC2060 defines all of these as "lists of address struc‐
199 tures", they are all translated into arrays of ...::Address objects.
200 See the section on Mail::IMAPClient::BodyStructure::Address", below,
202 for alternate (and preferred) ways of accessing these data.
203 The methods available are:
205 bcc Returns an array of blind cc'ed recipients' address structures.
207 (Don't expect much in here unless the message was sent from the
208 mailbox you're poking around in, by the way.)
209 cc Returns an array of cc'ed recipients' address structures.
211 from
213 Returns an array of "From:" address structures--usually just one.
214 replyto
216 Returns an array of "Reply-to:" address structures. Once again
217 there is usually just one address in the list.
218 sender
220 Returns an array of senders' address structures--usually just one
221 and usually the same as from.
222 to Returns an array of recipients' address structures.
224 Each of the methods that returns a list of address structures (i.e. a
226 list of Mail::IMAPClient::BodyStructure::Address arrays) also has an
227 analagous method that will return a list of E-Mail addresses instead.
228 The addresses are in the format "personalname <mailboxname@hostname>"
229 (see the section on Mail::IMAPClient::BodyStructure::Address, below)
230 However, if the personal name is 'NIL' then it is omitted from the
231 address.
232 These methods are:
234 bcc_addresses
236 Returns a list (or an array reference if called in scalar context)
237 of blind cc'ed recipients' email addresses. (Don't expect much in
238 here unless the message was sent from the mailbox you're poking
239 around in, by the way.)
240 cc_addresses
242 Returns a list of cc'ed recipients' email addresses. If called in a
243 scalar context it returns a reference to an array of email
244 addresses.
245 from_addresses
247 Returns a list of "From:" email addresses. If called in a scalar
248 context it returns the first email address in the list. (It's usu‐
249 ally a list of just one anyway.)
250 replyto_addresses
252 Returns a list of "Reply-to:" email addresses. If called in a
253 scalar context it returns the first email address in the list.
254 sender_addresses
256 Returns a list of senders' email addresses. If called in a scalar
257 context it returns the first email address in the list.
258 to_addresses
260 Returns a list of recipients' email addresses. If called in a
261 scalar context it returns a reference to an array of email
262 addresses.
263 Note that context affects the behavior of all of the above methods.
265 Those fields that will commonly contain multiple entries (i.e. they are
267 recipients) will return an array reference when called in scalar con‐
268 text. You can use this behavior to optimize performance.
269 Those fields that will commonly contain just one address (the sender's)
271 will return the first (and usually only) address. You can use this
272 behavior to optimize your development time.
273
275 Several components of an envelope structure are address structures.
276 They are each parsed into their own object, Mail::IMAPClient::BodyS‐
277 tructure::Address, which looks like this:
278 {
280 mailboxname => 'somebody.special',
281 hostname => 'somplace.weird.com',
282 personalname => 'Somebody Special
283 sourceroute => 'NIL'
284 }
285 RFC2060 specifies that each address component of a bodystructure is a
287 list of address structures, so Mail::IMAPClient::BodyStructure parses
288 each of these into an array of Mail::IMAPClient::BodyStructure::Address
289 objects.
290 Each of these objects has the following methods available to it:
292 mailboxname
294 Returns the "mailboxname" portion of the address, which is the part
295 to the left of the '@' sign.
296 hostname
298 Returns the "hostname" portion of the address, which is the part to
299 the right of the '@' sign.
300 personalname
302 Returns the "personalname" portion of the address, which is the
303 part of the address that's treated like a comment.
304 sourceroute
306 Returns the "sourceroute" portion of the address, which is typi‐
307 cally "NIL".
308 Taken together, the parts of an address structure form an address that
310 will look something like this:
311 "personalname <mailboxname@hostname>"
313 Note that because the Mail::IMAPClient::BodyStructure::Address objects
315 come in arrays, it's generally easier to use the methods available to
316 Mail::IMAPClient::BodyStructure::Envelope to obtain all of the
317 addresses in a particular array in one operation. These methods are
318 provided, however, in case you'd rather do things the hard way. (And
319 also because the aforementioned methods from Mail::IMAPClient::BodyS‐
320 tructure::Envelope need them anyway.)
321
323 David J. Kernen
324
326 perl(1), Mail::IMAPClient, and RFC2060. See also Parse::RecDescent if
327 you want to understand the internals of this module.
328perl v5.8.8 2003-06-24 BodyStructure(3)