.\" Automatically generated by Pod::Man 2.23 (Pod::Simple 3.14)
.\"
.\" 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" ''
'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.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" 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.12.4" "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\s0\*(R" 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\s0 \s-1THIS\s0 \s-1SOFTWARE\s0 \s-1IS\s0 \s-1LICENSED\s0 \s-1FREE\s0 \s-1OF\s0 \s-1CHARGE\s0, \s-1THERE\s0 \s-1IS\s0 \s-1NO\s0 \s-1WARRANTY\s0
\&\s-1FOR\s0 \s-1THE\s0 \s-1SOFTWARE\s0, \s-1TO\s0 \s-1THE\s0 \s-1EXTENT\s0 \s-1PERMITTED\s0 \s-1BY\s0 \s-1APPLICABLE\s0 \s-1LAW\s0. \s-1EXCEPT\s0
\&\s-1WHEN\s0 \s-1OTHERWISE\s0 \s-1STATED\s0 \s-1IN\s0 \s-1WRITING\s0 \s-1THE\s0 \s-1COPYRIGHT\s0 \s-1HOLDERS\s0 \s-1AND/OR\s0 \s-1OTHER\s0
\&\s-1PARTIES\s0 \s-1PROVIDE\s0 \s-1THE\s0 \s-1SOFTWARE\s0 \*(L"\s-1AS\s0 \s-1IS\s0\*(R" \s-1WITHOUT\s0 \s-1WARRANTY\s0 \s-1OF\s0 \s-1ANY\s0 \s-1KIND\s0,
\&\s-1EITHER\s0 \s-1EXPRESSED\s0 \s-1OR\s0 \s-1IMPLIED\s0, \s-1INCLUDING\s0, \s-1BUT\s0 \s-1NOT\s0 \s-1LIMITED\s0 \s-1TO\s0, \s-1THE\s0
\&\s-1IMPLIED\s0 \s-1WARRANTIES\s0 \s-1OF\s0 \s-1MERCHANTABILITY\s0 \s-1AND\s0 \s-1FITNESS\s0 \s-1FOR\s0 A \s-1PARTICULAR\s0
\&\s-1PURPOSE\s0. \s-1THE\s0 \s-1ENTIRE\s0 \s-1RISK\s0 \s-1AS\s0 \s-1TO\s0 \s-1THE\s0 \s-1QUALITY\s0 \s-1AND\s0 \s-1PERFORMANCE\s0 \s-1OF\s0 \s-1THE\s0
\&\s-1SOFTWARE\s0 \s-1IS\s0 \s-1WITH\s0 \s-1YOU\s0. \s-1SHOULD\s0 \s-1THE\s0 \s-1SOFTWARE\s0 \s-1PROVE\s0 \s-1DEFECTIVE\s0, \s-1YOU\s0 \s-1ASSUME\s0
\&\s-1THE\s0 \s-1COST\s0 \s-1OF\s0 \s-1ALL\s0 \s-1NECESSARY\s0 \s-1SERVICING\s0, \s-1REPAIR\s0, \s-1OR\s0 \s-1CORRECTION\s0.
.PP
\&\s-1IN\s0 \s-1NO\s0 \s-1EVENT\s0 \s-1UNLESS\s0 \s-1REQUIRED\s0 \s-1BY\s0 \s-1APPLICABLE\s0 \s-1LAW\s0 \s-1OR\s0 \s-1AGREED\s0 \s-1TO\s0 \s-1IN\s0 \s-1WRITING\s0
\&\s-1WILL\s0 \s-1ANY\s0 \s-1COPYRIGHT\s0 \s-1HOLDER\s0, \s-1OR\s0 \s-1ANY\s0 \s-1OTHER\s0 \s-1PARTY\s0 \s-1WHO\s0 \s-1MAY\s0 \s-1MODIFY\s0 \s-1AND/OR\s0
\&\s-1REDISTRIBUTE\s0 \s-1THE\s0 \s-1SOFTWARE\s0 \s-1AS\s0 \s-1PERMITTED\s0 \s-1BY\s0 \s-1THE\s0 \s-1ABOVE\s0 \s-1LICENCE\s0, \s-1BE\s0 \s-1LIABLE\s0
\&\s-1TO\s0 \s-1YOU\s0 \s-1FOR\s0 \s-1DAMAGES\s0, \s-1INCLUDING\s0 \s-1ANY\s0 \s-1GENERAL\s0, \s-1SPECIAL\s0, \s-1INCIDENTAL\s0, \s-1OR\s0
\&\s-1CONSEQUENTIAL\s0 \s-1DAMAGES\s0 \s-1ARISING\s0 \s-1OUT\s0 \s-1OF\s0 \s-1THE\s0 \s-1USE\s0 \s-1OR\s0 \s-1INABILITY\s0 \s-1TO\s0 \s-1USE\s0 \s-1THE\s0
\&\s-1SOFTWARE\s0 (\s-1INCLUDING\s0 \s-1BUT\s0 \s-1NOT\s0 \s-1LIMITED\s0 \s-1TO\s0 \s-1LOSS\s0 \s-1OF\s0 \s-1DATA\s0 \s-1OR\s0 \s-1DATA\s0 \s-1BEING\s0
\&\s-1RENDERED\s0 \s-1INACCURATE\s0 \s-1OR\s0 \s-1LOSSES\s0 \s-1SUSTAINED\s0 \s-1BY\s0 \s-1YOU\s0 \s-1OR\s0 \s-1THIRD\s0 \s-1PARTIES\s0 \s-1OR\s0 A
\&\s-1FAILURE\s0 \s-1OF\s0 \s-1THE\s0 \s-1SOFTWARE\s0 \s-1TO\s0 \s-1OPERATE\s0 \s-1WITH\s0 \s-1ANY\s0 \s-1OTHER\s0 \s-1SOFTWARE\s0), \s-1EVEN\s0 \s-1IF\s0
\&\s-1SUCH\s0 \s-1HOLDER\s0 \s-1OR\s0 \s-1OTHER\s0 \s-1PARTY\s0 \s-1HAS\s0 \s-1BEEN\s0 \s-1ADVISED\s0 \s-1OF\s0 \s-1THE\s0 \s-1POSSIBILITY\s0 \s-1OF\s0 \s-1SUCH\s0
\&\s-1DAMAGES\s0.