.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35)
.\"
.\" 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" ''
.    ds C`
.    ds C'
'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 >0, 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.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Daemon 3pm"
.TH Daemon 3pm "2021-01-16" "perl v5.28.1" "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"
Cyrus::Annotator::Daemon \- framework for writing annotator daemons for Cyrus
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 5
\&  use warnings;
\&  use strict;
\&  package MyAnnotatorDaemon;
\&  use Cyrus::Annotator::Daemon;
\&  our @ISA = qw(Cyrus::Annotator::Daemon);
\&
\&  sub annotate_message
\&  {
\&      my ($self, $message) = @_;
\&
\&      $message\->set_flag(\*(Aq\eFlagged\*(Aq);
\&      $message\->set_shared_annotation(\*(Aq/comment\*(Aq, \*(AqHello!!\*(Aq);
\&  }
\&
\&  MyAnnotatorDaemon\->run();
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module provides a framework for writing daemons which can be used
to add annotations or flags to messages which are delivered into the
Cyrus mail server.
.PP
To use Cyrus::Annotator::Daemon, write a Perl script which creates an
object derived from it; see the Synposis above.  Run this script as
root, and it will daemonize itself.  Then add this line to the
imapd.conf file
.PP
.Vb 1
\&  annotation_callout: /var/run/annotatord.socket
.Ve
.PP
and restart Cyrus.
.SH "METHODS"
.IX Header "METHODS"
Cyrus::Annotator::Daemon has the following methods.
.IP "\fIrun(...options...)\fR" 4
.IX Item "run(...options...)"
This class method can be used to create an instance of
Cyrus::Annotator::Daemon and to run it's main loop.  Note that
Cyrus::Annotator::Daemon derives from Net::Server, and any of that
module's options can be used.
.Sp
For example:
.Sp
.Vb 1
\&  MyAnnotatorDaemon\->run(personality => \*(AqFork\*(Aq);
.Ve
.Sp
Cyrus::Annotator::Daemon changes some of the Net::Server defaults,
including:
.RS 4
.IP "\(bu" 4
Logging is to syslog using facility \fIlocal6\fR.
.IP "\(bu" 4
The network socket is a \fI\s-1SOCK_STREAM\s0\fR \s-1UNIX\s0 domain
socket bound to \fI/var/run/annotatord.socket\fR.
.IP "\(bu" 4
A \s-1PID\s0 file is written to \fI/var/run/annotatord.pid\fR.
.IP "\(bu" 4
The daemon runs in the background, as user \fIcyrus\fR and group \fImail\fR.
.RE
.RS 4
.RE
.IP "\fIannotate_message($message)\fR" 4
.IX Item "annotate_message($message)"
You need to provide a method of this name.  It will be called whenever
Cyrus notifies the annotator daemon that a new message is available, and
may set or clear any flags (system or user flags) or annotations.  Note
that to set any annotations which aren't builtin to Cyrus, you will
first need to configure them using \fIannotation_definitions\fR option in
the \fIimapd.conf\fR file.
.Sp
The \fI\f(CI$message\fI\fR object is a Cyrus::Annotator::Message which can be
examined, and on which flags and annotations can be set.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fINet::Server\fR, \fBimapd.conf\fR(5), \fI\s-1RFC3501\s0\fR, \fI\s-1RFC5257\s0\fR.
.SH "AUTHOR"
.IX Header "AUTHOR"
Greg Banks <gnb@fastmail.fm>.