NAME

       Cyrus::Annotator::Message - representation of a message to annotate

SYNOPSIS

         use warnings;
         use strict;
         package MyAnnotatorDaemon;
         use base Cyrus::Annotator::Daemon;

         sub annotate_message
         {
             my ($message) = @_;

             $message->set_flag('\Flagged');
             $message->set_shared_annotation('/comment', 'Hello!!');
         }

         MyAnnotatorDaemon->run();

DESCRIPTION

       This module encapsulates a message which is being processed by the annotator daemon.

METHODS

       Cyrus::Annotator::Message has the following methods.

       new(%args)
           Takes the following args:

            # required
            * BODYSTRUCTURE => parsed bodystructure

            # optional (but you need to provide SOMETHING if your code uses any
            # of the accessors)
            * GUID => 40 character sha1
            * HEADER => Mail::Header object with headers pre-parsed
            * FILENAME => path to rfc822 file

            # totally optional (will be considered empty if not set)
            * FLAGS => array of already set flags
            * ANNOTATIONS => array of already set annotations

       fh()
           returns a read-only filehandle to the raw (rfc822) representation of the full message.

       decode_part($Part, $Content)
           Given some content, decode it from the part's content encoding and charset.

       read_part_content($Part, $nbytes)
           returns the first n bytes of the bodypart passed.  This is a section of the
           bodystructure (hashref).  If no part is passed, it's the raw message.

           If no 'nbytes' is passed, read the entire part.

       header()
           returns a Mail::Header object containing all the headers of the message.

       bodystructure()
           returns a structure

           is a structure closely based on the IMAP BODYSTRUCTURE, decoded into a hash, including
           recursively all MIME sections.  In general, the following items are defined for all
           body structures:

           •   MIME-Type

           •   MIME-Subtype

           •   Content-Type

           •   Content-Description

           •   Content-Disposition

           •   Content-Language

           Body structures which have a MIME-Type of 'multipart' contain the following items:

           •   MIME-Subparts

           For body structures except those that have a MIME-Type of 'multipart', the following
           are defined:

           •   Content-ID

           •   Content-Description

           •   Content-Transfer-Encoding

           •   Content-MD5

           •   Size

           •   Lines

           •   Offset

           •   HeaderSize

       guid()
           returns the hex encoded (40 character) sha1 of the rfc822 representation.

       has_flag($name)
       set_flag($name)
       clear_flag($name)
           Check for the boolean value of a flag with $name, set the flag and remove the flag
           respectively.

           Note that changes are not immediate.  They will be applied by the annotator at the
           end.

           For example:

             $message->set_flag("\\Flagged");

       get_shared_annotation($entry)
       get_private_annotation($entry)
       set_shared_annotation($entry, $value)
       set_private_annotation($entry, $value)
       clear_shared_annotation($entry)
       clear_private_annotation($entry)
           Get, set and clear the value of an annotation, either shared or private.  The "get"
           accessors return a string with the value.  Clear is the same as set with $value of the
           empty string ('').

           For example:

             $message->set_shared_annotation('/comment', 'Hello World');

       get_changed()
           returns two arrayrefs - [['flagname', 'bool']] and [['entry', 'type', 'value']], e.g.

           [["\\Flagged", 1]], [['/comment', 'value.shared', 'Hello World']]

SEE ALSO

       RFC3501, RFC5257.

AUTHOR

       Greg Banks <gnb@fastmail.fm>.  Bron Gondwana <brong@fastmail.fm>.