---
name: "Cyrus::Annotator::Message"
section: "3pm"
platform: "linux"
package: "libcyrus-imap-perl"
version: "3.10.2-1+deb13u2"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/Cyrus::Annotator::Message"
---

# Cyrus::Annotator::Message(3pm)

representation of a message to annotate

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