NAME

       Cyrus::SIEVE::managesieve - Perl client for the SIEVE protocol

SYNOPSIS

         use Cyrus::SIEVE::managesieve;

DESCRIPTION

       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.

AUTHOR

       T. Martin, tmartin@andrew.cmu.edu

SEE ALSO

       RFC5804, A Protocol for Remotely Managing Sieve Scripts.

perl v5.38.2                                       2024-07-29                                   managesieve(3pm)