Net::IMAP::Client::MsgSummary(3pm)

1Net::IMAP::Client::MsgSUusmemrarCyo(n3t)ributed Perl DocNuemte:n:tIaMtAiPo:n:Client::MsgSummary(3)
2
3
4

NAME

6       Net::IMAP::Client::MsgSummary - parse message (+ subparts) summary info
7

SYNOPSIS

9       This object is created internally in Net::IMAP::Client->get_summaries.
10       You shouldn't need to instantiate it directly.  You can skip the
11       SYNOPSIS, these notes are intended for developers.
12
13           my $imap = Net::IMAP::Client->new( ... )
14           $imap->select('INBOX');
15
16           # retrieve FETCH lines
17           my ($ok, $lines) = $imap->_tell_imap(FETCH => "$msg_id FULL");
18           die 'FETCH failed: ' . $imap->last_error
19             unless $ok;
20
21           # build parsed tokens
22           my @tokens = map { Net::IMAP::Client::_parse_tokens($_) } @$lines;
23
24           # they look like this:
25           [ '*', 'MSGID', 'FETCH',
26             [ 'FLAGS', [ '\\Seen', '\\Answered' ],
27               'INTERNALDATE', '13-Aug-2008 14:43:50 +0300',
28               'RFC822.SIZE', '867',
29               'ENVELOPE', [
30                  ...
31               ]
32             ...
33           ]
34
35       Basically it's the IMAP response parsed into a Perl structure (array of
36       tokens).  FIXME: this stuff should be documented in Net::IMAP::Client.
37
38           # make summaries
39           my @summaries = map {
40               my $tokens = $_->[3];
41               my %hash = @$tokens;
42               Net::IMAP::Client::MsgSummary->new(\%hash);
43           } @tokens;
44
45           my $summary = shift @summaries;
46
47           print $summary->subject;
48           print $summary->from->[0];
49

DESCRIPTION

51       This object can represent a message or a message part.  For example,
52       for a message containing attachments you will be able to call parts()
53       in order to fetch parsed Net::IMAP::Client::MsgSummary objects for each
54       part.  Each part in turn may contain other subparts!  For example, if a
55       part is of type "message/rfc822" then its "parts" method will return
56       it's subparts, if any.
57
58       There's a distinction between a message and a message part, although we
59       use the same object to represent both.  A message will have additional
60       information, fetched from its ENVELOPE (i.e. "subject", "from", "to",
61       "date", etc.).  For a part only, this information will be missing.
62
63       If all this sounds confusing, you might want to use Data::Dumper to
64       inspect the structure of a complex message.  See also the documentation
65       of Net::IMAP::Client's get_summaries method for an example.
66

API REFERENCE

68       It contains only accessors that return data as retrieved by the FETCH
69       command.  Parts that may be MIME-word encoded are automatically
70       undecoded.
71
72   "new"  # constructor
73       Parses/creates a new object from the given FETCH data.
74
75       "type"
76           Returns the base MIME type (i.e. 'text')
77
78       "subtype"
79           Returns the subtype (i.e. 'plain')
80
81       "parameters"
82           Returns any parameters passed in BODY(STRUCTURE).  You shouldn't
83           need this.
84
85       "cid"
86           Returns the part's unique identifier (CID).
87
88       "description"
89           Returns the part's description (usually undef).
90
91       "transfer_encoding"
92           Returns the part's content transfer encoding.  You'll need this in
93           order to decode binary parts.
94
95       "encoded_size"
96           Returns the size of the encoded part.  This is actually the size in
97           octets that will be downloaded from the IMAP server if you fetch
98           this part only.
99
100       "content_type"
101           Shortcut for "$self-"type . '/' .$self->subtype>.
102
103       "charset"
104           Returns the charset declaration for this part.
105
106       "name"
107           Returns the name of this part, if found in FETCH response.
108
109       "filename"
110           Returns the file name of this part, if found in FETCH response.  If
111           there's no filename it will try "name".
112
113       "multipart"
114           Returns the multipart type (i.e. 'mixed', 'alternative')
115
116       "parts"
117           Returns the subparts of this part.
118
119       "part_id"
120           Returns the "id" (path) of this part starting from the toplevel
121           message, i.e. "2.1" (meaning that this is the first subpart of the
122           second subpart of the toplevel message).
123
124       "md5"
125           Returns a MD5 of this part or undef if not present.
126
127       "disposition"
128           Returns the disposition of this part (undef if not present).  It's
129           a hash actually that looks like this:
130
131             { inline => { filename => 'foobar.png' } }
132
133       "language"
134           Returns the language of this part or undef if not present.
135
136       "rfc822_size"
137           Returns the size of the full message body.
138
139       "internaldate"
140           Returns the INTERNALDATE of this message.
141
142       "flags"
143           Returns the flags of this message.
144
145       "uid"
146           Returns the UID of this message.
147
148       "seq_id"
149           Returns the sequence number of this message, if it has been
150           retrieved!
151
152       "date"
153           Returns the date of this message (from the Date header).
154
155       "subject"
156           Returns the subject of this message.
157
158       "from", "sender", "reply_to", "to", "cc", "bcc"
159           Returns an array of Net::IMAP::Client::MsgAddress objects
160           containing the respective addresses.  Note that sometimes this
161           array can be empty!
162
163       "in_reply_to"
164           Returns the ID of the "parent" message (to which this one has been
165           replied).  This is NOT the "UID" of the message!
166
167       "message_id"
168           Returns the ID of this message (from the Message-ID header).
169
170       "get_subpart" ($path)
171           Returns the subpart of this message identified by $path, which is
172           in form '1.2' etc.  Returns undef if no such path was found.
173
174           Here's a possible message structure:
175
176            - Container (multipart/mixed) has no path ID; it's the toplevel
177              message.  It contains the following subparts:
178
179              1 multipart/related
180                1.1 text/html
181                1.2 image/png (embedded in HTML)
182
183              2 message/rfc822 (decoded type is actually multipart/related)
184                2.1 text/html
185                2.2 image/png (also embedded)
186
187           "get_subpart" called on the container will return the respective
188           Net::IMAP::Client::MsgSummary part, i.e. get_subpart('2.1') will
189           return the text/html part of the attached message.
190
191       "has_attachments"
192           Tries to determine if this message has attachments.  For now this
193           checks if the multipart type is 'mixed', which isn't really
194           accurate.
195
196       "is_message"
197           Returns true if this object represents a message (i.e. has
198           content_type eq 'message/rfc822').  Note that it won't return true
199           for the toplevel part, but you know that that part represents a
200           message. ;-)
201
202       "message"
203           Returns the attached rfc822 message
204
205       "headers"
206           Returns (unparsed, as plain text) additional message headers if
207           they were fetched by get_summaries.  You can use MIME::Head to
208           parse them.
209

TODO

211       Fix "has_attachments"
212

AUTHOR

217       Mihai Bazon, <mihai.bazon@gmail.com>
218           http://www.dynarchlib.com/
219           http://www.bazon.net/mishoo/
220

COPYRIGHT

222       Copyright (c) Mihai Bazon 2008.  All rights reserved.
223
224       This module is free software; you can redistribute it and/or modify it
225       under the same terms as Perl itself.
226

DISCLAIMER OF WARRANTY

228       BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
229       FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT
230       WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER
231       PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND,
232       EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
233       WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE
234       ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH
235       YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL
236       NECESSARY SERVICING, REPAIR, OR CORRECTION.
237
238       IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
239       WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
240       REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE
241       TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR
242       CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE
243       SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
244       RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
245       FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF
246       SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
247       DAMAGES.
248
249
250
251perl v5.28.1                      2010-12-21  Net::IMAP::Client::MsgSummary(3)