Message(3)

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