4.4.2 Manipulating the Sieve Machine

This subsection describes functions used to create an instance of the sieve machine, read or alter its internal fields and destroy it.

Function: int sieve_machine_init (sieve_machine_t *mach, void *data)

The sieve_machine_init() function creates an instance of a sieve machine. A pointer to the instance itself is returned in the argument mach. The user-specific data to be associated with the new machine are passed in data argument. The function returns 0 on success, non-zero error code otherwise,

Function: void sieve_machine_destroy (sieve_machine_t *pmach)

This function destroys the instance of sieve machine pointed to by mach parameter. After execution of sieve_machine_destroy() pmach contains NULL. The destructors registered with sieve_machine_add_destructor() are executed in LIFO order.

Function: int sieve_machine_add_destructor (sieve_machine_t mach, sieve_destructor_t destr, void *ptr);

This function registers a destructor function dest. The purpose of the destructor is to free any resources associated with the item ptr. The destructor function takes a single argument -- a pointer to the data being destroyed. All registered destructors are called in reverse order upon execution of sieve_machine_destroy(). Here's a short example of the use of this function:

static void free_regex (void *data) { regfree ((regex_t*)data); } int match_part_checker (const char *name, list_t tags, list_t args) { regex_t *regex; /* Initialise the regex: */ regex = sieve_malloc (mach, sizeof (*regex)); /* Make sure it will be freed when necessary */ sieve_machine_add_destructor (sieve_machine, free_regex, regex); . . . }

Function: void* sieve_get_data (sieve_machine_t mach)

This function returns the application-specific data associated with the instance of sieve machine. See sieve_machine_init().

Function: message_t sieve_get_message (sieve_machine_t mach)

This function returns the current message.

Function: size_t sieve_get_message_num (sieve_machine_t mach)

This function returns the current message number in the mailbox. If there are no mailbox, i.e. the execution of the sieve code is started with sieve_message, this function returns 1.

Function: int sieve_get_debug_level (sieve_machine_t mach)

Returns the debug level set for this instance of sieve machine.

Function: ticket_t sieve_get_ticket (sieve_machine_t mach)

Returns the authentication ticket for this machine.

Function: mailer_t sieve_get_mailer (sieve_machine_t mach)

Returns the mailer.

Function: char * sieve_get_daemon_email (sieve_machine_t mach)

This function returns the daemon email associated with this instance of sieve machine. The daemon email is an email address used in envelope from addresses of automatic reply messages. By default its local part is `<MAILER-DAEMON>' and the domain part is the machine name.

Function: void sieve_set_error (sieve_machine_t mach, sieve_printf_t error_printer)

This function sets the error printer function for the machine. If it is not set, the default error printer will be used. It is defined as follows:

int _sieve_default_error_printer (void *unused, const char *fmt, va_list ap) { return mu_verror (fmt, ap); }

Function: void sieve_set_parse_error (sieve_machine_t mach, sieve_parse_error_t p)

This function sets the parse error printer function for the machine. If it is not set, the default parse error printer will be used. It is defined as follows:

int _sieve_default_parse_error (void *unused, const char *filename, int lineno, const char *fmt, va_list ap) { if (filename) fprintf (stderr, "%s:%d: ", filename, lineno); vfprintf (stderr, fmt, ap); fprintf (stderr, "\n"); return 0; }

Function: void sieve_set_debug (sieve_machine_t mach, sieve_printf_t debug);

This function sets the debug printer function for the machine. If it is not set, the default debug printer is NULL which means no debugging information will be displayed.

Function: void sieve_set_debug_level (sieve_machine_t mach, mu_debug_t dbg, int level)

This function sets the debug level for the given instance of sieve machine. The dbg argument is the mu_debug_t object to be used with mailutils library, the level argument specifies the debugging level for the sieve library itself. It is a bitwise or of the following values:

MU_SIEVE_DEBUG_TRACE

Trace the execution of the sieve script.

MU_SIEVE_DEBUG_INSTR

Print the sieve machine instructions as they are executed.

MU_SIEVE_DEBUG_DISAS

Dump the disassembled code of the sieve machine. Do not run it.

MU_SIEVE_DRY_RUN

Do not executed the actions, only show what would have been done.

Function: void sieve_set_logger (sieve_machine_t mach, sieve_action_log_t logger)

This function sets the logger function. By default the logger function is NULL, which means that the executed actions are not logged.

Function: void sieve_set_ticket (sieve_machine_t mach, ticket_t ticket)

This function sets the authentication ticket to be used with this machine.

Function: void sieve_set_mailer (sieve_machine_t mach, mailer_t mailer)

This function sets the mailer. The default mailer is "sendmail:".

Function: void sieve_set_daemon_email (sieve_machine_t mach, const char *email)

This functions sets the daemon email for reject and redirect actions.

Function: int sieve_is_dry_run (sieve_machine_t mach)

The sieve_is_dry_run() returns 1 if the machine is in dry run state, i.e. it will only log the actions that would have been executed without actually executing them. The dry run state is set by calling sieve_set_debug_level() if its last argument has the MU_SIEVE_DRY_RUN bit set.

Function: const char * sieve_type_str (sieve_data_type type)

Returns the string representation for the given sieve data type. The return value is a pointer to a static constant string.