Cyrus::SIEVE::managesieve - Perl client for the SIEVE protocol
use Cyrus::SIEVE::managesieve;
This is a Perl module which provides a client for the SIEVE protocol. It
supports SASL authentication and communication encryption, using the Cyrus
SASL infrastructure.
It provides the following functions.
- 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 SIEVE 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.
The servername may take any of the forms
- hostname
-
hostname:port
- ipv4address
-
ipv4address:port
- [ipv6address]
- [ipv6address]:port
If not explicitly specified in the
servername, the port defaults to the
port named "sieve" in the client machine's service database (for
example the "/etc/services" files), or 4190.
All the callbacks are called with the following arguments
$string = callback($which, $prompt);
where
which is one of the strings "username",
"authname", "getpass", or "realm" respectively,
and
prompt is a human-readable English language prompt string for the
user's benefit. Each callback should return a string containing the required
information.
The function will return
undef on error, use
sieve_get_global_error to get a description of the error.
- sieve_get_error($sieveobj)
- Returns a human-readable English language string describing
the last error encountered on the object
$sieveobj.
- sieve_get_global_error()
- Returns a human-readable English language string describing
the last error encountered while creating a Sieve object.
- sieve_logout($sieveobj)
- Log out from the SIEVE server. The
$sieveobj will become unusable.
- sieve_put_file($sieveobj, $filename)
- Installs a SIEVE script contained in a local file named by
$filename to the server. The name of the script on
the server will be the basename of $filename. Returns
zero on success and non-zero on failure.
- sieve_put_file_withdest($sieveobj, $filename,
$destname)
- Like sieve_put_file but also specifies the name of
the file on the server. Any directory part of
$destname is ignored.
- sieve_put($sieveobj obj, $name, $data)
- Installs a SIEVE script contained in the scalar $data to
the server, with the script name $name. Returns zero
on success and non-zero on failure.
- sieve_delete($sieveobj obj, $name)
- Removes a SIEVE script from the server. Returns zero on
success and non-zero on failure.
- sieve_list($sieveobj obj, &callback)
- Lists existing SIEVE scripts on the server. The
&callback returns no value and is called once for each script
on the server, with arguments
callback($name, $is_active)
sieve_list returns zero on success and non-zero on failure.
- sieve_activate($sieveobj, $name)
- Makes the script named $name 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.
- sieve_get($sieveobj, $name, $output)
- Retrieves the SIEVE script named <$name> from the
server, and stores it in the scalar $output. Returns
zero on success and non-zero on failure.
T. Martin,
[email protected]
RFC5804, A Protocol for Remotely Managing Sieve Scripts.