4.4.1 Sieve Data Types

Data Type: sieve_machine_t

This is an opaque data type representing a pointer to an instance of sieve machine. The sieve_machine_t keeps all information necessary for compiling and executing the script.

It is created by sieve_machine_create() and destroyed by sieve_machine_destroy(). The functions for manipulating this data type are described in 4.4.2 Manipulating the Sieve Machine.

Data Type: sieve_data_type

This enumeration keeps the possible types of sieve data. These are:

SVT_VOID

No datatype.

SVT_NUMBER

Numeric type.

SVT_STRING

Character string.

SVT_STRING_LIST

A list_t. Each item in this list represents a character string.

SVT_TAG

A sieve tag. See sieve_runtime_tag_t below.

SVT_IDENT

A character string representing an identifier.

SVT_VALUE_LIST

A list_t. Each item in this list is of sieve_value_t.

SVT_POINTER

An opaque pointer.

Data Type: sieve_value_t

The sieve_value_t keeps an instance of sieve data. It is defined as follows:

typedef struct { sieve_data_type type; /* Type of the data */ union { char *string; /* String value or identifier */ size_t number; /* Numeric value */ list_t list; /* List value */ sieve_runtime_tag_t *tag; /* Tag value */ void *ptr; /* Pointer value */ } v; } sieve_value_t;

Depending on the value of type member, following members of the union v keep the actual value:

SVT_VOID

Never appears.

SVT_NUMBER

The numeric value is kept in number member.

SVT_STRING

The string is kept in string member.

SVT_STRING_LIST

SVT_VALUE_LIST

The list itself is pointed to by list member

SVT_TAG

The tag value is pointed to by tag member.

SVT_IDENT

The string member points to the identifier name.

SVT_POINTER

The data are pointed to by ptr member.

Data Type: sieve_tag_def_t

This structure represents a definition of a tagged (optional) argument to a sieve action or test. It is defined as follows:

typedef struct { char *name; /* Tag name */ sieve_data_type argtype; /* Type of tag argument. */ } sieve_tag_def_t;

The name member points to the tag's name without leading colon. The argtype is set to SVT_VOID if the tag does not take argument, or to the type of the argument otherwise.

Data Type: sieve_runtime_tag_t

This structure represents the tagged (optional) argument at a runtime. It is defined as:

struct sieve_runtime_tag { char *tag; /* Tag name */ sieve_value_t *arg; /* Tag argument (if any) */ };

The arg member is NULL if the tag does not take an argument.

Data Type: sieve_handler_t

This is a pointer to function handler for a sieve action or test. It is defined as follows:

typedef int (*sieve_handler_t) (sieve_machine_t mach, list_t args, list_t tags);

The arguments to the handler have the following meaning:

mach

Sieve machine being processed.

args

A list of required arguments to the handler

tags

A list of optional arguments (tags).

Data Type: sieve_printf_t

A pointer to a diagnostic output function. It is defined as follows:

typedef int (*sieve_printf_t) (void *data, const char *fmt, va_list ap);

data

A pointer to application specific data. These data are passed as second argument to sieve_machine_init().

fmt

Printf-like format string.

ap

Other arguments.

Data Type: sieve_parse_error_t

This data type is declared as follows:

typedef int (*sieve_parse_error_t) (void *data, const char *filename, int lineno, const char *fmt, va_list ap);

It is used to declare error handlers for parsing errors. The application-specific data are passed in the data argument. Arguments filename and line indicate the location of the error in the source text, while fmt and ap give verbose description of the error.

Data Type: sieve_action_log_t

A pointer to the application-specific logging function:

typedef void (*sieve_action_log_t) (void *data, const char *script, size_t msgno, message_t msg, const char *action, const char *fmt, va_list ap);

data

Application-specific data.

script

Name of the sieve script being executed.

msgno

Ordinal number of the message in mailbox, if appropriate. When execution is started using sieve_message(), this argument is zero.

msg

The message this action is executed upon.

action

The name of the action.

fmt

var

These two arguments give the detailed description of the action.

Data Type: sieve_relcmp_t

Data Type: sieve_relcmpn_t

typedef int (*sieve_relcmp_t) (int, int); typedef int (*sieve_relcmpn_t) (size_t, size_t);

Data Type: sieve_comparator_t

typedef int (*sieve_comparator_t) (const char *, const char *);

A pointer to the comparator handler function. The function compares its two operands and returns 1 if they are equal, and 0 otherwise. Notice, that the sense of the return value is inverted in comparison with most standard libc functions like stcmp(), etc.

Data Type: sieve_retrieve_t

typedef int (*sieve_retrieve_t) (void *item, void *data, int idx, char **pval);

A pointer to generic retriever function. See description of sieve_vlist_compare() for details of its usage.

Data Type: sieve_destructor_t

typedef void (*sieve_destructor_t) (void *data);

A pointer to destructor function. The function frees any resources associated with data. See the description of sieve_machine_add_destructor() for more information.

Data Type: sieve_tag_checker_t

typedef int (*sieve_tag_checker_t) (const char *name, list_t tags, list_t args)

A pointer to tag checker function. The purpose of the function is to perform compilation-time consistency test on tags. Its arguments are:

name

Name of the test or action whose tags are being checked.

tags

A list of sieve_runtime_tag_t representing tags.

args

A list of sieve_value_t representing required arguments to name.

The function is allowed to make any changes in tags and args. It should return 0 if the syntax is correct and non-zero otherwise. It is responsible for issuing the diagnostics in the latter case. [FIXME: describe how to do that]