.\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.07) .\" .\" 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" '' '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 turned on, 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. .ie \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . nr % 0 . rr F .\} .el \{\ . de IX .. .\} .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "Net::ManageSieve 3pm" .TH Net::ManageSieve 3pm "2010-07-10" "perl v5.10.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" Net::ManageSieve \- ManageSieve Protocol Client .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use Net::ManageSieve; \& \& # Constructors \& $sieve = Net::ManageSieve\->new(\*(Aqlocalhost\*(Aq); \& $sieve = Net::ManageSieve\->new(\*(Aqlocalhost\*(Aq, Timeout => 60); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This module implements a client interface to the ManageSieve protocol (). This documentation assumes that you are familiar with the concepts of the protocol. .PP A new Net::ManageSieve object must be created with the \fInew\fR method. Once this has been done, all ManageSieve commands are accessed through this object. .PP \&\fINote\fR: ManageSieve allows to manipulate scripts on a host running a ManageSieve service, this module does not perform, validate or something like that Sieve scipts themselves. .PP This module works in taint mode. .SH "EXAMPLES" .IX Header "EXAMPLES" This example prints the capabilities of the server known as mailhost: .PP .Vb 1 \& #!/usr/local/bin/perl \-w \& \& use Net::ManageSieve; \& \& $sieve = Net::ManageSieve\->new(\*(Aqmailhost\*(Aq); \& print "$k=$v\en" while ($k, $v) = each %{ $sieve\->capabilities }; \& $sieve\->logout; .Ve .PP This example lists all storred scripts on the server and requires \s-1TLS:\s0 .PP .Vb 1 \& #!/usr/local/bin/perl \-w \& \& use Net::ManageSieve; \& \& my $sieve = Net::ManageSieve\->new(\*(Aqmailhost\*(Aq, tls => \*(Aqrequire\*(Aq) \& or die "$@\en"; \& print "Cipher: ", $sieve\->get_cipher(), "\en"; \& $sieve\->login(\*(Aquser\*(Aq, \*(Aqpassword\*(Aq) \& or die "Login: ".$sieve\->error()."\en"; \& my $scripts = $sieve\->listscripts \& or die "List: ".$sieve\->error()."\en"; \& my $activeScript = pop(@$scripts); \& print "$_\en" for sort @$scripts; \& print $activeScript \& ? \*(Aqactive script: \*(Aq . $activeScript \& : \*(Aqno script active\*(Aq \& , "\en"; \& $sieve\->logout; .Ve .SH "ERROR HANDLING" .IX Header "ERROR HANDLING" By default all functions return \f(CW\*(C`undef\*(C'\fR on failure and set an error description into \f(CW$@\fR, which can be retrieved with the method \f(CW\*(C`error()\*(C'\fR as well. .PP The constructor accepts the setting \f(CW\*(C`on_fail\*(C'\fR, which alters this behaviour by changing the step to assign \f(CW$@\fR: If its value is: .ie n .IP """warn""" 4 .el .IP "\f(CWwarn\fR" 4 .IX Item "warn" the program carps the error description. .Sp If \f(CW\*(C`debug\*(C'\fR is enabled, too, the description is printed twice. .ie n .IP """die""" 4 .el .IP "\f(CWdie\fR" 4 .IX Item "die" the program croaks. .IP "is a \s-1CODE\s0 ref" 4 .IX Item "is a CODE ref" this subroutine is called with the arguments: .Sp .Vb 1 \& &code_ref ( $object, $error_message ) .Ve .Sp The return value controls, whether or not the error message will be assigned to \f(CW$@\fR. Private functions may just signal that an error occured, but keep \f(CW$@\fR unchanged. In this case \f(CW$@\fR remains unchanged, if code_ref returns true. .Sp \&\fINote\fR: Even if the code ref returns false, \f(CW$@\fR might bi clobberred by called modules. This is especially true in the \f(CW\*(C`new()\*(C'\fR constructor. .IP "otherwise" 4 .IX Item "otherwise" the default behaviour is retained by setting \f(CW$@\fR. .SH "CONSTRUCTOR" .IX Header "CONSTRUCTOR" .IP "new ( [ \s-1HOST\s0 ] [, \s-1OPTIONS\s0 ] )" 4 .IX Item "new ( [ HOST ] [, OPTIONS ] )" This is the constructor for a new Net::ManageSieve object. \f(CW\*(C`HOST\*(C'\fR is the name of the remote host to which an ManageSieve connection is required. .Sp \&\f(CW\*(C`HOST\*(C'\fR is optional. If \f(CW\*(C`HOST\*(C'\fR is not given then it may instead be passed as the \f(CW\*(C`Host\*(C'\fR option described below. If neither is given then \&\f(CW\*(C`localhost\*(C'\fR will be used. .Sp \&\f(CW\*(C`OPTIONS\*(C'\fR are passed in a hash like fashion, using key and value pairs. Possible options are: .Sp \&\fBHost\fR \- ManageSieve host to connect to. It may be a single scalar, as defined for the \f(CW\*(C`PeerAddr\*(C'\fR option in IO::Socket::INET, or a reference to an array with hosts to try in turn. The \*(L"host\*(R" method will return the value which was used to connect to the host. .Sp \&\fBLocalAddr\fR and \fBLocalPort\fR \- These parameters are passed directly to IO::Socket to allow binding the socket to a local port. .Sp \&\fBTimeout\fR \- Maximum time, in seconds, to wait for a response from the ManageSieve server (default: 120) .Sp \&\fBPort\fR \- Select a port on the remote host to connect to (default is 2000) .Sp \&\fBDebug\fR or \fBdebug\fR \- enable debugging if true (default \s-1OFF\s0) .Sp \&\fINote\fR: All of the above options are passed through to IO::Socket::INET. .Sp \&\fBtls\fR \- issue \s-1STARTTLS\s0 right after connect. If \fBtls\fR is a \s-1HASH\s0 ref, the mode is in member \f(CW\*(C`mode\*(C'\fR, otherwise \f(CW\*(C`tls\*(C'\fR itself is the mode and an empty \s-1SSL\s0 option \s-1HASH\s0 is passed to \fIstarttls()\fR. The \f(CW\*(C`mode\*(C'\fR may be one of \f(CW\*(C`require\*(C'\fR to fail, if \s-1TLS\s0 negotiation fails, or \f(CW\*(C`auto\*(C'\fR, \&\f(CW\*(C`on\*(C'\fR or \f(CW\*(C`yes\*(C'\fR, if \s-1TLS\s0 is to attempt, but a failure is ignored. (Aliases: \fB\s-1TLS\s0\fR, \fBTls\fR) .Sp \&\fBon_fail\fR \- Changes the error handling of all functions that would otherwise return undef and set \f(CW$@\fR. See section \s-1ERROR\s0 \s-1HANDLING\s0 (Aliases: \fBOn_fail\fR) .Sp Example: .Sp .Vb 3 \& $sieve = Net::ManageSieve\->new(\*(Aqmailhost\*(Aq, \& Timeout => 30, \& ); .Ve .Sp use the first host one can connect to successfully \f(CW\*(C`mailhost\*(C'\fR on port \&\f(CW2000\fR, the default port, then \f(CW\*(C`localhost\*(C'\fR on port \f(CW2008\fR. .Sp .Vb 7 \& $sieve = Net::ManageSieve\->new(Host => [ \*(Aqmailhost\*(Aq, \*(Aqlocalhost:2008\*(Aq ], \& Timeout => 30, \& tls => { \& mode => require, \& SSL_ca_path => \*(Aq/usr/ssl/cert\*(Aq, \& } \& ); .Ve .SH "METHODS" .IX Header "METHODS" Unless otherwise stated all methods return either a \fItrue\fR or \fIfalse\fR value, with \fItrue\fR meaning that the operation was a success. When a method states that it returns a value, failure will be returned as \&\fIundef\fR or an empty list. The error is specified in \f(CW$@\fR and can be returned with the \*(L"error\*(R" method. Please see section \s-1ERROR\s0 \s-1HANDLING\s0 for an alternative error handling scheme. .IP "close ()" 4 .IX Item "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. .ie n .IP "starttls ( %SSL_opts )" 4 .el .IP "starttls ( \f(CW%SSL_opts\fR )" 4 .IX Item "starttls ( %SSL_opts )" Initiates a \s-1TLS\s0 session, may be used only before any authentication. .Sp The \f(CW\*(C`SSL_opts\*(C'\fR is a \s-1HASH\s0 containing any options you can pass to IO::Socket::SSL\->\fInew()\fR. No one is passed by default. .Sp In order to detect in the later run, if the connection is encrypted, use the \f(CW\*(C`encrypted()\*(C'\fR function. .Sp Return: \f(CW$self\fR or \f(CW\*(C`undef\*(C'\fR on failure \- the socket is still functioning, but is not encrypted. .IP "encrypted ()" 4 .IX Item "encrypted ()" Returns \f(CW\*(C`undef\*(C'\fR, if the connection is not encrypted, otherwise \&\f(CW\*(C`true\*(C'\fR. .IP "get_cipher (), dump_peer_certificate (), peer_certificate ($field)" 4 .IX Item "get_cipher (), dump_peer_certificate (), peer_certificate ($field)" Returns \f(CW\*(C`undef\*(C'\fR, if the connection is not encrypted, otherwise the functions directly calls the equally named function of IO::Socket::SSL. .IP "auth (\s-1USER\s0 [, \s-1PASSWORD\s0 [, \s-1AUTHNAME\s0 ] ])" 4 .IX Item "auth (USER [, PASSWORD [, AUTHNAME ] ])" Authentificates as \f(CW\*(C`USER\*(C'\fR. .Sp If the module Authen::SASL is available, this module is tried first. In this case, the \f(CW\*(C`USER\*(C'\fR parameter may be a \f(CW\*(C`Authen::SASL\*(C'\fR object, that is not furtherly modified. If \f(CW\*(C`USER\*(C'\fR is no \f(CW\*(C`Authen::SASL\*(C'\fR object, \&\f(CW\*(C`USER\*(C'\fR is passed as \f(CW\*(C`user\*(C'\fR, \f(CW\*(C`PASSWORD\*(C'\fR as \f(CW\*(C`pass\*(C'\fR and \f(CW\*(C`AUTHNAME\*(C'\fR as \f(CW\*(C`authname\*(C'\fR to \f(CW\*(C`Authen::SASL\->new()\*(C'\fR. If \f(CW\*(C`AUTHNAME\*(C'\fR is undefined, \f(CW\*(C`USER\*(C'\fR is passed as \f(CW\*(C`authname\*(C'\fR. This way you can authentificate against Cyrus: \f(CW\*(C`auth(\*(Aqcyrus\*(Aq, $password, $username)\*(C'\fR. .Sp If Authen::SASL is \fInot\fR available or the initialization of it fails, this function attempts to authentificate via the \f(CW\*(C`PLAIN\*(C'\fR method. .Sp Aliases: \f(CW\*(C`login\*(C'\fR, \f(CW\*(C`authentificate\*(C'\fR. .IP "logout ()" 4 .IX Item "logout ()" Sends the \f(CW\*(C`LOGOUT\*(C'\fR command to the server and closes the connection to the server. .Sp Aliases: \f(CW\*(C`quit\*(C'\fR, \f(CW\*(C`bye\*(C'\fR. .IP "host ()" 4 .IX Item "host ()" Returns the remote host of the connection. .IP "capabilities ([reget])" 4 .IX Item "capabilities ([reget])" Returns the capabilities as \s-1HASH\s0 ref, e.g.: .Sp .Vb 6 \& { \& \*(Aqstarttls\*(Aq => 1, \& \*(Aqsasl\*(Aq => \*(AqPLAIN LOGIN\*(Aq, \& \*(Aqimplementation\*(Aq => \*(Aqdovecot\*(Aq, \& \*(Aqsieve\*(Aq => \*(Aqfileinto reject envelope vacation imapflags notify subaddress relational comparator\-i;ascii\-numeric regex\*(Aq \& }; .Ve .Sp If the argument \f(CW\*(C`bool\*(C'\fR is specified and is boolean \f(CW\*(C`TRUE\*(C'\fR, the capabilities are reaquired from the server using the \fI\s-1CAPABILITY\s0\fR command. Note: The initial capabilities may be different from the set acquired later. .IP "havespace (\s-1NAME\s0, \s-1SIZE\s0)" 4 .IX Item "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. .Sp 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. .IP "putscript (\s-1NAME\s0, \s-1SCRIPT\s0)" 4 .IX Item "putscript (NAME, SCRIPT)" Stores the \f(CW\*(C`SCRIPT\*(C'\fR as name \f(CW\*(C`NAME\*(C'\fR on the server, the script is \fInot\fR activated by default. \f(CW\*(C`SCRIPT\*(C'\fR is a scalar in \s-1UTF\-8\s0. .Sp The script must not be empty. .IP "listscripts ()" 4 .IX Item "listscripts ()" returns an \s-1ARRAY\s0 ref of the names of the scripts. .Sp The last entry in the list, specifies the active script, it is an empty string \f(CW""\fR, if there is none. .Sp e.g.: .Sp .Vb 4 \& [ "script1", \& "script2", \& "script1" \& ] .Ve .Sp means that \f(CW\*(C`script1\*(C'\fR is active currently. .IP "setactive (\s-1NAME\s0)" 4 .IX Item "setactive (NAME)" Activates the script named \f(CW\*(C`NAME\*(C'\fR. .IP "getscript (\s-1NAME\s0)" 4 .IX Item "getscript (NAME)" Returns the named script. The contents is in perl-internal \s-1UTF8\s0. .IP "deletescript (\s-1NAME\s0)" 4 .IX Item "deletescript (NAME)" Deletes the script named \f(CW\*(C`NAME\*(C'\fR. .IP "error ()" 4 .IX Item "error ()" Returns the locally cached error information in the form: .Sp .Vb 1 \& error description respn=last server response .Ve .IP "debug ( [state] )" 4 .IX Item "debug ( [state] )" Returns the current state of debugging. .Sp If \f(CW\*(C`state\*(C'\fR is given, the boolean value enables or disables debugging. .ie n .IP """str2utf8([encoding,] string)""" 4 .el .IP "\f(CWstr2utf8([encoding,] string)\fR" 4 .IX Item "str2utf8([encoding,] string)" Encodes the string into internal \s-1UTF8\s0. .Sp If encoding is specified, it is tried first; then \f(CW\*(C`utf\-8\-strict\*(C'\fR, and, if all fails, \f(CW\*(C`Latin1\*(C'\fR, which is not fail. .SH "BUGS" .IX Header "BUGS" The modules tries hard to pass valid \s-1UTF8\s0 data to the server and transforms the results into perl internal \s-1UTF8\s0. If latter fails, the transmitted octets are decoded using Latin1. .PP Script names, user names and passwords are not checked or \&\*(L"SASLprep\*(R"'ed (\s-1RFC\s0 4013/3454). Script names with \f(CW\*(C`[\e0\er\en]\*(C'\fR are rejected. .PP We accept non-synchronizing literals \f(CW\*(C`{num+}\*(C'\fR from the server. .SH "SEE ALSO" .IX Header "SEE ALSO" .SH "AUTHOR" .IX Header "AUTHOR" Steffen Kaiser This module heavily bases on Net::SMTP and Net::Cmd. .SH "COPYRIGHT" .IX Header "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.