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
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
|
#ifndef SIEVE_H
#define SIEVE_H
struct sieve_script;
struct sieve_binary;
#include "sieve-config.h"
#include "sieve-types.h"
#include "sieve-error.h"
/*
* Main Sieve library interface
*/
/* Initialize the sieve engine. Must be called before any sieve functionality is
used. */
struct sieve_instance *
sieve_init(const struct sieve_environment *env,
const struct sieve_callbacks *callbacks, void *context, bool debug);
/* Free all memory allocated by the sieve engine. */
void sieve_deinit(struct sieve_instance **_svinst);
/* Get capability string for a particular extension. */
const char *
sieve_get_capabilities(struct sieve_instance *svinst, const char *name);
/* Set the supported extensions. The provided string is parsed into a list
of extensions that are to be enabled/disabled. */
void sieve_set_extensions(struct sieve_instance *svinst,
const char *extensions);
/* Get top-level event for this Sieve instance. */
struct event *sieve_get_event(struct sieve_instance *svinst) ATTR_PURE;
/*
* Script compilation
*/
/* Compile a Sieve script from a Sieve script object. Returns Sieve binary upon
success and NULL upon failure. */
struct sieve_binary *
sieve_compile_script(struct sieve_script *script,
struct sieve_error_handler *ehandler,
enum sieve_compile_flags flags, enum sieve_error *error_r)
ATTR_NULL(2, 4);
/* Compile a Sieve script from a Sieve script location string. Returns Sieve
binary upon success and NULL upon failure. The provided script_name is used
for the internally created Sieve script object. */
struct sieve_binary *
sieve_compile(struct sieve_instance *svinst, const char *script_location,
const char *script_name, struct sieve_error_handler *ehandler,
enum sieve_compile_flags flags, enum sieve_error *error_r)
ATTR_NULL(3, 4, 6);
/*
* Reading/writing Sieve binaries
*/
/* Loads the sieve binary indicated by the provided path. */
struct sieve_binary *
sieve_load(struct sieve_instance *svinst, const char *bin_path,
enum sieve_error *error_r);
/* First tries to open the binary version of the specified script and if it does
not exist or if it contains errors, the script is (re-)compiled. Note that
errors in the bytecode are caught only at runtime.
*/
struct sieve_binary *
sieve_open_script(struct sieve_script *script,
struct sieve_error_handler *ehandler,
enum sieve_compile_flags flags, enum sieve_error *error_r);
/* First tries to open the binary version of the specified script and if it does
not exist or if it contains errors, the script is (re-)compiled. Note that
errors in the bytecode are caught only at runtime.
*/
struct sieve_binary *
sieve_open(struct sieve_instance *svinst, const char *script_location,
const char *script_name, struct sieve_error_handler *ehandler,
enum sieve_compile_flags flags, enum sieve_error *error_r);
/* Record resource usage in the binary cumulatively. The binary is disabled when
resource limits are exceeded within a configured timeout. Returns FALSE when
resource limits are exceeded. */
bool ATTR_NOWARN_UNUSED_RESULT
sieve_record_resource_usage(struct sieve_binary *sbin,
const struct sieve_resource_usage *rusage)
ATTR_NULL(1);
/* Check whether Sieve binary is (still) executable. Returns 1 if all is OK,
0 when an error occurred, and -1 when the error is internal. Sets the Sieve
error code in error_r and a user error message in client_error_r when the
error is not internal. */
int sieve_check_executable(struct sieve_binary *sbin,
enum sieve_error *error_r,
const char **client_error_r);
/* Saves the binary as the file indicated by the path parameter. This function
will not write the binary to disk when the provided binary object was loaded
earlier from the indicated bin_path, unless update is TRUE.
*/
int sieve_save_as(struct sieve_binary *sbin, const char *bin_path, bool update,
mode_t save_mode, enum sieve_error *error_r);
/* Saves the binary to the default location. This function will not overwrite
the binary on disk when the provided binary object was loaded earlier from
the default location, unless update is TRUE.
*/
int sieve_save(struct sieve_binary *sbin, bool update,
enum sieve_error *error_r);
/* Closes a compiled/opened sieve binary. */
void sieve_close(struct sieve_binary **_sbin);
/* Obtains the path the binary was compiled or loaded from. */
const char *sieve_get_source(struct sieve_binary *sbin);
/* Indicates whether the binary was loaded from a pre-compiled file. */
bool sieve_is_loaded(struct sieve_binary *sbin);
/*
* Debugging
*/
/* Dumps the byte code in human-readable form to the specified ostream. */
void sieve_dump(struct sieve_binary *sbin,
struct ostream *stream, bool verbose);
/* Dumps the byte code in hexdump form to the specified ostream. */
void sieve_hexdump(struct sieve_binary *sbin, struct ostream *stream);
/* Executes the bytecode, but only prints the result to the given stream. */
int sieve_test(struct sieve_binary *sbin,
const struct sieve_message_data *msgdata,
const struct sieve_script_env *senv,
struct sieve_error_handler *ehandler, struct ostream *stream,
enum sieve_execute_flags flags);
/*
* Script execution
*/
/* Initializes the scirpt environment from the given mail_user. */
int sieve_script_env_init(struct sieve_script_env *senv, struct mail_user *user,
const char **error_r);
/* Executes the binary, including the result. */
int sieve_execute(struct sieve_binary *sbin,
const struct sieve_message_data *msgdata,
const struct sieve_script_env *senv,
struct sieve_error_handler *exec_ehandler,
struct sieve_error_handler *action_ehandler,
enum sieve_execute_flags flags);
/*
* Multiscript support
*/
struct sieve_multiscript;
struct sieve_multiscript *
sieve_multiscript_start_execute(struct sieve_instance *svinst,
const struct sieve_message_data *msgdata,
const struct sieve_script_env *senv);
struct sieve_multiscript *
sieve_multiscript_start_test(struct sieve_instance *svinst,
const struct sieve_message_data *msgdata,
const struct sieve_script_env *senv,
struct ostream *stream);
bool sieve_multiscript_run(struct sieve_multiscript *mscript,
struct sieve_binary *sbin,
struct sieve_error_handler *exec_ehandler,
struct sieve_error_handler *action_ehandler,
enum sieve_execute_flags flags);
bool sieve_multiscript_will_discard(struct sieve_multiscript *mscript);
void sieve_multiscript_run_discard(struct sieve_multiscript *mscript,
struct sieve_binary *sbin,
struct sieve_error_handler *exec_ehandler,
struct sieve_error_handler *action_ehandler,
enum sieve_execute_flags flags);
int sieve_multiscript_status(struct sieve_multiscript *mscript);
int sieve_multiscript_finish(struct sieve_multiscript **_mscript,
struct sieve_error_handler *action_ehandler,
enum sieve_execute_flags flags, int status);
/*
* Configured limits
*/
unsigned int sieve_max_redirects(struct sieve_instance *svinst);
unsigned int sieve_max_actions(struct sieve_instance *svinst);
size_t sieve_max_script_size(struct sieve_instance *svinst);
/*
* User log
*/
const char *sieve_user_get_log_path(struct sieve_instance *svinst,
struct sieve_script *user_script)
ATTR_NULL(2);
/*
* Script trace log
*/
struct sieve_trace_log;
int sieve_trace_log_create(struct sieve_instance *svinst, const char *path,
struct sieve_trace_log **trace_log_r) ATTR_NULL(2);
int sieve_trace_log_create_dir(struct sieve_instance *svinst, const char *dir,
struct sieve_trace_log **trace_log_r)
ATTR_NULL(3);
int sieve_trace_log_open(struct sieve_instance *svinst,
struct sieve_trace_log **trace_log_r) ATTR_NULL(2);
void sieve_trace_log_printf(struct sieve_trace_log *trace_log,
const char *fmt, ...) ATTR_FORMAT(2, 3);
void sieve_trace_log_free(struct sieve_trace_log **_trace_log);
int sieve_trace_config_get(struct sieve_instance *svinst,
struct sieve_trace_config *tr_config);
/*
* Execution exit codes
*/
const char *sieve_execution_exitcode_to_str(int code);
/*
* Resource usage
*/
/* Initialize the resource usage struct, clearing all usage statistics. */
void sieve_resource_usage_init(struct sieve_resource_usage *rusage_r);
/* Calculate the sum of the provided resource usage statistics, writing the
result to the first. */
void sieve_resource_usage_add(struct sieve_resource_usage *dst,
const struct sieve_resource_usage *src);
/* Returns TRUE if the resource usage is sufficiently high to warrant recording
for checking cumulative resource limits (across several different script
executions). */
bool sieve_resource_usage_is_high(struct sieve_instance *svinst,
const struct sieve_resource_usage *rusage);
/* Returns TRUE when the provided resource usage statistics exceed a configured
policy limit. */
bool sieve_resource_usage_is_excessive(
struct sieve_instance *svinst,
const struct sieve_resource_usage *rusage);
/* Returns a string containing a description of the resource usage (to be used
log messages). */
const char *
sieve_resource_usage_get_summary(const struct sieve_resource_usage *rusage);
#endif
|
