1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
|
#
# Copyright (c) 1994-2008 Carnegie Mellon University. All rights reserved.
#
# Redistribution and use in source and binary forms, with or without
# modification, are permitted provided that the following conditions
# are met:
#
# 1. Redistributions of source code must retain the above copyright
# notice, this list of conditions and the following disclaimer.
#
# 2. Redistributions in binary form must reproduce the above copyright
# notice, this list of conditions and the following disclaimer in
# the documentation and/or other materials provided with the
# distribution.
#
# 3. The name "Carnegie Mellon University" must not be used to
# endorse or promote products derived from this software without
# prior written permission. For permission or any legal
# details, please contact
# Carnegie Mellon University
# Center for Technology Transfer and Enterprise Creation
# 4615 Forbes Avenue
# Suite 302
# Pittsburgh, PA 15213
# (412) 268-7393, fax: (412) 268-7395
# innovation@andrew.cmu.edu
#
# 4. Redistributions of any form whatsoever must retain the following
# acknowledgment:
# "This product includes software developed by Computing Services
# at Carnegie Mellon University (http://www.cmu.edu/computing/)."
#
# CARNEGIE MELLON UNIVERSITY DISCLAIMS ALL WARRANTIES WITH REGARD TO
# THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
# AND FITNESS, IN NO EVENT SHALL CARNEGIE MELLON UNIVERSITY BE LIABLE
# FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
# WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN
# AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING
# OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
#
package Cyrus::SIEVE::managesieve;
use strict;
use Carp;
use vars qw($VERSION @ISA @EXPORT @EXPORT_OK $AUTOLOAD);
require Exporter;
require DynaLoader;
@ISA = qw(Exporter DynaLoader);
# Items to export into callers namespace by default. Note: do not export
# names by default without a very good reason. Use EXPORT_OK instead.
# Do not simply export all your public functions/methods/constants.
@EXPORT = qw(
sieve_get_handle
sieve_get_error
sieve_get_global_error
sieve_put_file
sieve_put_file_withdest
sieve_put
sieve_delete
sieve_list
sieve_activate
sieve_get
sieve_logout
);
$VERSION = '0.01';
sub AUTOLOAD {
# This AUTOLOAD is used to 'autoload' constants from the constant()
# XS function. If a constant is not found then control is passed
# to the AUTOLOAD in AutoLoader.
my $constname;
($constname = $AUTOLOAD) =~ s/.*:://;
my $val = constant($constname, @_ ? $_[0] : 0);
if ($! != 0) {
if ($! =~ /Invalid/) {
$AutoLoader::AUTOLOAD = $AUTOLOAD;
goto &AutoLoader::AUTOLOAD;
}
else {
croak "Your vendor has not defined Cyrus::SIEVE::managesieve macro $constname";
}
}
eval "sub $AUTOLOAD { $val }";
goto &$AUTOLOAD;
}
bootstrap Cyrus::SIEVE::managesieve $VERSION;
# Preloaded methods go here.
# Autoload methods go after =cut, and are processed by the autosplit program.
1;
__END__
# Below is the stub of documentation for your module. You better edit it!
=head1 NAME
Cyrus::SIEVE::managesieve - Perl client for the SIEVE protocol
=head1 SYNOPSIS
use Cyrus::SIEVE::managesieve;
=head1 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.
=over
=item 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 I<servername> may take any of the forms
=over
=item I<hostname>
=item I<hostname>:I<port>
=item I<ipv4address>
=item I<ipv4address>:I<port>
=item [I<ipv6address>]
=item [I<ipv6address>]:I<port>
=back
If not explicitly specified in the I<servername>, the port defaults to
the port named "sieve" in the client machine's service database (for
example the C</etc/services> files), or 4190.
All the callbacks are called with the following arguments
$string = callback($which, $prompt);
where I<which> is one of the strings C<"username">, C<"authname">,
C<"getpass">, or C<"realm"> respectively, and I<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 I<undef> on error, use
I<sieve_get_global_error> to get a description of the error.
=item sieve_get_error($sieveobj)
Returns a human-readable English language string describing the last
error encountered on the object I<$sieveobj>.
=item sieve_get_global_error()
Returns a human-readable English language string describing the last
error encountered while creating a Sieve object.
=item sieve_logout($sieveobj)
Log out from the SIEVE server. The I<$sieveobj> will become unusable.
=item sieve_put_file($sieveobj, $filename)
Installs a SIEVE script contained in a local file named by I<$filename>
to the server. The name of the script on the server will be the
basename of I<$filename>. Returns zero on success and non-zero on
failure.
=item sieve_put_file_withdest($sieveobj, $filename, $destname)
Like I<sieve_put_file> but also specifies the name of the file on the
server. Any directory part of I<$destname> is ignored.
=item sieve_put($sieveobj obj, $name, $data)
Installs a SIEVE script contained in the scalar $data to the server,
with the script name I<$name>. Returns zero on success and non-zero on
failure.
=item sieve_delete($sieveobj obj, $name)
Removes a SIEVE script from the server. Returns zero on success and
non-zero on failure.
=item sieve_list($sieveobj obj, &callback)
Lists existing SIEVE scripts on the server. The I<&callback> returns no
value and is called once for each script on the server, with arguments
callback($name, $is_active)
I<sieve_list> returns zero on success and non-zero on failure.
=item sieve_activate($sieveobj, $name)
Makes the script named I<$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.
=item sieve_get($sieveobj, $name, $output)
Retrieves the SIEVE script named <$name> from the server, and stores it
in the scalar I<$output>. Returns zero on success and non-zero on
failure.
=back
=head1 AUTHOR
T. Martin, tmartin@andrew.cmu.edu
=head1 SEE ALSO
RFC5804, A Protocol for Remotely Managing Sieve Scripts.
=cut
|
