.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Net::IMAP::Client::MsgSummary 3pm"
.TH Net::IMAP::Client::MsgSummary 3pm "2010-12-21" "perl v5.18.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Net::IMAP::Client::MsgSummary \- parse message (+ subparts) summary info
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
This object is created internally in Net::IMAP::Client\->get_summaries.
You shouldn't need to instantiate it directly.  You can skip the
\&\s-1SYNOPSIS,\s0 these notes are intended for developers.
.PP
.Vb 2
\&    my $imap = Net::IMAP::Client\->new( ... )
\&    $imap\->select(\*(AqINBOX\*(Aq);
\&
\&    # retrieve FETCH lines
\&    my ($ok, $lines) = $imap\->_tell_imap(FETCH => "$msg_id FULL");
\&    die \*(AqFETCH failed: \*(Aq . $imap\->last_error
\&      unless $ok;
\&
\&    # build parsed tokens
\&    my @tokens = map { Net::IMAP::Client::_parse_tokens($_) } @$lines;
\&
\&    # they look like this:
\&    [ \*(Aq*\*(Aq, \*(AqMSGID\*(Aq, \*(AqFETCH\*(Aq,
\&      [ \*(AqFLAGS\*(Aq, [ \*(Aq\e\eSeen\*(Aq, \*(Aq\e\eAnswered\*(Aq ],
\&        \*(AqINTERNALDATE\*(Aq, \*(Aq13\-Aug\-2008 14:43:50 +0300\*(Aq,
\&        \*(AqRFC822.SIZE\*(Aq, \*(Aq867\*(Aq,
\&        \*(AqENVELOPE\*(Aq, [
\&           ...
\&        ]
\&      ...
\&    ]
.Ve
.PP
Basically it's the \s-1IMAP\s0 response parsed into a Perl structure (array
of tokens).  \s-1FIXME:\s0 this stuff should be documented in
Net::IMAP::Client.
.PP
.Vb 6
\&    # make summaries
\&    my @summaries = map {
\&        my $tokens = $_\->[3];
\&        my %hash = @$tokens;
\&        Net::IMAP::Client::MsgSummary\->new(\e%hash);
\&    } @tokens;
\&
\&    my $summary = shift @summaries;
\&
\&    print $summary\->subject;
\&    print $summary\->from\->[0];
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This object can represent a message or a message part.  For example,
for a message containing attachments you will be able to call \fIparts()\fR
in order to fetch parsed Net::IMAP::Client::MsgSummary objects for
each part.  Each part in turn may contain other subparts!  For
example, if a part is of type \f(CW\*(C`message/rfc822\*(C'\fR then its \f(CW\*(C`parts\*(C'\fR
method will return it's subparts, if any.
.PP
There's a distinction between a message and a message part, although
we use the same object to represent both.  A message will have
additional information, fetched from its \s-1ENVELOPE \s0(i.e. \f(CW\*(C`subject\*(C'\fR,
\&\f(CW\*(C`from\*(C'\fR, \f(CW\*(C`to\*(C'\fR, \f(CW\*(C`date\*(C'\fR, etc.).  For a part only, this information
will be missing.
.PP
If all this sounds confusing, you might want to use Data::Dumper to
inspect the structure of a complex message.  See also the
documentation of Net::IMAP::Client's get_summaries method for an
example.
.SH "API REFERENCE"
.IX Header "API REFERENCE"
It contains only accessors that return data as retrieved by the \s-1FETCH\s0
command.  Parts that may be MIME-word encoded are automatically
undecoded.
.ie n .SS """new""  # constructor"
.el .SS "\f(CWnew\fP  # constructor"
.IX Subsection "new # constructor"
Parses/creates a new object from the given \s-1FETCH\s0 data.
.ie n .IP """type""" 4
.el .IP "\f(CWtype\fR" 4
.IX Item "type"
Returns the base \s-1MIME\s0 type (i.e. 'text')
.ie n .IP """subtype""" 4
.el .IP "\f(CWsubtype\fR" 4
.IX Item "subtype"
Returns the subtype (i.e. 'plain')
.ie n .IP """parameters""" 4
.el .IP "\f(CWparameters\fR" 4
.IX Item "parameters"
Returns any parameters passed in \s-1BODY\s0(\s-1STRUCTURE\s0).  You shouldn't need
this.
.ie n .IP """cid""" 4
.el .IP "\f(CWcid\fR" 4
.IX Item "cid"
Returns the part's unique identifier (\s-1CID\s0).
.ie n .IP """description""" 4
.el .IP "\f(CWdescription\fR" 4
.IX Item "description"
Returns the part's description (usually \fIundef\fR).
.ie n .IP """transfer_encoding""" 4
.el .IP "\f(CWtransfer_encoding\fR" 4
.IX Item "transfer_encoding"
Returns the part's content transfer encoding.  You'll need this in
order to decode binary parts.
.ie n .IP """encoded_size""" 4
.el .IP "\f(CWencoded_size\fR" 4
.IX Item "encoded_size"
Returns the size of the encoded part.  This is actually the size in
octets that will be downloaded from the \s-1IMAP\s0 server if you fetch this
part only.
.ie n .IP """content_type""" 4
.el .IP "\f(CWcontent_type\fR" 4
.IX Item "content_type"
Shortcut for \f(CW\*(C`$self\-\*(C'\fRtype . '/' .$self\->subtype>.
.ie n .IP """charset""" 4
.el .IP "\f(CWcharset\fR" 4
.IX Item "charset"
Returns the charset declaration for this part.
.ie n .IP """name""" 4
.el .IP "\f(CWname\fR" 4
.IX Item "name"
Returns the name of this part, if found in \s-1FETCH\s0 response.
.ie n .IP """filename""" 4
.el .IP "\f(CWfilename\fR" 4
.IX Item "filename"
Returns the file name of this part, if found in \s-1FETCH\s0 response.  If
there's no filename it will try \f(CW\*(C`name\*(C'\fR.
.ie n .IP """multipart""" 4
.el .IP "\f(CWmultipart\fR" 4
.IX Item "multipart"
Returns the multipart type (i.e. 'mixed', 'alternative')
.ie n .IP """parts""" 4
.el .IP "\f(CWparts\fR" 4
.IX Item "parts"
Returns the subparts of this part.
.ie n .IP """part_id""" 4
.el .IP "\f(CWpart_id\fR" 4
.IX Item "part_id"
Returns the \*(L"id\*(R" (path) of this part starting from the toplevel
message, i.e. \*(L"2.1\*(R" (meaning that this is the first subpart of the
second subpart of the toplevel message).
.ie n .IP """md5""" 4
.el .IP "\f(CWmd5\fR" 4
.IX Item "md5"
Returns a \s-1MD5\s0 of this part or \fIundef\fR if not present.
.ie n .IP """disposition""" 4
.el .IP "\f(CWdisposition\fR" 4
.IX Item "disposition"
Returns the disposition of this part (\fIundef\fR if not present).  It's
a hash actually that looks like this:
.Sp
.Vb 1
\&  { inline => { filename => \*(Aqfoobar.png\*(Aq } }
.Ve
.ie n .IP """language""" 4
.el .IP "\f(CWlanguage\fR" 4
.IX Item "language"
Returns the language of this part or \fIundef\fR if not present.
.ie n .IP """rfc822_size""" 4
.el .IP "\f(CWrfc822_size\fR" 4
.IX Item "rfc822_size"
Returns the size of the full message body.
.ie n .IP """internaldate""" 4
.el .IP "\f(CWinternaldate\fR" 4
.IX Item "internaldate"
Returns the \s-1INTERNALDATE\s0 of this message.
.ie n .IP """flags""" 4
.el .IP "\f(CWflags\fR" 4
.IX Item "flags"
Returns the flags of this message.
.ie n .IP """uid""" 4
.el .IP "\f(CWuid\fR" 4
.IX Item "uid"
Returns the \s-1UID\s0 of this message.
.ie n .IP """seq_id""" 4
.el .IP "\f(CWseq_id\fR" 4
.IX Item "seq_id"
Returns the sequence number of this message, if it has been retrieved!
.ie n .IP """date""" 4
.el .IP "\f(CWdate\fR" 4
.IX Item "date"
Returns the date of this message (from the Date header).
.ie n .IP """subject""" 4
.el .IP "\f(CWsubject\fR" 4
.IX Item "subject"
Returns the subject of this message.
.ie n .IP """from"", ""sender"", ""reply_to"", ""to"", ""cc"", ""bcc""" 4
.el .IP "\f(CWfrom\fR, \f(CWsender\fR, \f(CWreply_to\fR, \f(CWto\fR, \f(CWcc\fR, \f(CWbcc\fR" 4
.IX Item "from, sender, reply_to, to, cc, bcc"
Returns an array of Net::IMAP::Client::MsgAddress objects containing
the respective addresses.  Note that sometimes this array can be
empty!
.ie n .IP """in_reply_to""" 4
.el .IP "\f(CWin_reply_to\fR" 4
.IX Item "in_reply_to"
Returns the \s-1ID\s0 of the \*(L"parent\*(R" message (to which this one has been
replied).  This is \s-1NOT\s0 the \*(L"\s-1UID\*(R"\s0 of the message!
.ie n .IP """message_id""" 4
.el .IP "\f(CWmessage_id\fR" 4
.IX Item "message_id"
Returns the \s-1ID\s0 of this message (from the Message-ID header).
.ie n .IP """get_subpart"" ($path)" 4
.el .IP "\f(CWget_subpart\fR ($path)" 4
.IX Item "get_subpart ($path)"
Returns the subpart of this message identified by \f(CW$path\fR, which is in
form '1.2' etc.  Returns undef if no such path was found.
.Sp
Here's a possible message structure:
.Sp
.Vb 2
\& \- Container (multipart/mixed) has no path ID; it\*(Aqs the toplevel
\&   message.  It contains the following subparts:
\&
\&   1 multipart/related
\&     1.1 text/html
\&     1.2 image/png (embedded in HTML)
\&
\&   2 message/rfc822 (decoded type is actually multipart/related)
\&     2.1 text/html
\&     2.2 image/png (also embedded)
.Ve
.Sp
\&\f(CW\*(C`get_subpart\*(C'\fR called on the container will return the respective
Net::IMAP::Client::MsgSummary part, i.e. get_subpart('2.1') will
return the text/html part of the attached message.
.ie n .IP """has_attachments""" 4
.el .IP "\f(CWhas_attachments\fR" 4
.IX Item "has_attachments"
Tries to determine if this message has attachments.  For now this
checks if the multipart type is 'mixed', which isn't really accurate.
.ie n .IP """is_message""" 4
.el .IP "\f(CWis_message\fR" 4
.IX Item "is_message"
Returns true if this object represents a message (i.e. has
content_type eq 'message/rfc822').  Note that it won't return true for
the toplevel part, but you \fBknow\fR that that part represents a
message. ;\-)
.ie n .IP """message""" 4
.el .IP "\f(CWmessage\fR" 4
.IX Item "message"
Returns the attached rfc822 message
.ie n .IP """headers""" 4
.el .IP "\f(CWheaders\fR" 4
.IX Item "headers"
Returns (unparsed, as plain text) additional message headers if they
were fetched by get_summaries.  You can use MIME::Head to parse
them.
.SH "TODO"
.IX Header "TODO"
Fix \f(CW\*(C`has_attachments\*(C'\fR
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Net::IMAP::Client, Net::IMAP::Client::MsgAddress
.SH "AUTHOR"
.IX Header "AUTHOR"
Mihai Bazon, <mihai.bazon@gmail.com>
    http://www.dynarchlib.com/
    http://www.bazon.net/mishoo/
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (c) Mihai Bazon 2008.  All rights reserved.
.PP
This module is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
.SH "DISCLAIMER OF WARRANTY"
.IX Header "DISCLAIMER OF WARRANTY"
\&\s-1BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT
WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER
PARTIES PROVIDE THE SOFTWARE \*(L"AS IS\*(R" WITHOUT WARRANTY OF ANY KIND,
EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE
SOFTWARE IS WITH YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME
THE COST OF ALL NECESSARY SERVICING, REPAIR, OR CORRECTION.\s0
.PP
\&\s-1IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE
TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR
CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE
SOFTWARE \s0(\s-1INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE\s0), \s-1EVEN IF
SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
DAMAGES.\s0