@c This is part of the GNU Mailutils manual.
@c Copyright (C) 1999,2000,2001,2002 Free Software Foundation, Inc.
@c See file mailutils.texi for copying conditions.
@comment *******************************************************************

@menu
* Sieve Data Types::
* Manipulating the Sieve Machine::
* Logging and Diagnostic Functions::
* Symbol Space Functions::
* Memory Allocation::
* Compiling and Executing the Script::
@end menu

@node Sieve Data Types
@section Sieve Data Types

@deftp {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 @code{sieve_machine_create()} and destroyed by
@code{sieve_machine_destroy()}. The functions for manipulating this data
type are described in @ref{Manipulating the Sieve Machine}.
@end deftp

@deftp {Enumeration} sieve_data_type
This enumeration keeps the possible types of sieve data. These are:

@table @code
@item SVT_VOID
No datatype.

@item SVT_NUMBER
Numeric type.

@item SVT_STRING
Character string.

@item SVT_STRING_LIST
A @code{list_t}. Each item in this list represents a character string.

@item SVT_TAG
A sieve tag. See @code{sieve_runtime_tag_t} below.

@item SVT_IDENT
A character string representing an identifier. 

@item SVT_VALUE_LIST
A @code{list_t}. Each item in this list is of @code{sieve_value_t}.

@item SVT_POINTER
An opaque pointer.
@end table
@end deftp

@deftp {Structure} sieve_value_t
The @code{sieve_value_t} keeps an instance of sieve data. It is defined
as follows:

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

Depending on the value of @code{type} member, following members of the
union @code{v} keep the actual value:

@table @code
@item SVT_VOID
Never appears.

@item SVT_NUMBER
The numeric value is kept in @code{number} member.

@item SVT_STRING
The string is kept in @code{string} member.

@item SVT_STRING_LIST
@itemx SVT_VALUE_LIST
The list itself is pointed to by @code{list} member

@item SVT_TAG
The tag value is pointed to by @code{tag} member.

@item SVT_IDENT
The @code{string} member points to the identifier name.

@item SVT_POINTER
The data are pointed to by @code{ptr} member.
@end table

@end deftp

@deftp {Structure} 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:

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

The @code{name} member points to the tag's name @emph{without leading
colon}. The @code{argtype} is set to @code{SVT_VOID} if the tag does
not take argument, or to the type of the argument otherwise.
@end deftp

@deftp {Structure} sieve_runtime_tag_t
This structure represents the tagged (optional) argument at a runtime.
It is defined as:

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

The @code{arg} member is @code{NULL} if the tag does not take an argument.
@end deftp

@deftp {Function Type} sieve_handler_t

This is a pointer to function handler for a sieve action or test.
It is defined as follows:
@example
typedef int (*sieve_handler_t) (sieve_machine_t @var{mach},
                                list_t @var{args}, list_t @var{tags});
@end example
@end deftp

The arguments to the handler have the following meaning:

@table @var
@item mach
Sieve machine being processed.
@item args
A list of required arguments to the handler
@item tags
A list of optional arguments (tags).
@end table

@deftp {Function Type} sieve_printf_t
A pointer to a diagnostic output function. It is defined as follows:
@example
typedef int (*sieve_printf_t) (void *@var{data}, const char *@var{fmt}, va_list @var{ap});
@end example
@end deftp

@table @var
@item data
A pointer to application specific data. These data are passed as 
second argument to @code{sieve_machine_init()}.
@item fmt
Printf-like format string.
@item ap
Other arguments.
@end table

@deftp {Function Type} sieve_parse_error_t
This data type is decalred as follows:
@example
typedef int (*sieve_parse_error_t) (void *@var{data},
                                    const char *@var{filename}, int @var{lineno},
                                    const char *@var{fmt}, va_list @var{ap});
@end example
@end deftp

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

@deftp {Function Type} sieve_action_log_t
A pointer to the application-specific logging function:

@example
typedef void (*sieve_action_log_t) (void *@var{data},
                                    const char *@var{script},
                                    size_t @var{msgno}, message_t @var{msg},
                                    const char *@var{action},
                                    const char *@var{fmt}, va_list @var{ap});
@end example
@end deftp

@table @var
@item data
Application-specific data.

@item script
Name of the sieve script being executed.

@item msgno
Ordinal number of the message in mailbox, if appropriate. When execution
is started using @code{sieve_message()}, this argument is zero.

@item msg
The message this action is executed upon.

@item action
The name of the action.

@item fmt
@itemx var
These two arguments give the detaied description of the action.
@end table

@deftp {Function Type} sieve_comparator_t
@example
typedef int (*sieve_comparator_t) (const char *, const char *);
@end example

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

@end deftp

@deftp {Function Type} sieve_retrieve_t
@example
typedef int (*sieve_retrieve_t) (void *item, void *data, int idx,
                                 char **pval);
@end example

A pointer to generic retriever function. See description of
@code{sieve_vlist_compare()} for details of its usage.
@end deftp

@deftp {Function Type} sieve_destructor_t
@example
typedef void (*sieve_destructor_t) (void *data);
@end example

A pointer to destructor function. The function frees any resources
associated with @code{data}. See the description of
@code{sieve_machine_add_destructor()} for more information.
@end deftp

@deftp {Function Type} sieve_tag_checker_t
@example
typedef int (*sieve_tag_checker_t) (const char *@var{name}, list_t @var{tags}, list_t @var{args})
@end example

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

@table @var
@item name
Name of the test or action whose tags are being checked.

@item tags
A list of @code{sieve_runtime_tag_t} representing tags.

@item args
A list of @code{sieve_value_t} representing required arguments to
@var{name}.
@end table

The function is allowed to make any changes in @var{tags} and
@var{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]

@end deftp

@node Manipulating the Sieve Machine
@section Manipulating the Sieve Machine

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

@deftypefn int sieve_machine_init (sieve_machine_t *@var{mach}, void *@var{data})

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

@deftypefn void sieve_machine_destroy (sieve_machine_t *@var{pmach})

This function destroys the instance of sieve machine pointed to by
@var{mach} parameter. After execution of @code{sieve_machine_destroy()}
@var{pmach} contains @code{NULL}. The destructors registered with
@code{sieve_machine_add_destructor()} are executed in @sc{lifo}
order.
@end deftypefn

@deftypefn int sieve_machine_add_destructor (sieve_machine_t @var{mach}, sieve_destructor_t @var{destr}, void *@var{ptr});

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

@example
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);
  .
  .
  .
@}
@end example
@end deftypefn

@deftypefn void *sieve_get_data (sieve_machine_t @var{mach})
This function returns the application-specific data associated with
the instance of sieve machine. See @code{sieve_machine_init()}.
@end deftypefn

@deftypefn message_t sieve_get_message (sieve_machine_t @var{mach})
This function returns the current message.
@end deftypefn

@deftypefn size_t sieve_get_message_num (sieve_machine_t @var{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 @code{sieve_message}, this function returns 1.
@end deftypefn

@deftypefn int sieve_get_debug_level (sieve_machine_t @var{mach})
Returns the debug level set for this instance of sieve machine.
@end deftypefn

@deftypefn ticket_t sieve_get_ticket (sieve_machine_t @var{mach})
Returns the authentication ticket for this machine.
@end deftypefn

@deftypefn mailer_t sieve_get_mailer (sieve_machine_t @var{mach})
Returns the mailer.
@end deftypefn

@deftypefn {char *} sieve_get_daemon_email __P((sieve_machine_t @var{mach})
This function returns the @dfn{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 it local
part is @samp{<MAILER-DAEMON>} and the domain part is the machine name.
@end deftypefn


@deftypefn void sieve_set_error (sieve_machine_t @var{mach}, sieve_printf_t @var{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:

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

@deftypefn void sieve_set_parse_error (sieve_machine_t @var{mach}, sieve_parse_error_t @var{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:

@example
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;
@}
@end example
@end deftypefn

@deftypefn void sieve_set_debug (sieve_machine_t @var{mach}, sieve_printf_t @var{debug}));
This function sets the debug printer function for the machine. If it is
not set, the default debug printer is @code{NULL} which means no
debugging information will be displayed.
@end deftypefn

@deftypefn void sieve_set_debug_level (sieve_machine_t @var{mach}, mu_debug_t @var{dbg}, int @var{level})
This function sets the debug level for the given instance of sieve
machine. The @var{dbg} argument is the @code{mu_debug_t} object to be
used with mailutils library, the @var{level} argument specifies the
debugging level for the sieve library itself. It is a bitwise or of
the following values:

@table @code
@item MU_SIEVE_DEBUG_TRACE
Trace the execution of the sieve script.

@item MU_SIEVE_DEBUG_INSTR 
Print the sieve machine instructions as they are executed.

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

@item MU_SIEVE_DRY_RUN
Do not executed the actions, only show what would have been done.
@end table
@end deftypefn

@deftypefn void sieve_set_logger (sieve_machine_t @var{mach}, sieve_action_log_t @var{logger})
This function sets the logger function. By default the logger function
is @code{NULL}, which means that the executed actions are not logged.
@end deftypefn

@deftypefn void sieve_set_ticket (sieve_machine_t @var{mach}, ticket_t @var{ticket})
This function sets the authentication ticket to be used with this machine.
@end deftypefn

@deftypefn void sieve_set_mailer (sieve_machine_t @var{mach}, mailer_t @var{mailer})
This function sets the mailer. The default mailer is @code{"sendmail:"}.
@end deftypefn

@deftypefn void sieve_set_daemon_email (sieve_machine_t @var{mach}, const char *@var{email})
This functions sets the @dfn{daemon email} for @code{reject} and
@code{redirect} actions.
@end deftypefn

@deftypefn int sieve_is_dry_run (sieve_machine_t @var{mach})
The @code{sieve_is_dry_run()} returns 1 if the machine is in @dfn{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 @code{sieve_set_debug_level()} if its last argument has
the @code{MU_SIEVE_DRY_RUN} bit set.
@end deftypefn

@deftypefn {const char *} sieve_type_str (sieve_data_type @var{type})
Returns the string representation for the given sieve data type. The
return value is a pointer to a static constant string.
@end deftypefn

@node Logging and Diagnostic Functions 
@section Logging and Diagnostic Functions 

@deftypefn void sieve_error (sieve_machine_t @var{mach}, const char *@var{fmt}, @dots{})
Format and output an error message using error printer of the machine @var{mach}.
@end deftypefn

@deftypefn void sieve_debug (sieve_machine_t @var{mach}, const char *@var{fmt}, @dots{})
Format and output a debug message using debug printer of the machine @var{mach}.
@end deftypefn

@deftypefn void sieve_log_action (sieve_machine_t @var{mach}, const char *@var{action}, const char *@var{fmt}, @dots{})
Log a sieve action using logger function associated with the machine @var{mach}.
@end deftypefn

@deftypefn void sieve_abort (sieve_machine_t @var{mach})
Immediately abort the execution of the script.
@end deftypefn

@node Symbol Space Functions
@section Symbol Space Functions

@deftypefn {sieve_register_t *} sieve_test_lookup (sieve_machine_t @var{mach}, const char *@var{name})
Find a register object describing the test @var{name}. Returns
@code{NULL} if no such test exists.
@end deftypefn

@deftypefn sieve_register_t *sieve_action_lookup (sieve_machine_t @var{mach}, const char *@var{name})
Find a register object describing the action @var{name}. Returns
@code{NULL} if no such action exists.
@end deftypefn
                                           
@deftypefn int sieve_register_test (sieve_machine_t @var{mach}, const char *@var{name}, sieve_handler_t @var{handler}, sieve_data_type *@var{arg_types}, sieve_tag_group_t *@var{tags}, int @var{required})
@end deftypefn
                             
@deftypefn int sieve_register_action (sieve_machine_t @var{mach}, const char *@var{name}, sieve_handler_t @var{handler}, sieve_data_type *@var{arg_types}, sieve_tag_group_t *@var{tags}, int @var{required})
@end deftypefn
                               
@deftypefn int sieve_register_comparator (sieve_machine_t @var{mach}, const char *@var{name}, int @var{required}, sieve_comparator_t @var{is}, sieve_comparator_t @var{contains}, sieve_comparator_t @var{matches}, sieve_comparator_t @var{regex})
@end deftypefn
                                   
@deftypefn int sieve_tag_lookup (list_t @var{taglist}, char *@var{name}, sieve_value_t **@var{arg})
@end deftypefn

@deftypefn int sieve_load_ext (sieve_machine_t @var{mach}, const char *@var{name})
@end deftypefn

@node Memory Allocation
@section Memory Allocation

The following functions act as their libc counterparts. The allocated
memory is associated with the @var{mach} argument and is automatically
freed upon the call to @code{sieve_machine_destroy (@var{mach})}.

@deftypefn {void *} sieve_malloc (sieve_machine_t @var{mach}, size_t @var{size})
Allocates @var{size} bytes and returns a pointer to the allocated memory.
@end deftypefn

@deftypefn {char *} sieve_mstrdup (sieve_machine_t @var{mach}, const char *@var{str})
This function returns a pointer to a new string  which is a duplicate of the
string @var{str}.
@end deftypefn

@deftypefn {void *} sieve_mrealloc (sieve_machine_t @var{mach}, void *@var{ptr}, size_t @var{size})
Changes the size of the memory block pointed to by @var{ptr} to
@var{size} bytes.  The contents will be unchanged to the minimum of the
old and new sizes; newly allocated memory will be uninitialized. If
@var{ptr} is @code{NULL}, the call is equivalent to
@code{sieve_malloc(@var{mach}, @var{size})}; if @var{size} is equal to
zero, the call is equivalent to @code{sieve_mfree(@var{ptr})}. Unless
@var{ptr} is @code{NULL}, it must have been returned by an earlier
call to @code{sieve_malloc()} or @code{sieve_mrealloc()}.
@end deftypefn

@deftypefn void sieve_mfree (sieve_machine_t @var{mach}, void *@var{ptr})
@code{sieve_mfree()} frees the memory space pointed to by @var{ptr} and
detaches it from the destructor list of @var{mach}. The @var{ptr} must
have been returned by a previous call to @code{sieve_malloc()} or
@code{sieve_mrealloc()}. Otherwise, or if @code{sieve_mfree(@var{ptr})}
has already been called before, undefined behaviour occurs.

If @var{ptr} is @code{NULL}, no operation is performed.
@end deftypefn

@node Compiling and Executing the Script
@section Compiling and Executing the Script

@deftypefn int sieve_compile (sieve_machine_t @var{mach}, const char *@var{name})
Compile the seive script from the file @var{name}.
@end deftypefn

@deftypefn int sieve_mailbox (sieve_machine_t @var{mach}, mailbox_t @var{mbox})
Execute the code from the given instance of sieve machine @var{mach}
over each message in the mailbox @var{mbox}.
@end deftypefn

@deftypefn int sieve_message (sieve_machine_t @var{mach}, message_t @var{message})
Execute the code from the given instance of sieve machine @var{mach}
over the @var{message}.
@end deftypefn

@deftypefn int sieve_disass (sieve_machine_t @var{mach})
Dump the disassembled code of the sieve machine @var{mach}.
@end deftypefn