diff options
Diffstat (limited to 'pigeonhole/src/lib-sieve/sieve.h')
| -rw-r--r-- | pigeonhole/src/lib-sieve/sieve.h | 261 |
1 files changed, 261 insertions, 0 deletions
diff --git a/pigeonhole/src/lib-sieve/sieve.h b/pigeonhole/src/lib-sieve/sieve.h new file mode 100644 index 0000000..66a6d12 --- /dev/null +++ b/pigeonhole/src/lib-sieve/sieve.h @@ -0,0 +1,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 |