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
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, tmartin@andrew.cmu.edu
RFC5804, A Protocol for Remotely Managing Sieve Scripts.