.\" 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 "managesieve 3pm"
.TH managesieve 3pm "2021-06-19" "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::SIEVE::managesieve \- Perl client for the SIEVE protocol
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use Cyrus::SIEVE::managesieve;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This is a Perl module which provides a client for the \s-1SIEVE\s0 protocol.
It supports \s-1SASL\s0 authentication and communication encryption, using the
Cyrus \s-1SASL\s0 infrastructure.
.PP
It provides the following functions.
.IP "sieve_get_handle($servername, &username_cb, &authname_cb, &password_cb, &realm_cb)" 4
.IX Item "sieve_get_handle($servername, &username_cb, &authname_cb, &password_cb, &realm_cb)"
Creates and returns a new Sieve object which can be used for communicating
with the \s-1SIEVE\s0 server.  The server is connected to and a login sequence
is performed, using some combination of the given callbacks to fetch
from the calling program any data needed for authentication.
.Sp
The \fIservername\fR may take any of the forms
.RS 4
.IP "\fIhostname\fR" 4
.IX Item "hostname"
.PD 0
.IP "\fIhostname\fR:\fIport\fR" 4
.IX Item "hostname:port"
.IP "\fIipv4address\fR" 4
.IX Item "ipv4address"
.IP "\fIipv4address\fR:\fIport\fR" 4
.IX Item "ipv4address:port"
.IP "[\fIipv6address\fR]" 4
.IX Item "[ipv6address]"
.IP "[\fIipv6address\fR]:\fIport\fR" 4
.IX Item "[ipv6address]:port"
.RE
.RS 4
.PD
.Sp
If not explicitly specified in the \fIservername\fR, the port defaults to
the port named \*(L"sieve\*(R" in the client machine's service database (for
example the \f(CW\*(C`/etc/services\*(C'\fR files), or 4190.
.Sp
All the callbacks are called with the following arguments
.Sp
\&\f(CW$string\fR = callback($which, \f(CW$prompt\fR);
.Sp
where \fIwhich\fR is one of the strings \f(CW"username"\fR, \f(CW"authname"\fR,
\&\f(CW"getpass"\fR, or \f(CW"realm"\fR respectively, and \fIprompt\fR is a
human-readable English language prompt string for the user's benefit.
Each callback should return a string containing the required
information.
.Sp
The function will return \fIundef\fR on error, use
\&\fIsieve_get_global_error\fR to get a description of the error.
.RE
.IP "sieve_get_error($sieveobj)" 4
.IX Item "sieve_get_error($sieveobj)"
Returns a human-readable English language string describing the last
error encountered on the object \fI\f(CI$sieveobj\fI\fR.
.IP "\fBsieve_get_global_error()\fR" 4
.IX Item "sieve_get_global_error()"
Returns a human-readable English language string describing the last
error encountered while creating a Sieve object.
.IP "sieve_logout($sieveobj)" 4
.IX Item "sieve_logout($sieveobj)"
Log out from the \s-1SIEVE\s0 server.  The \fI\f(CI$sieveobj\fI\fR will become unusable.
.ie n .IP "sieve_put_file($sieveobj, $filename)" 4
.el .IP "sieve_put_file($sieveobj, \f(CW$filename\fR)" 4
.IX Item "sieve_put_file($sieveobj, $filename)"
Installs a \s-1SIEVE\s0 script contained in a local file named by \fI\f(CI$filename\fI\fR
to the server.  The name of the script on the server will be the
basename of \fI\f(CI$filename\fI\fR.  Returns zero on success and non-zero on
failure.
.ie n .IP "sieve_put_file_withdest($sieveobj, $filename, $destname)" 4
.el .IP "sieve_put_file_withdest($sieveobj, \f(CW$filename\fR, \f(CW$destname\fR)" 4
.IX Item "sieve_put_file_withdest($sieveobj, $filename, $destname)"
Like \fIsieve_put_file\fR but also specifies the name of the file on the
server.  Any directory part of \fI\f(CI$destname\fI\fR is ignored.
.ie n .IP "sieve_put($sieveobj obj, $name, $data)" 4
.el .IP "sieve_put($sieveobj obj, \f(CW$name\fR, \f(CW$data\fR)" 4
.IX Item "sieve_put($sieveobj obj, $name, $data)"
Installs a \s-1SIEVE\s0 script contained in the scalar \f(CW$data\fR to the server,
with the script name \fI\f(CI$name\fI\fR.  Returns zero on success and non-zero on
failure.
.ie n .IP "sieve_delete($sieveobj obj, $name)" 4
.el .IP "sieve_delete($sieveobj obj, \f(CW$name\fR)" 4
.IX Item "sieve_delete($sieveobj obj, $name)"
Removes a \s-1SIEVE\s0 script from the server.  Returns zero on success and
non-zero on failure.
.IP "sieve_list($sieveobj obj, &callback)" 4
.IX Item "sieve_list($sieveobj obj, &callback)"
Lists existing \s-1SIEVE\s0 scripts on the server.  The \fI&callback\fR returns no
value and is called once for each script on the server, with arguments
.Sp
callback($name, \f(CW$is_active\fR)
.Sp
\&\fIsieve_list\fR returns zero on success and non-zero on failure.
.ie n .IP "sieve_activate($sieveobj, $name)" 4
.el .IP "sieve_activate($sieveobj, \f(CW$name\fR)" 4
.IX Item "sieve_activate($sieveobj, $name)"
Makes the script named \fI\f(CI$name\fI\fR the active script on the server.  Only
one script is active at a time; activating a script de-activates any
others.  Returns zero on success and non-zero on failure.
.ie n .IP "sieve_get($sieveobj, $name, $output)" 4
.el .IP "sieve_get($sieveobj, \f(CW$name\fR, \f(CW$output\fR)" 4
.IX Item "sieve_get($sieveobj, $name, $output)"
Retrieves the \s-1SIEVE\s0 script named <$name> from the server, and stores it
in the scalar \fI\f(CI$output\fI\fR.  Returns zero on success and non-zero on
failure.
.SH "AUTHOR"
.IX Header "AUTHOR"
T. Martin, tmartin@andrew.cmu.edu
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\s-1RFC5804, A\s0 Protocol for Remotely Managing Sieve Scripts.