/ 
Net-ManageSieve-0.13
River stage one • 1 direct dependent • 1 total dependent
/ Net::ManageSieve

NAME

Net::ManageSieve - ManageSieve Protocol Client

SYNOPSIS

use Net::ManageSieve;

# Constructors
$sieve = Net::ManageSieve->new('localhost');
$sieve = Net::ManageSieve->new('localhost', Timeout => 60);

DESCRIPTION

This module implements a client interface to the ManageSieve protocol (http://tools.ietf.org/html/draft-martin-managesieve-09). This documentation assumes that you are familiar with the concepts of the protocol.

A new Net::ManageSieve object must be created with the new method. Once this has been done, all ManageSieve commands are accessed through this object.

Note: ManageSieve allows one to manipulate scripts on a host running a ManageSieve service, this module does not perform, validate or something like that Sieve scipts themselves.

This module works in taint mode.

EXAMPLES

This example prints the capabilities of the server known as mailhost:

#!/usr/local/bin/perl -w

use Net::ManageSieve;

$sieve = Net::ManageSieve->new('mailhost');
print "$k=$v\n" while ($k, $v) = each %{ $sieve->capabilities };
$sieve->logout;

This example lists all storred scripts on the server and requires TLS:

    #!/usr/local/bin/perl -w

    use Net::ManageSieve;

    my $sieve = Net::ManageSieve->new('mailhost', tls => 'require')
      or die "$@\n";
    print "Cipher: ", $sieve->get_cipher(), "\n";
    $sieve->login('user', 'password')
      or die "Login: ".$sieve->error()."\n";
    my $scripts = $sieve->listscripts
      or die "List: ".$sieve->error()."\n";
    my $activeScript = pop(@$scripts);
	print "$_\n" for sort @$scripts;
    print $activeScript
      ? 'active script: ' . $activeScript
      : 'no script active'
     , "\n";
    $sieve->logout;

ERROR HANDLING

By default all functions return undef on failure and set an error description into $@, which can be retrieved with the method error() as well.

The constructor accepts the setting on_fail, which alters this behaviour by changing the step to assign $@: If its value is:

warn

the program carps the error description.

If debug is enabled, too, the description is printed twice.

die

the program croaks.

is a CODE ref

this subroutine is called with the arguments:

&code_ref ( $object, $error_message )

The return value controls, whether or not the error message will be assigned to $@. Private functions may just signal that an error occurred, but keep $@ unchanged. In this case $@ remains unchanged, if code_ref returns true.

Note: Even if the code ref returns false, $@ might bi clobberred by called modules. This is especially true in the new() constructor.

otherwise

the default behaviour is retained by setting $@.

CONSTRUCTOR

new ( [ HOST ] [, OPTIONS ] )

This is the constructor for a new Net::ManageSieve object. HOST is the name of the remote host to which an ManageSieve connection is required.

HOST is optional. If HOST is not given then it may instead be passed as the Host option described below. If neither is given then localhost will be used.

OPTIONS are passed in a hash like fashion, using key and value pairs. Possible options are:

Host - ManageSieve host to connect to. It may be a single scalar, as defined for the PeerAddr option in IO::Socket::INET, or a reference to an array with hosts to try in turn. The "host" method will return the value which was used to connect to the host.

LocalAddr and LocalPort - These parameters are passed directly to IO::Socket to allow binding the socket to a local port.

Timeout - Maximum time, in seconds, to wait for a response from the ManageSieve server (default: 120)

Port - Select a port on the remote host to connect to (default is 2000)

Debug or debug - enable debugging if true (default OFF)

Note: All of the above options are passed through to IO::Socket::INET.

tls - issue STARTTLS right after connect. If tls is a HASH ref, the mode is in member mode, otherwise tls itself is the mode and an empty SSL option HASH is passed to starttls(). The mode may be one of require to fail, if TLS negotiation fails, or auto, on or yes, if TLS is to attempt, but a failure is ignored. (Aliases: TLS, Tls)

on_fail - Changes the error handling of all functions that would otherwise return undef and set $@. See section ERROR HANDLING (Aliases: On_fail)

Example:

    $sieve = Net::ManageSieve->new('mailhost',
			   Timeout => 30,
	);

use the first host one can connect to successfully mailhost on port 2000, the default port, then localhost on port 2008.

    $sieve = Net::ManageSieve->new(Host => [ 'mailhost', 'localhost:2008' ],
			   Timeout => 30,
			   tls => {
			   	mode => require,
			   	SSL_ca_path => '/usr/ssl/cert',
			   }
	);

METHODS

Unless otherwise stated all methods return either a true or false value, with true meaning that the operation was a success. When a method states that it returns a value, failure will be returned as undef or an empty list. The error is specified in $@ and can be returned with the "error" method. Please see section ERROR HANDLING for an alternative error handling scheme.

close ()

Closes the connection to the server. Any already cached data is kept active, though, there should be no pending data, if an user calls this function.

starttls ( %SSL_opts )

Initiates a TLS session, may be used only before any authentication.

The SSL_opts is a HASH containing any options you can pass to IO::Socket::SSL->new(). No one is passed by default.

In order to detect in the later run, if the connection is encrypted, use the encrypted() function.

Return: $self or undef on failure - the socket is still functioning, but is not encrypted.

encrypted ()

Returns undef, if the connection is not encrypted, otherwise true.

get_cipher (), dump_peer_certificate (), peer_certificate ($field)

Returns undef, if the connection is not encrypted, otherwise the functions directly calls the equally named function of IO::Socket::SSL.

auth (USER [, PASSWORD [, AUTHNAME ] ])

Authentificates as USER.

If the module Authen::SASL is available, this module is tried first. In this case, the USER parameter may be a Authen::SASL object, that is not furtherly modified. If USER is no Authen::SASL object, USER is passed as user, PASSWORD as pass and AUTHNAME as authname to Authen::SASL->new(). If AUTHNAME is undefined, USER is passed as authname. This way you can authentificate against Cyrus: auth('cyrus', $password, $username).

If Authen::SASL is not available or the initialization of it fails, this function attempts to authentificate via the PLAIN method.

Aliases: login, authentificate.

logout ()

Sends the LOGOUT command to the server and closes the connection to the server.

Aliases: quit, bye.

host ()

Returns the remote host of the connection.

capabilities ([reget])

Returns the capabilities as HASH ref, e.g.:

{
  'starttls' => 1,
  'sasl' => 'PLAIN LOGIN',
  'implementation' => 'dovecot',
  'sieve' => 'fileinto reject envelope vacation imapflags notify subaddress relational comparator-i;ascii-numeric regex'
};

If the argument bool is specified and is boolean TRUE, the capabilities are reaquired from the server using the CAPABILITY command. Note: The initial capabilities may be different from the set acquired later.

havespace (NAME, SIZE)

Return whether or not a script with the specified size (and name) might fit into the space of the user on the server.

Due to various reasons, the result of this function is not very reliable, because in the meantime lots of changes may take place on the server.

putscript (NAME, SCRIPT)

Stores the SCRIPT as name NAME on the server, the script is not activated by default. SCRIPT is a scalar in UTF-8.

The script must not be empty.

listscripts ()

returns an ARRAY ref of the names of the scripts.

The last entry in the list, specifies the active script, it is an empty string "", if there is none.

e.g.:

[	"script1",
	"script2",
	"script1"
]

means that script1 is active currently.

setactive (NAME)

Activates the script named NAME.

getscript (NAME)

Returns the named script. The contents is in perl-internal UTF8.

deletescript (NAME)

Deletes the script named NAME.

error ()

Returns the locally cached error information in the form:

error description respn=last server response
debug ( [state] )

Returns the current state of debugging.

If state is given, the boolean value enables or disables debugging.

str2utf8([encoding,] string)

Encodes the string into internal UTF8.

If encoding is specified, it is tried first; then utf-8-strict, and, if all fails, Latin1, which is not fail.

BUGS

The modules tries hard to pass valid UTF8 data to the server and transforms the results into perl internal UTF8. If latter fails, the transmitted octets are decoded using Latin1.

Script names, user names and passwords are not checked or "SASLprep"'ed (RFC 4013/3454). Script names with [\0\r\n] are rejected.

We accept non-synchronizing literals {num+} from the server.

SEE ALSO

http://tools.ietf.org/html/draft-martin-managesieve-09

AUTHOR

Steffen Kaiser This module heavily bases on Net::SMTP and Net::Cmd.

COPYRIGHT

Copyright (c) 2008-2010 Steffen Kaiser. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.