GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  NET::IMAP::CLIENT::MSGSUMMARY (3)

.ds Aq ’

NAME

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

CONTENTS

SYNOPSIS

This object is created internally in Net::IMAP::Client->get_summaries. You shouldn’t need to instantiate it directly. You can skip the SYNOPSIS, these notes are intended for developers.



    my $imap = Net::IMAP::Client->new( ... )
    $imap->select(INBOX);

    # retrieve FETCH lines
    my ($ok, $lines) = $imap->_tell_imap(FETCH => "$msg_id FULL");
    die FETCH failed:  . $imap->last_error
      unless $ok;

    # build parsed tokens
    my @tokens = map { Net::IMAP::Client::_parse_tokens($_) } @$lines;

    # they look like this:
    [ *, MSGID, FETCH,
      [ FLAGS, [ \\Seen, \\Answered ],
        INTERNALDATE, 13-Aug-2008 14:43:50 +0300,
        RFC822.SIZE, 867,
        ENVELOPE, [
           ...
        ]
      ...
    ]



Basically it’s the IMAP response parsed into a Perl structure (array of tokens). FIXME: this stuff should be documented in Net::IMAP::Client.



    # make summaries
    my @summaries = map {
        my $tokens = $_->[3];
        my %hash = @$tokens;
        Net::IMAP::Client::MsgSummary->new(\%hash);
    } @tokens;

    my $summary = shift @summaries;

    print $summary->subject;
    print $summary->from->[0];



DESCRIPTION

This object can represent a message or a message part. For example, for a message containing attachments you will be able to call parts() 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 message/rfc822 then its parts method will return it’s subparts, if any.

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 ENVELOPE (i.e. subject, from, to, date, etc.). For a part only, this information will be missing.

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.

API REFERENCE

It contains only accessors that return data as retrieved by the FETCH command. Parts that may be MIME-word encoded are automatically undecoded.

CWnew # constructor

Parses/creates a new object from the given FETCH data.
type Returns the base MIME type (i.e. ’text’)
subtype Returns the subtype (i.e. ’plain’)
parameters Returns any parameters passed in BODY(STRUCTURE). You shouldn’t need this.
cid Returns the part’s unique identifier (CID).
description Returns the part’s description (usually undef).
transfer_encoding Returns the part’s content transfer encoding. You’ll need this in order to decode binary parts.
encoded_size Returns the size of the encoded part. This is actually the size in octets that will be downloaded from the IMAP server if you fetch this part only.
content_type Shortcut for $self-type . ’/’ .$self->subtype>.
charset Returns the charset declaration for this part.
name Returns the name of this part, if found in FETCH response.
filename Returns the file name of this part, if found in FETCH response. If there’s no filename it will try name.
multipart Returns the multipart type (i.e. ’mixed’, ’alternative’)
parts Returns the subparts of this part.
part_id Returns the id (path) of this part starting from the toplevel message, i.e. 2.1 (meaning that this is the first subpart of the second subpart of the toplevel message).
md5 Returns a MD5 of this part or undef if not present.
disposition Returns the disposition of this part (undef if not present). It’s a hash actually that looks like this:



  { inline => { filename => foobar.png } }



language Returns the language of this part or undef if not present.
rfc822_size Returns the size of the full message body.
internaldate Returns the INTERNALDATE of this message.
flags Returns the flags of this message.
uid Returns the UID of this message.
seq_id Returns the sequence number of this message, if it has been retrieved!
date Returns the date of this message (from the Date header).
subject Returns the subject of this message.
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!
in_reply_to Returns the ID of the parent message (to which this one has been replied). This is NOT the UID of the message!
message_id Returns the ID of this message (from the Message-ID header).
get_subpart ($path) Returns the subpart of this message identified by $path, which is in form ’1.2’ etc. Returns undef if no such path was found.

Here’s a possible message structure:



 - Container (multipart/mixed) has no path ID; its 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)



get_subpart 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.

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.
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 <B>knowB> that that part represents a message. ;-)
message Returns the attached rfc822 message
headers Returns (unparsed, as plain text) additional message headers if they were fetched by get_summaries. You can use MIME::Head to parse them.

TODO

Fix has_attachments

SEE ALSO

Net::IMAP::Client, Net::IMAP::Client::MsgAddress

AUTHOR

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

COPYRIGHT

Copyright (c) Mihai Bazon 2008. All rights reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

DISCLAIMER OF WARRANTY

BECAUSE 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 AS IS 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.

IN 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 (INCLUDING 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), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

Search for    or go to Top of page |  Section 3 |  Main Index


perl v5.20.3 NET::IMAP::CLIENT::MSGSUMMARY (3) 2010-12-21

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.