Node:Sieve Data Types, Next:, Up:Library Description


Sieve Data Types

sieve_machine_t Data Type
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 Manipulating the Sieve Machine.

sieve_data_type 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.

sieve_value_t Data Type
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.

sieve_tag_def_t Data Type
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.

sieve_runtime_tag_t Data Type
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.

sieve_handler_t Data Type

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).

sieve_printf_t Data Type
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.

sieve_parse_error_t Data Type
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.

sieve_action_log_t Data Type
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.

sieve_comparator_t Data Type 

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.

sieve_retrieve_t Data Type 

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.

sieve_destructor_t Data Type 

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.

sieve_tag_checker_t Data Type 

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]