START-INFO-DIR-ENTRY * mailutils: (mailutils). API for mailboxes and mail protocols END-INFO-DIR-ENTRY START-INFO-DIR-ENTRY * comsatd: (mailutils)comsatd. Comsat daemon * frm: (mailutils)frm. List headers from a mailbox * guimb: (mailutils)guimb. Mailbox scanning and processing language * imap4d: (mailutils)imap4d. IMAP4 daemon * mail.local: (mailutils)mail.local. Deliver mail to the local mailbox * mail: (mailutils)mail. Send and receive mail * messages: (mailutils)messages. Count the number of messages in a mailbox * pop3d: (mailutils)pop3d. POP3 daemon * readmsg: (mailutils)readmsg. Extract messages from a folder * sieve: (mailutils)sieve. Mail filtering utility * mailutils-config: (mailutils)mailutils-config. Get the information about the Mailutils build. END-INFO-DIR-ENTRY This file documents Mailutils, library API. Published by the Free Software Foundation, 59 Temple Place - Suite 330 Boston, MA 02111-1307, USA Copyright 1999, 2000 Free Software Foundation, Inc. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that this permission notice may be stated in a translation approved by the Foundation. ...Short Contents... This document was produced for version 0.2 of GNU Mailutils. Introduction ************ GNU Mailutils offers a general purpose library whose aim is to provide a rich set of functions for accessing different mailbox formats and mailers. References ========== For more information on, * SMTP - `RFC 2821: Simple Mail Transfer Protocol' - `RFC 2368: The mailto URL scheme' * POP3 - `RFC 1939: Post Office Protocol - Version 3' - `RFC 1734: POP3 AUTHentication command' - `RFC 1957: Some Observations on Implementations of the Post Office Protocol (POP3)' - `RFC 2449: POP3 Extension Mechanism' - `RFC 2384: POP URL Scheme' * IMAP4 - `RFC 2060: INTERNET MESSAGE ACCESS PROTOCOL - VERSION 4rev1' - `RFC 2088: IMAP4 non-synchronizing literals' - `RFC 2193: IMAP4 Mailbox Referrals' - `RFC 2221: IMAP4 Login Referrals' - `RFC 2342: IMAP4 Namespace' - `RFC 2192: IMAP URL Scheme' - `RFC 1731: IMAP4 Authentication Mechanisms' - `RFC 2245: Anonymous SASL Mechanism' * message formats - `RFC 2822: Internet Message Format' - `RFC 2045: Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies' - `RFC 2046: Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types' - `RFC 2047: Multipurpose Internet Mail Extensions (MIME) Part Three: Message Header Extensions for Non-ASCII Text' - `RFC 2049: Multipurpose Internet Mail Extensions (MIME) Part Five: Conformance Criteria and Examples' - `RFC 2111: Content-ID and Message-ID Uniform Resource Locators' * miscellaneous related topics - `RFC 3028: Sieve: A Mail Filtering Language' - `RFC 2298: An Extensible Message Format for Message Disposition Notifications' - `RFC 1738: Uniform Resource Locators (URL)' - `Internet Email Protocols: A Developer's Guide, by Kevin Johnson' Framework ********* Wherever the mail is and whatever format it is stored in, it is operated upon using the same set of functions. To unified the C API, GNU Mailutils offers a heteroclite set of objects that work in aggregation to do operations on emails. Each object does a specific task and delegates non-related tasks to others. The object comes alive by specifying a _URL_ parameter when created, it will indicate the storage format or protocol (POP3, IMAP4, MH, MAILDIR, etc ..). folder_t url_t -/var/mail- +- .. ->+-----------------+ +-->+------------+ ( alain *-)-+ | | url_t *-|---+ | port | ----------- | | |-----------------| | hostname | ( jakob *-)-+--+ | auth_t *-|---+ | file | ----------- | |-----------------| | | ... | ( jeff *-)-+ | stream_t | | +------------+ ----------- | |-----------------| | ( shaleh*-)-+ | ..... | | auth_t ---------- |-----------------| +-->+------------+ +---|-* mailbox_t[] | | ticket_t | mailbox_t | +-----------------+ +------------+ +----------------+<-+ | locker_t *--|-------------+ |----------------| | | url_t | | locker_t |----------------| +-------->+---------+ | stream_t | | lock | |----------------| | unlock | | message_t[] *-|-------+ +---------+ +----------------+ | envelope_t | +-------->+-----------+ message_t | | | date | +----------------+<------+ | | from | | envelope_t *-|------------------+ | to | |----------------| header_t +-----------+ | header_t *-|------------>+--------------+ |----------------| | stream_t | | body_t *-|----+ +--------------+ +----------------+ | body_t +-->+--------------+ | stream_t | +--------------+ As an example, here is a simplified version of `from' command. It lists the `From' and `Subject' headers of every mail in a mailbox. /* sfrom, Simple From */ #include #include #include #include #include int main (int argc, const char **argv) { char *from; char *subject; mailbox_t mbox; int status; size_t msgno, total = 0; /* Register the type of mailbox. IMAP4, POP3 and local format */ { list_t registrar; registrar_get_list (®istrar); list_append (registrar, imap_record); list_append (registrar, path_record); list_append (registrar, pop_record); } status = mailbox_create_default (&mbox, argv[1]); if (status != 0) { fprintf (stderr, "mailbox_create: %s\n", mu_errstring (status)); exit (EXIT_FAILURE); } status = mailbox_open (mbox, MU_STREAM_READ); if (status != 0) { fprintf (stderr, "mailbox_open: %s\n", mu_errstring (status)); exit (EXIT_FAILURE); } mailbox_messages_count (mbox, &total); for (msgno = 1; msgno <= total; msgno++) { message_t msg; header_t hdr; if ((status = mailbox_get_message (mbox, msgno, &msg)) != 0 || (status = message_get_header (msg, &hdr)) != 0) { fprintf (stderr, "Error message: %s\n", mu_errstring (status)); exit (EXIT_FAILURE); } if (header_aget_value (hdr, MU_HEADER_FROM, &from)) from = strdup ("(NO FROM)"); if (header_aget_value (hdr, MU_HEADER_SUBJECT, &subject)) subject = strdup("(NO SUBJECT)"); printf ("%s\t%s\n", from, subject); free (from); free (subject); } mailbox_close (mbox); mailbox_destroy (&mbox); return 0; } Here is a sample output produced by this program: % MAIL=pop://alain@localhost ./sfrom Passwd: xxxx Jim Meyering fetish(shellutils) beta Franc,ois Pinard recode new alpha ... Folder ====== `/* Prefix _folder__ is reserve */' `#include ' folder_t url_t -/var/mail- +---//---->/-----------------\ +-->/-----------\ ( alain *-)-+ | | url_t *-|----+ | port | ----------- | | |-----------------+ | hostname | ( jakob *-)-+--+ | observer_t *-| | file | ----------- | |-----------------+ | ... | ( jeff *-)-+ | stream_t | \-----------/ ----------- | |-----------------| ( sean *-)-+ | auth_t | ---------- |-----------------| | mailbox_t(1) | |-----------------| | mailbox_t(2) | | ...... | | mailbox_t(n) | \-----------------/ - Function: int folder_create (folder_t *, const char *URL) - Function: void folder_destroy (folder_t *) - Function: int folder_open (folder_t, int FLAG) - Function: int folder_close (folder_t) - Function: int folder_delete (folder_t, const char *MAILBOX) - Function: int folder_rename (folder_t, const char *, const char *MAILBOX) - Function: int folder_subscribe (folder_t, const char *MAILBOX) - Function: int folder_unsubscribe (folder_t, const char *MAILBOX) - Function: int folder_list (folder_t, const char *REF, const char *WCARD, iterator_t *) - Function: int folder_lsub (folder_t, const char *REF, const char *WCAR, iterator_t *) - Function: int folder_get_stream (folder_t, stream_t *) - Function: int folder_set_stream (folder_t, stream_t) - Function: int folder_get_observable (folder_t, observable_t *) - Function: int folder_get_debug (folder_t, debug_t *) - Function: int folder_set_debug (folder_t, debug_t) - Function: int folder_get_authority (folder_t, authority_t *) - Function: int folder_set_authority (folder_t, authority_t) - Function: int folder_get_url (folder_t, url_t *) - Function: int folder_set_url (folder_t, url_t) Mailbox ======= `/* Prefix _mailbox__ is reserved */' `#include ' - Data Type: mailbox_t The `mailbox_t' object is used to hold information and it is an opaque data structure to the user. Functions are provided to retrieve information from the data structure. mailbox_t url_t -/var/mail- +---//---->/-----------------\ +-->/-----------\ ( alain ) | | url_t *-|----+ | port | ----------- | |-----------------+ | hostname | ( jakob *-)----+ | observer_t *-| | file | ----------- |-----------------+ | ... | ( jeff ) | stream_t | \-----------/ ----------- |-----------------| ( sean ) | locker_t | ---------- |-----------------| | message_t(1) | |-----------------| | message_t(2) | | ...... | | message_t(n) | \-----------------/ - Function: int mailbox_append_message (mailbox_t MBOX, message_t MESSAGE) The MESSAGE is appended to the mailbox MBOX. The return value is `0' on success and a code number on error conditions: `MU_ERROR_INVALID_PARAMETER' MBOX is null or MESSAGE is invalid. - Function: int mailbox_close (mailbox_t MBOX) The stream attach to MBOX is closed. The return value is `0' on success and a code number on error conditions: `MU_ERROR_INVALID_PARAMETER' MBOX is null. - Function: int mailbox_create (mailbox_t *PMBOX, const char *NAME) The function `mailbox_create' allocates and initializes PMBOX. The concrete mailbox type instantiate is based on the scheme of the url NAME. The return value is `0' on success and a code number on error conditions: `MU_ERR_OUT_PTR_NULL' The pointer PMBOX supplied is NULL. `MU_ERR_NO_HANDLER' The url NAME supplied is invalid or not supported. `EINVAL' `ENOMEM' Not enough memory to allocate resources. - Function: int mailbox_create_default (mailbox_t *PMBOX, const char *NAME) Create a mailbox with `mailbox_create ()' based on the environment variable _$MAIL_ or the string formed by __PATH_MAILDIR_/USER" or _$LOGNAME_ if USER is null, - Function: void mailbox_destroy (mailbox_t *PMBOX) Destroys and releases resources held by PMBOX. - Function: int mailbox_expunge (mailbox_t MBOX) All messages marked for deletion are removed. The return value is `0' on success and a code number on error conditions: `MU_ERROR_INVALID_PARAMETER' MBOX is null. - Function: int mailbox_get_folder (mailbox_t MBOX, folder_t *FOLDER) Get the FOLDER. The return value is `0' on success and a code number on error conditions: `MU_ERROR_INVALID_PARAMETER' MBOX is null. - Function: int mailbox_get_debug (mailbox_t MBOX, debug_t *DEBUG) Get a debug object. The return value is `0' on success and a code number on error conditions: `MU_ERROR_INVALID_PARAMETER' MBOX is null. `ENOMEM' - Function: int mailbox_get_locker (mailbox_t MBOX, locker_t *PLOCKER) Return the LOCKER object. The return value is `0' on success and a code number on error conditions: `MU_ERROR_INVALID_PARAMETER' MBOX is null. - Function: int mailbox_get_message (mailbox_t MBOX, size_t MSGNO, message_t *PMESSAGE) Retrieve message number MSGNO, PMESSAGE is allocated and initialized. The return value is `0' on success and a code number on error conditions: `MU_ERROR_INVALID_PARAMETER' MBOX is null or MSGNO is invalid. `ENOMEM' Not enough memory. - Function: int mailbox_get_observable (mailbox_t mbox MBOX, observable_t*OBSERVABLE) Get the observable object. The return value is `0' on success and a code number on error conditions: `MU_ERROR_INVALID_PARAMETER' MBOX is null. `ENOMEM' Not enough memory. - Function: int mailbox_get_property (mailbox_t MBOX, property_t *PROPERTY) Get the property object. The return value is `0' on success and a code number on error conditions: `MU_ERROR_INVALID_PARAMETER' MBOX is null. `ENOMEM' - Function: int mailbox_get_size (mailbox_t MBOX, off_t *PSIZE) Gives the MBOX size. The return value is `0' on success and a code number on error conditions: `MU_ERROR_INVALID_PARAMETER' MBOX is null. - Function: int mailbox_get_stream (mailbox_t MBOX, stream_t *PSTREAM) The mailbox stream is put in PSTREAM. The return value is `0' on success and a code number on error conditions: `MU_ERROR_INVALID_PARAMETER' MBOX is invalid or PSTREAM is NULL. - Function: int mailbox_get_ticket (mailbox_t MBOX, ticket_t TICKET) The return value is `0' on success and a code number on error conditions: `MU_ERROR_INVALID_PARAMETER' MBOX is null. - Function: int mailbox_get_url (mailbox_t MBOX, url_t *PURL) Gives the constructed URL. The return value is `0' on success and a code number on error conditions: `MU_ERROR_INVALID_PARAMETER' MBOX is null. - Function: int mailbox_is_modified (mailbox_t MBOX) Check if the mailbox been modified by an external source. The return value is `0' on success and a code number on error conditions: `MU_ERROR_INVALID_PARAMETER' MBOX is null. - Function: int mailbox_message_unseen (mailbox_t MBOX, size_t *PNUMBER); Give the number of first unseen message in MBOX. The return value is `0' on success and a code number on error conditions: `MU_ERROR_INVALID_PARAMETER' MBOX is null. - Function: int mailbox_messages_count (mailbox_t MBOX, size_t *PNUMBER); Give the number of messages in MBOX. The return value is `0' on success and a code number on error conditions: `MU_ERROR_INVALID_PARAMETER' MBOX is null. - Function: int mailbox_messages_recent (mailbox_t MBOX, size_t *PNUMBER); Give the number of recent messages in MBOX. The return value is `0' on success and a code number on error conditions: `MU_ERROR_INVALID_PARAMETER' MBOX is null. - Function: int mailbox_open (mailbox_t MBOX, int FLAG) A connection is open, if no stream was provided, a stream is created based on the MBOX type. The FLAG can be OR'ed. See `stream_create' for FLAG's description. The return value is `0' on success and a code number on error conditions: `EAGAIN' `EINPROGRESS' Operation in progress. `EBUSY' Resource busy. `MU_ERROR_INVALID_PARAMETER' MBOX is null or flag is invalid. `ENOMEM' Not enough memory. - Function: int mailbox_scan (mailbox_t MBOX, size_t MSGNO, size_t *PCOUNT); Scan the mailbox for new messages starting at message MSGNO. The return value is `0' on success and a code number on error conditions: `MU_ERROR_INVALID_PARAMETER' MBOX is null. `ENOMEM' Not enough memory. - Function: int mailbox_set_locker (mailbox_t MBOX, locker_t LOCKER) Set the type of locking done by the MBOX. The return value is `0' on success and a code number on error conditions: `MU_ERROR_INVALID_PARAMETER' MBOX is null. - Function: int mailbox_set_stream (mailbox_t MBOX, stream_t STREAM) Set the STREAM connection to use for the mailbox. The return value is `0' on success and a code number on error conditions: `MU_ERROR_INVALID_PARAMETER' MBOX or STREAM is NULL. - Function: int mailbox_set_ticket (mailbox_t MBOX, ticket_t TICKET) The TICKET will be set on the `auth_t' object on creation. The return value is `0' on success and a code number on error conditions: `MU_ERROR_INVALID_PARAMETER' MBOX is null. - Function: int mailbox_uidnext (mailbox_t MBOX, size_t *PNUMBER); Give the next predicted uid for MBOX. The return value is `0' on success and a code number on error conditions: `MU_ERROR_INVALID_PARAMETER' MBOX is null. - Function: int mailbox_uidvalidity (mailbox_t MBOX, size_t *PNUMBER); Give the uid validity of MBOX. The return value is `0' on success and a code number on error conditions: `MU_ERROR_INVALID_PARAMETER' MBOX is null. Mailer ====== `/* Prefix _mailer__ is reserved */' `#include ' The API is still changing. - Function: int mailer_create (mailer_t *, const char *) - Function: void mailer_destroy (mailer_t *) - Function: int mailer_open (mailer_t, int flags) - Function: int mailer_close (mailer_t) - Function: int mailer_send_message (mailer_t MAILER, message_t MSG, address_t FROM, address_t TO); If from is not NULL, it must contain a single fully qualified RFC2822 email address which will be used as the envelope from address. This is the address to which delivery status notifications are sent, so it never matters what it is set to until it REALLY matters. This is equivalent to sendmail's -F flag. The default for FROM is provided by the specific mailer. If to is not NULL, then the message will be sent to the list of addresses that it specifies. The default for TO is to use the contents of the standard "To:", "Cc:", and "Bcc:" fields, this is equivalent to sendmail's -T flag. Note: the previous implementation of mailer_send_message() was equivalent to having both FROM and TO be NULL. - Function: int mailer_get_property (mailer_t, property_t *) - Function: int mailer_get_stream (mailer_t, stream_t *) - Function: int mailer_set_stream (mailer_t, stream_t) - Function: int mailer_get_debug (mailer_t, debug_t *) - Function: int mailer_set_debug (mailer_t, debug_t) - Function: int mailer_get_observable (mailer_t, observable_t *) - Function: int mailer_get_url (mailer_t, url_t *) Some usage notes. ----------------- Some possible use cases the API must support are: - original submission 1 - fill in header addresses 2 - mailer_send_message(mailer, msg, NULL, NULL); - from will be filled in if missing, - bcc's will be deleted before delivery to a non-bcc address, - message-id and date will be added, if missing, - a to: or apparently-to: will be added if non is present (for RFC compliance) - MTA-style .forward ( and sieve-style redirect ) 1 - get the envelope from of the message to be forwarded 2 - mailer_send_message(mailer, msg, from, to) - MUA-style bounce 1 - add Resent-[to,from,....] 2 - mailer_send_message(mailer, msg, NULL, to) - DSN "bounce" 1 - compose DSN 2 - mailer_deliver(mailer, msg, address_t( "<>" ), to) Don't want mail loops, so the null but valid SMTP address of <> is the envelope from. The sendmail mailer. -------------------- /sbin/sendmail isn't always sendmail... sometimes its a sendmail-compatible wrapper, so assume /sbin/sendmail understands only a recipient list, -f and -oi, these seem to be pretty basic. Cross fingers. Pipe to "/sbin/sendmail -oi [-f from] [to...]", supplying -f if there was a from, and supplying the recipient list from the to (if there is no recipient list, assume it will read the message contents for the recipients). Note: since the stdout and stderr of sendmail is closed, we have no way of ever giving feedback on failure. Also, what should the return code be from mailer_send_message() when sendmail returns 1? 1 maps to EPERM, which is less than descriptive! The SMTP mailer. ---------------- This mailer does NOT canonicalize the message. This must be done before sending the message, or it may be assumed that the MTA will do so. It does blind out the Bcc: header before sending, though. Note: mutt always puts the recipient addresses on the command line, even bcc ones, do we strip the bcc before forwarding with SMTP? Non-RFC822 addresses. --------------------- An address that has no domain is not and RFC822 email address. What do I do with them? Should the user of the API be responsible for determining what is mean by email to "john" means? Or should the be able to configure sendmail to decide globally what this means. If so, we can pass the address to sendmail, but we have to decide for SMTP! So, right now these addresses are rejected. This could be changed. Message ======= `#include ' `/* Prefix _message__ is reserve */' The `message_t' object is a convenient way to manipulate messages. It encapsulates the `envelope_t', the `header_t' and the `body_t'. mailbox_t __________ message_t (message[1]) +------>+-----------------------+ ---------- | | envelope_t | (message[2]) | |-----------------------| ---------- | | header_t | (message[3])--------+ |-----------------------| ---------- | body_t | (message[n]) |-----------------------| ---------- | attribute_t | |-----------------------| | stream_t | +-----------------------+ - Function: void message_create (message_t *MSG, void *OWNER) - Function: void message_destroy (message_t *MSG, void *OWNER) The resources allocate for MSG are freed. - Function: int message_get_header (message_t MSG, header_t *PHEADER) Retrieve MSG header. - Function: int message_set_header (message_t MSG, header_t HEADER, void *OWNER) - Function: int message_get_body (message_t MSG, body_t *PBODY) - Function: int message_set_body (message_t MSG, body_t BODY, void *OWNER) - Function: int message_is_multipart (message_t MSG, int *PMULTI) Set *PMULTI to non-zero value if MSG is multi-part. - Function: int message_get_num_parts (message_t MSG, size_t *nparts) - Function: int message_get_part (message_t MSG, size_t part, message_t *msg) - Function: int message_get_stream (message_t MSG, stream_t *PSTREAM) - Function: int message_set_stream (message_t MSG, stream_t STREAM,void *OWNER ) - Function: int message_get_attribute (message_t MSG, attribute_t *PATTRIBUTE) - Function: int message_set_attribute (message_t MSG, attribute_t ATTRIBUTE, void *owner) - Function: int message_get_envelope (message_t MSG, envelope_t *penvelope) - Function: int message_set_envelope (message_t MSG, envelope_t envelope, void *OWNER) - Function: int message_get_uid (message_t MSG, size_t *UID) - Function: int message_get_uidl (message_t MSG, char *BUFFER, size_t BUFLEN, size_t *PWRITEN) - Function: int message_set_uidl (message_t MSG, int (*_GET_UIDL)(message_t, char *, size_t, size_t *), void *OWNER) - Function: int message_get_observable (message_t MSG, observable_t *OBSERVABLE) - Function: int message_create_attachment (const char *CONTENT_TYPE, const char *ENCODING, const char *FILENAME, message_t *NEWMSG) - Function: int message_save_attachment (message_t MSG, const char *FILENAME, void **DATA) - Function: int message_encapsulate (message_t MSG, message_t *NEWMSG, void **DATA) - Function: int message_unencapsulate (message_t MSG, message_t *NEWMSG, void **DATA); Envelope ======== `/* Prefix _envelope__ is reserved */' `#include ' - Function: int envelope_date (envelope_t, char *, size_t, size_t *); Get the date that the message was delivered to the mailbox, in something close to ANSI ctime() format: Mon Jul 05 13:08:27 1999. - Function: int envelope_sender (envelope_t, char *, size_t, size_t *); Get the address that this message was reportedly received from. This would be the "mail from" argument if the message was delivered or received via SMTP, for example. - Function: int envelope_get_message (envelope_t, message_t *); - Function: int envelope_create (envelope_t *, void *); Primarily for internal use. - Function: void envelope_destroy (envelope_t *, void *); Primarily for internal use. - Function: int envelope_set_sender (envelope_t, int (*_sender) __P ((envelope_t, char *, size_t, size_t*)), void *); Primarily for internal use. The implementation of envelope_t depends on the mailbox type, this allows the function which actually gets the sender to be set by the creator of an envelope_t. - Function: int envelope_set_date (envelope_t, int (*_date) __P ((envelope_t, char *, size_t, size_t *)), void *); Primarily for internal use. The implementation of envelope_t depends on the mailbox type, this allows the function which actually gets the date to be set by the creator of an envelope_t. Headers ======= `/* Prefix _header__ is reserved */' `#include ' So far we plan support for RFC822 and plan for RFC1522. with RFC1522 non ASCII characters will be encoded. - Function: int header_create (header_t *HDR, const char *BLURB, size_t LEN, void *OWNER) Initialize a HDR to a supported type. If BLURB is not NULL, it is parsed. - Function: void header_destroy (header_t *HDR, void *OWNER) The resources allocated for HDR are freed. - Function: int header_set_value (header_t HDR, const char *FN, const char *FV, size_t n, int REPLACE) Set the field-name FN to field-value FV of size N in HDR. If REPLACE is non-zero the initial value is replaced, if zero it is appended. Some basic macros are already provided for rfc822. `MU_HEADER_RETURN_PATH' Return-Path `MU_HEADER_RECEIVED' Received `MU_HEADER_DATE' Date `MU_HEADER_FROM' From `MU_HEADER_RESENT_FROM' Resent-From `MU_HEADER_SUBJECT' Subject `MU_HEADER_SENDER' Sender `MU_HEADER_RESENT_SENDER' Resent-SENDER `MU_HEADER_TO' To `MU_HEADER_RESENT_TO' Resent-To `MU_HEADER_CC' Cc `MU_HEADER_RESENT_CC' Resent-Cc `MU_HEADER_BCC' Bcc `MU_HEADER_RESENT_BCC' Resent-Bcc `MU_HEADER_REPLY_TO' Reply-To `MU_HEADER_RESENT_REPLY_TO' Resent-Reply-To `MU_HEADER_MESSAGE_ID' Message-ID `MU_HEADER_RESENT_MESSAGE_ID' Resent-Message-ID `MU_HEADER_IN_REPLY_TO' In-Reply-To `MU_HEADER_ENCRYPTED' Encrypted `MU_HEADER_PRECEDENCE' Precedence `MU_HEADER_STATUS' Status `MU_HEADER_CONTENT_LENGTH' Content-Length `MU_HEADER_CONTENT_TYPE' Content-Type `MU_HEADER_MIME_VERSION' MIME-Version - Function: int header_get_value (header_t HDR, const char *FN, char *FV, size_t LEN, size_t *N) Value of field-name FN is returned in buffer FV of size LEN. The number of bytes written is put in N. - Function: int header_aget_value (header_t HDR, const char *FN, char **FV) The value is allocated. - Function: int header_get_stream (header_t HDR, stream_t *PSTREAM) - Function: int header_set_size (header_t HDR, size_t *SIZE) - Function: int header_set_lines (header_t HDR, size_t *LPINES) Body ==== `/* Prefix _body__ is reserved */' `#include ' - Function: int body_create (body_t *BODY, void *OWNER) Initialize an object BDY. - Function: void body_destroy (body_t *PBODY) The resources allocate are release. - Function: int body_get_stream (body_t BODY, stream_t *PSTREAM) - Function: int body_set_stream (body_t BODY, stream_t STREAM, void *OWNER) - Function: int body_get_filename __P ((body_t BODY, char *BUFFER, size_tBUFLEN, size_t *PWRITEN) - Function: int body_set_filename (body_t BODY, const char*BUFFER) - Function: int body_size (body_t BODY, size_t*PSIZE) - Function: int body_lines (body_t BODY, size_t *PLINES) Attribute ========= `/* Prefix _attribute__ is reserved */' `#include ' - Function: int attribute_create (attribute_t *PATTRIBUTE) - Function: void attribute_destroy (attribute_t *PATTRIBUTE) - Function: int attribute_is_seen (attribute_t ATTRIBUTE) - Function: int attribute_is_answered (attribute_t ATTRIBUTE) - Function: int attribute_is_flagged (attribute_t ATTRIBUTE) - Function: int attribute_is_deleted (attribute_t ATTRIBUTE) - Function: int attribute_is_draft (attribute_t ATTRIBUTE) - Function: int attribute_is_recent (attribute_t ATTRIBUTE) - Function: int attribute_is_read (attribute_t ATTRIBUTE) - Function: int attribute_set_seen (attribute_t ATTRIBUTE) - Function: int attribute_set_answered (attribute_t ATTRIBUTE) - Function: int attribute_set_flagged (attribute_t ATTRIBUTE) - Function: int attribute_set_deleted (attribute_t ATTRIBUTE) - Function: int attribute_set_draft (attribute_t ATTRIBUTE) - Function: int attribute_set_recent (attribute_t ATTRIBUTE) - Function: int attribute_set_read (attribute_t ATTRIBUTE) - Function: int attribute_unset_seen (attribute_t ATTRIBUTE) - Function: int attribute_unset_answered (attribute_t ATTRIBUTE) - Function: int attribute_unset_flagged (attribute_t ATTRIBUTE) - Function: int attribute_unset_deleted (attribute_t ATTRIBUTE) - Function: int attribute_unset_draft (attribute_t ATTRIBUTE) - Function: int attribute_unset_recent (attribute_t ATTRIBUTE) - Function: int attribute_unset_read (attribute_t ATTRIBUTE) - Function: int attribute_is_equal (attribute_t ATT1, attribute_t ATT2) - Function: int attribute_copy (attribute_t DST, attribute_t SRC) - Function: int string_to_attribute (const char *BUF, attribute_t *PATTR) - Function: int attribute_to_string (attribute_t ATTR, char *BUF, size_t LEN, size_t *PWRITEN) Stream ====== `#include ' These generic flags are interpreted as appropriate to the specific streams. `MU_STREAM_READ' The stream is open read only. `MU_STREAM_WRITE' The stream is open write only. `MU_STREAM_RDWR' The stream is open read and write. `MU_STREAM_APPEND' The stream is open in append mode for writing. `MU_STREAM_CREAT' The stream open will create the underlying resource (such as a file) if it doesn't exist already. `MU_STREAM_NONBLOCK' The stream is set non blocking. `MU_STREAM_NO_CHECK' Stream is destroyed without checking for the owner. `MU_STREAM_NO_CLOSE' Stream doesn't close it's underlying resource when it is closed or destroyed. - Function: int file_stream_create (stream_t *PSTREAM, const char *FILENAME, int FLAGS) - Function: int tcp_stream_create (stream_t *PSTREAM, const char *HOST, int PORT, int FLAGS) - Function: int mapfile_stream_create (stream_t *PSTREAM, const char *FILENAME, int FLAGS) - Function: int memory_stream_create (stream_t *PSTREAM, const char *FILENAME, int FLAGS) - Function: int encoder_stream_create (stream_t *PSTREAM, stream_t IOSTREAM, const char *ENCODING) - Function: int decoder_stream_create (stream_t *PSTREAM, stream_t IOSTREAM, const char *ENCODING) - Function: int stdio_stream_create (stream_t *PSTREAM, FILE* STDIO, int FLAGS) If MU_STREAM_NO_CLOSE is specified, fclose() will not be called on STDIO when the stream is closed. - Function: void stream_destroy (stream_t *PSTREAM, void *OWNER) - Function: int stream_open (stream_t STREAM) - Function: int stream_close (stream_t STREAM) - Function: int stream_is_seekable (stream_t STREAM) - Function: int stream_get_fd (stream_t STREAM, int *PFD) - Function: int stream_read (stream_t STREAM, char *BUFFER, size_t BUFLEN, off_t OFFSET, size_t *PWRITEN) - Function: int stream_readline (stream_t STREAM, char *BUFFER, size_t BUFLEN, off_t OFFSET, size_t *PWRITEN) - Function: int stream_size (stream_t STREAM, off_t *PSIZE) - Function: int stream_truncate (stream_t STREAM, off_t SIZE) - Function: int stream_write (stream_t STREAM, const char *BUFFER, size_t BUFLEN, off_t OFFSET, size_t *PWRITEN) - Function: int stream_setbufsiz (stream_t STREAM, size_t SIZE) - Function: int stream_flush (stream_t STREAM) These functions will typically only be useful to implementors of streams. - Function: int stream_create (stream_t *PSTREAM, int FLAGS, void *OWNER) Used to implement a new kind of stream. - Function: int stream_get_flags (stream_t STREAM, int *PFLAGS) - Function: int stream_get_state (stream_t STREAM, int *PSTATE) `MU_STREAM_STATE_OPEN' Last action was `stream_open'. `MU_STREAM_STATE_READ' Last action was `stream_read' or `stream_readline'. `MU_STREAM_STATE_WRITE' Last action was `stream_write'. `MU_STREAM_STATE_CLOSE' Last action was `stream_close'. An example using `tcp_stream_create' to make a simple web client: /* This is an example program to illustrate the use of stream functions. It connects to a remote HTTP server and prints the contents of its index page */ #include #include #include #include #include #include const char *wbuf = "GET / HTTP/1.0\r\n\r\n"; char rbuf[1024]; int main () { int ret, off = 0, fd; stream_t stream; size_t nb; fd_set fds; ret = tcp_stream_create (&stream, "www.gnu.org", 80, MU_STREAM_NONBLOCK); if (ret != 0) { mu_error ( "tcp_stream_create: %s\n", mu_errstring (ret)); exit (EXIT_FAILURE); } connect_again: ret = stream_open (stream); if (ret != 0) { if (ret == EAGAIN) { ret = stream_get_fd (stream, &fd); if (ret != 0) { mu_error ( "stream_get_fd: %s\n", mu_errstring (ret)); exit (EXIT_FAILURE); } FD_ZERO (&fds); FD_SET (fd, &fds); select (fd + 1, NULL, &fds, NULL, NULL); goto connect_again; } mu_error ( "stream_open: %s\n", mu_errstring (ret)); exit (EXIT_FAILURE); } ret = stream_get_fd (stream, &fd); if (ret != 0) { mu_error ( "stream_get_fd: %s\n", mu_errstring (ret)); exit (EXIT_FAILURE); } write_again: ret = stream_write (stream, wbuf + off, strlen (wbuf), 0, &nb); if (ret != 0) { if (ret == EAGAIN) { FD_ZERO (&fds); FD_SET (fd, &fds); select (fd + 1, NULL, &fds, NULL, NULL); off += nb; goto write_again; } mu_error ( "stream_write: %s\n", mu_errstring (ret)); exit (EXIT_FAILURE); } if (nb != strlen (wbuf)) { mu_error ( "stream_write: %s\n", "nb != wbuf length"); exit (EXIT_FAILURE); } do { ret = stream_read (stream, rbuf, sizeof (rbuf), 0, &nb); if (ret != 0) { if (ret == EAGAIN) { FD_ZERO (&fds); FD_SET (fd, &fds); select (fd + 1, &fds, NULL, NULL, NULL); } else { mu_error ( "stream_read: %s\n", mu_errstring (ret)); exit (EXIT_FAILURE); } } write (2, rbuf, nb); } while (nb || ret == EAGAIN); ret = stream_close (stream); if (ret != 0) { mu_error ( "stream_close: %s\n", mu_errstring (ret)); exit (EXIT_FAILURE); } stream_destroy (&stream, NULL); exit (EXIT_SUCCESS); } Iterator ======== `/* Prefix _iterator__ is reserved */' `#include ' - Function: int iterator_create (iterator_t *) - Function: void iterator_destroy (iterator_t *) - Function: int iterator_first (iterator_t) - Function: int iterator_next (iterator_t) - Function: int iterator_current (iterator_t, void **pitem) - Function: int iterator_is_done (iterator_t) Authenticator ============= `/* Prefix _auth__ is reserved */' `#include ' There are many ways to authenticate to a server. To be flexible the authentication process is provided by two objects `auth_t' and `ticket_t'. The `auth_t' can implement different protocol like APOP, MD5-AUTH, One Time Passwd etc .. By default if a mailbox does not understand or know how to authenticate it falls back to user/passwd authentication. The `ticket_t' is a way for Mailboxes and Mailers provide a way to authenticate when the URL does not contain enough information. The default action is to call the function `auth_authenticate' which will get the _user_ and _passwd_ if not set, this function can be overridden by a custom method. - Function: int auth_create (auth_t *PAUTH, void *OWNER) - Function: void auth_destroy (auth_t *PAUTH, void *OWNER) - Function: int auth_prologue (auth_t AUTH) - Function: int auth_authenticate (auth_t AUTH, char **USER, char **PASSWD) - Function: int auth_epilogue (auth_t AUTH) A simple example of an authenticate function: #include #include #include int my_authenticate (auth_t auth, char **user, char **passwd) { char u[128] = ""; char p[128] = ""; /* prompt the user name */ printf ("User: "); fflush (stdout); fgets (u, sizeof (u), stdin); u[strlen (u) - 1] = '\0'; /* nuke the trailing NL */ /* prompt the passwd */ printf ("Passwd: "); fflush (stdout); echo_off (); fgets (p, sizeof(p), stdin); echo_on (); p[strlen (p) - 1] = '\0'; /* duplicate */ *user = strdup (u); *passwd = strdup (p); return 0; } Address ======= `/* Prefix _address__ is reserved */' `#include ' The Internet address format is defined in RFC 822. RFC 822 has been updated, and is now superceeded by RFC 2822, which makes some corrections and clarifications. References to RFC 822 here apply equally to RFC 2822. The RFC 822 format is more flexible than many people realize, here is a quick summary of the syntax this parser implements, see RFC 822 for the details. "[]" pairs mean "optional", "/" means "one or the other", and double-quoted characters are literals. addr-spec = local-part "d"omain mailbox = addr-spec ["(" display-name ")"] / [display-name] "<" [route] addr-spec ">" mailbox-list = mailbox ["," mailbox-list] group = display-name ":" [mailbox-list] ";" address = mailbox / group / unix-mbox address-list = address ["," address-list] unix-mbox is a non-standard extension meant to deal with the common practice of using user names as addresses in mail utilities. It allows addresses such as "root" to be parsed correctly. These are NOT valid internet email addresses, they must be qualified before use. Several address functions have a set of common arguments with consistent semantics, these are described here to avoid repetition. Since an address-list may contain multiple addresses, they are accessed by a *one-based* index number, NO. The index is one-based because pop, imap, and other message stores commonly use one-based counts to access messages and attributes of messages. If LEN is greater than `0' it is the length of the buffer BUF, and as much of the component as possible will be copied into the buffer. The buffer will be null terminated. The size of a particular component may be queried by providing `0' for the LEN of the buffer, in which case the buffer is optional. In this case, if N is provided *N is assigned the length of the component string. - Data Type: address_t The `address_t' object is used to hold information about a parsed RFC822 address list, and is an opaque data structure to the user. Functions are provided to retrieve information about an address in the address list. - Function: int address_create (address_t *ADDR, const char *STRING) This function allocates and initializes ADDR by parsing the RFC822 address-list STRING. The return value is `0' on success and a code number on error conditions: `EINVAL' Invalid usage, usually a required argument was `null'. `ENOMEM' Not enough memory to allocate resources. `ENOENT' Invalid RFC822 syntax, parsing failed. - Function: int address_createv (address_t *ADDR, const char *SV, size_t LEN) This function allocates and initializes ADDR by parsing the array of pointers to RFC822 address-lists in SV. If LEN is `-1', then SV must be null-terminated in the fashion of ARGV, otherwise LEN is the length of the array. The return value is `0' on success and a code number on error conditions: `EINVAL' Invalid usage, usually a required argument was `null'. `ENOMEM' Not enough memory to allocate resources. `ENOENT' Invalid RFC822 syntax, parsing failed. - Function: void address_destroy (address_t *ADDR) The ADDR is destroyed. - Function: int address_get_email (address_t *ADDR, size_t NO, char* BUF, size_t LEN, size_t* N) Accesses the NOth email address component of the address list. This address is the plain email address, correctly quoted, suitable for using in an smtp dialog, for example, or as the address part of a contact book entry. Note that the entry may be valid, but be a group name. In this case success is returned, but the length of the address is `0'. The return value is `0' on success and a code number on error conditions: `EINVAL' Invalid usage, usually a required argument was `null'. `ENOENT' The index NO is outside of the range of available addresses. - Function: int address_aget_email (address_t *ADDR, size_t NO, char** BUFP) As above, but mallocs the email address, if present, and write a pointer to it into BUFP. BUFP will be `NULL' if there is no email address to return. The return value is `0' on success and a code number on error conditions: `EINVAL' Invalid usage, usually a required argument was `null'. `ENOENT' The index NO is outside of the range of available addresses. - Function: int address_get_personal (address_t *ADDR, size_t NO, char* BUF, size_t LEN, size_t* N) Accesses the display-name describing the NOth email address. This display-name is optional, so may not be present. If it is not present, but there is an RFC822 comment after the address, that comment will be returned as the personal phrase, as this is a common usage of the comment even though it is not defined in the internet mail standard. A group is a kind of a special case. It has a display-name, followed by an optional mailbox-list. The display-name will be allocated an address all it's own, but all the other elements (local-part, domain, etc.) will be zero-length. So "a group: ;" is valid, will have a count of 1, but address_get_email(), and all the rest, will return zero-length output. The return value is `0' on success and a code number on error conditions: `EINVAL' Invalid usage, usually a required argument was `null'. `ENOENT' The index NO is outside of the range of available addresses. - Function: int address_get_comments (address_t *ADDR, size_t NO, char* BUF, size_t LEN, size_t* N) Accesses the comments extracted while parsing the NOth email address. These comments have no defined meaning, and are not currently collected. The return value is `0' on success and a code number on error conditions: `EINVAL' Invalid usage, usually a required argument was `null'. `ENOENT' The index NO is outside of the range of available addresses. - Function: int address_get_email (address_t *ADDR, size_t NO, char* BUF, size_t LEN, size_t* N) Accesses the email addr-spec extracted while parsing the NOth email address. This will be `0' length for a unix-mbox. The return value is `0' on success and a code number on error conditions: `EINVAL' Invalid usage, usually a required argument was `null'. `ENOENT' The index NO is outside of the range of available addresses. - Function: int address_get_local_part (address_t *ADDR, size_t NO, char* BUF, size_t LEN, size_t* N) Accesses the local-part of an email addr-spec extracted while parsing the NOth email address. The return value is `0' on success and a code number on error conditions: `EINVAL' Invalid usage, usually a required argument was `null'. `ENOENT' The index NO is outside of the range of available addresses. - Function: int address_get_domain (address_t *ADDR, size_t NO, char* BUF, size_t LEN, size_t* N) Accesses the domain of an email addr-spec extracted while parsing the NOth email address. This will be `0' length for a unix-mbox. The return value is `0' on success and a code number on error conditions: `EINVAL' Invalid usage, usually a required argument was `null'. `ENOENT' The index NO is outside of the range of available addresses. - Function: int address_get_route (address_t *ADDR, size_t NO, char* BUF, size_t LEN, size_t* N) Accesses the route of an email addr-spec extracted while parsing the NOth email address. This is a rarely used RFC822 address syntax, but is legal in SMTP as well. The entire route is returned as a string, those wishing to parse it should look at . The return value is `0' on success and a code number on error conditions: `EINVAL' Invalid usage, usually a required argument was `null'. `ENOENT' The index NO is outside of the range of available addresses. - Function: int address_is_group (address_t *ADDR, size_t NO, size_t LEN, int* YES) Sets *YES to `1' if this address is just the name of a group, `0' otherwise. This is faster than checking if the address has a non-zero length personal, and a zero-length local_part and domain. YES can be `null', though that doesn't serve much purpose other than determining that NO refers to an address. Currently, there is no way to determine the end of the group. The return value is `0' on success and a code number on error conditions: `EINVAL' Invalid usage, usually a required argument was `null'. `ENOENT' The index NO is outside of the range of available addresses. - Function: int address_to_string (address_t *ADDR, char* BUF, size_t LEN, size_t* N) Returns the entire address list as a single RFC822 formatted address list. The return value is `0' on success and a code number on error conditions: `EINVAL' Invalid usage, usually a required argument was `null'. `ENOMEM' Not enough memory to allocate resources. - Function: int address_get_count (address_t ADDR, size_t* COUNT) Returns a count of the addresses in the address list. If ADDR is `null', the count is `0'. If COUNT is not `null', the count will be written to *COUNT. The return value is `0'. Example ======= #include #include #include #include #include #include #define EPARSE ENOENT static int parse (const char *str) { size_t no = 0; size_t pcount = 0; int status; char buf[BUFSIZ]; address_t address = NULL; mu_set_user_email_domain ("localhost"); status = address_create (&address, str); address_get_count (address, &pcount); if (status) { printf ("%s=> error %s\n\n", str, mu_errname (status)); return 0; } else { printf ("%s=> pcount %lu\n", str, (unsigned long) pcount); } for (no = 1; no <= pcount; no++) { size_t got = 0; int isgroup; address_is_group (address, no, &isgroup); printf ("%lu ", (unsigned long) no); if (isgroup) { address_get_personal (address, no, buf, sizeof (buf), &got); printf ("group <%s>\n", buf); } else { address_get_email (address, no, buf, sizeof (buf), 0); printf ("email <%s>\n", buf); } address_get_personal (address, no, buf, sizeof (buf), &got); if (got && !isgroup) printf (" personal <%s>\n", buf); address_get_comments (address, no, buf, sizeof (buf), &got); if (got) printf (" comments <%s>\n", buf); address_get_local_part (address, no, buf, sizeof (buf), &got); if (got) { printf (" local-part <%s>", buf); address_get_domain (address, no, buf, sizeof (buf), &got); if (got) printf (" domain <%s>", buf); printf ("\n"); } address_get_route (address, no, buf, sizeof (buf), &got); if (got) printf (" route <%s>\n", buf); } address_destroy (&address); printf ("\n"); return 0; } static int parseinput (void) { char buf[BUFSIZ]; while (fgets (buf, sizeof (buf), stdin) != 0) { buf[strlen (buf) - 1] = 0; parse (buf); } return 0; } int main (int argc, const char *argv[]) { argc = 1; if (!argv[argc]) { return parseinput (); } for (; argv[argc]; argc++) { if (strcmp (argv[argc], "-") == 0) { parseinput (); } else { parse (argv[argc]); } } return 0; } Locker ====== `/* Prefix _locker__ is reserved */' `#include ' - Function: int locker_create (locker_t * PLOCKER, char *FILENAME, size_t LEN, int FLAGS) - Function: void locker_destroy (locker_t * PLOCKER) - Function: int locker_lock (locker_t LOCKER, int FLAG) `MU_LOCKER_RDLOCK' `MU_LOCKER_WRLOCK' `MU_LOCKER_PID' `MU_LOCKER_FCNTL' `MU_LOCKER_TIME' - Function: int locker_touchlock (locker_t LOCKER) - Function: int locker_unlock (locker_t LOCKER) URL === A mailbox or a mailer can be described in a URL, the string will contain the necessary information to initialize `mailbox_t', or `mailer_t' properly. POP3 ---- The POP URL scheme contains a POP server, optional port number and the authentication mechanism. The general form is [;AUTH=]@][:]> or [:]@][:]> If _:port_ is omitted the default value is 110. Different forms of authentication can be specified with _;AUTH=type_. The special string _;AUTH=*_ indicates that the client will use a default scheme base on the capability of the server. For more complete information see `rfc2368'. IMAP ---- The IMAP URL scheme contains an IMAP server, optional port number and the authentication mechanism. The general form is [;AUTH=]]@[:port][/]> or [:]]@[:port][/]> If _:port_ is omitted the default value is 220. Different forms of authentication can be specified with _;AUTH=type_. The special string _;AUTH=*_ indicates that the client will use a default scheme base on the capability of the server. For more complete information see `rfc2192'. File ---- Local folder should be handle by this URL. It is preferable to let the mailbox recognize the type of mailbox and take the appropriate action. For MMDF, MH local mailboxes URLs are provided, but it is preferable to use and let the library figure out which one. Mailto ------ After setting a mailer, is used to tell the mailer where and to whom the message is for. Mailto can be used to generate short messages, for example to subscribe to mailing lists. For more complete information see `rfc2368'. URL functions ------------- Helper functions are provided to retrieve and set the _URL_ fields. - Function: int url_create (url_t *URL, const char *NAME) Create and the URL data structure, but do not parse it. - Function: void url_destroy (url_t *) Destroy the url and free it's resources. - Function: int url_parse (url_t URL) Parses the url, after calling this the get functions can be called. The syntax, condensed from RFC 1738, and extended with the ;auth= of RFC 2384 (for POP) and RFC 2192 (for IMAP) is: url = scheme ":" [ "//" [ user [ ( ":" password ) | ( ";auth=" auth ) ] "]" host [ ":" port ] [ ( "/" urlpath ) | ( "?" query ) ] ] This is a generalized URL syntax, and may not be exactly appropriate for any particular scheme. - Function: const char* url_to_string (const url_t URL) - Function: int url_get_scheme (const url_t URL, char *SCHEM, size_t LEN, size_t *N) - Function: int url_get_user (const url_t URL, char *USR, size_t LEN, size_t *N) - Function: int url_get_passwd (const url_t URL, char *PASSWD, size_t LEN, size_t *N) - Function: int url_get_host (const url_t URL, char *HOST, size_t LEN, size_t *N) - Function: int url_get_port (const url_t URL, long *PORT) - Function: int url_get_path (const url_t URL, char *PATH, size_t LEN, size_t *N) - Function: int url_get_query (const url_t URL, char *QUERY, size_tlen, size_t *N) - Function: char* url_decode (const char* STRING) Decodes an RFC 1738 % encoded string, returning the decoded string in allocated memory. If the string is not encoded, this degenerates to a strdup(). Example ======= #include #include #include #include int main () { char str[1024]; char buffer[1024]; long port = 0; int len = sizeof (buffer); url_t u = NULL; while (fgets (str, sizeof (str), stdin) != NULL) { int rc; str[strlen (str) - 1] = '\0'; /* chop newline */ if (strspn (str, " \t") == strlen (str)) continue; /* skip empty lines */ if ((rc = url_create (&u, str)) != 0) { fprintf (stderr, "url_create %s ERROR: [%d] %s", str, rc, mu_errstring (rc)); exit (1); } if ((rc = url_parse (u)) != 0) { printf ("%s => FAILED: [%d] %s\n", str, rc, mu_errstring (rc)); continue; } printf ("%s => SUCCESS\n", str); url_get_scheme (u, buffer, len, NULL); printf ("\tscheme <%s>\n", buffer); url_get_user (u, buffer, len, NULL); printf ("\tuser <%s>\n", buffer); url_get_passwd (u, buffer, len, NULL); printf ("\tpasswd <%s>\n", buffer); url_get_auth (u, buffer, len, NULL); printf ("\tauth <%s>\n", buffer); url_get_host (u, buffer, len, NULL); printf ("\thost <%s>\n", buffer); url_get_port (u, &port); printf ("\tport %ld\n", port); url_get_path (u, buffer, len, NULL); printf ("\tpath <%s>\n", buffer); url_get_query (u, buffer, len, NULL); printf ("\tquery <%s>\n", buffer); url_destroy (&u); } return 0; } Parse822 -- Functions for Parsing RFC 822 Headers ================================================= `/* Prefix _parse822__ is reserved */' `#include ' Internet Message Format, see Address node for the discussion. - Function: int parse822_address_list (address_t* a, const char* s) - Function: int parse822_mail_box (const char** p, const char* e, address_t* a) - Function: int parse822_group (const char** p, const char* e, address_t* a) - Function: int parse822_address (const char** p, const char* e, address_t* a) - Function: int parse822_route_addr (const char** p, const char* e, address_t* a) - Function: int parse822_route (const char** p, const char* e, char** route) - Function: int parse822_addr_spec (const char** p, const char* e, address_t* a) - Function: int parse822_unix_mbox (const char** p, const char* e, address_t* a) - Function: int parse822_local_part (const char** p, const char* e, char** local_part) - Function: int parse822_domain (const char** p, const char* e, char** domain) - Function: int parse822_sub_domain (const char** p, const char* e, char** sub_domain) - Function: int parse822_domain_ref (const char** p, const char* e, char** domain_ref) - Function: int parse822_domain_literal (const char** p, const char* e, char** domain_literal) - Function: int parse822_quote_string (char** quoted, const char* raw) - Function: int parse822_quote_local_part (char** quoted, const char* raw) - Function: int parse822_field_body (const char** p, const char *e, char** fieldbody) - Function: int parse822_field_name (const char** p, const char *e, char** fieldname) Authentication Library ********************** The functions from `libmailbox' library get user information from the system user database. The library `libmuauth' extends this functionality, allowing `libmailbox' functions to obtain information about a user from several places, like SQL database, etc. The method used is described in detail in *Note authentication::. This chapter contains a very succinct description of the underlying library mechanism. Data Types ========== - Data Type: mu_auth_fp This is a pointer to authentication or authorization data. It is defined as follows: typedef int (*mu_auth_fp) (void *RETURN_DATA, void *KEY, void *FUNC_DATA, void *CALL_DATA); Its arguments are: RETURN_DATA (1). Upon successful return authorization handler leaves in this memory location a pointer to the filled `mu_auth_data' structure with the user's information. For authentication handlers this argument is always `NULL' and should be ignored. KEY The search key value. Its actual type depends upon type of the handler. For authorization handlers it is `const char*' if the handler is called by `mu_get_auth_by_name()' and `uid_t *' if it is called by `mu_get_auth_by_uid()'. For authentication handlers it is always `struct mu_auth_data*' representing the user's data obtained by a previous call to a `mu_get_auth_by_...' function. FUNC_DATA Any data associated with this handler. CALL_DATA Any call specific data. This argument is not used at the moment. - Data Type: mu_auth_data The `mu_auth_data' is used to return the information about the user. It is similar to system `struct passwd', except that it is more mailutils-specific. Its definition is: struct mu_auth_data { /* These are from struct passwd */ char *name; /* user name */ char *passwd; /* user password */ uid_t uid; /* user id */ gid_t gid; /* group id */ char *gecos; /* real name */ char *dir; /* home directory */ char *shell; /* shell program */ /* */ char *mailbox; /* Path to the user's system mailbox */ int change_uid; /* Should the uid be changed? */ }; - Data Type: mu_auth_module The `mu_auth_module' structure contains full information about a libmuauth module. It is declared as follows: struct mu_auth_module { char *name; /* Module name */ struct argp *argp; /* Corresponding argp structure */ mu_auth_fp authenticate; /* Authentication function ... */ void *authenticate_data; /* ... and its specific data */ mu_auth_fp auth_by_name; /* Get user info by user name */ void *auth_by_name_data; /* ... and its specific data */ mu_auth_fp auth_by_uid; /* Get user info by user id */ void *auth_by_uid_data; /* ... and its specific data */ }; ---------- Footnotes ---------- (1) Actually it shoud have been `struct mu_auth_data** return_data'. This will be fixed in the next release Initializing the libmuauth ========================== - Function: void mu_auth_init (void) This function registers the command line capability "auth". It must be called after registering `libmuauth' modules and before calling `mu_agrp_parse()'. If an error occurs, this function prints diagnostic message and aborts the program. - Function: void MU_AUTH_REGISTER_ALL_MODULES (void) This macro registers all default modules and calls `mu_auth_init()'. Module Creation and Destruction =============================== - Function: int mu_auth_data_alloc (struct mu_auth_data **ptr, const char *name, const char *passwd, uid_t uid, gid_t gid, const char *gecos, const char *dir, const char *shell, const char *mailbox, int change_uid) Create a `mu_auth_data' structure and initialize it with the given values. Returns 0 on success and 1 otherwise. - Function: void mu_auth_data_free (struct mu_auth_data *PTR) Free the `mu_auth_data' structure allocated by a call to `mu_auth_data_alloc()'. - Function: void mu_auth_register_module (struct mu_auth_module *MOD) Register the module defined by the MOD argument. Obtaining Authorization Information =================================== - Function: int mu_auth_runlist (list_t FLIST, void *RETURN_DATA, void *KEY, void *CALL_DATA); The list is expected to contain `mu_auth_fp' pointers. Each of them is dereferenced and executed until either the list is exhausted or any of the functions returns non-zero, whichever occurs first. The RETURN_DATA and KEY arguments are passed as the first two parameters to the function (see the definition of `mu_auth_fp', notice the footnote), the `call_data' is passed as its last parameter. The function returns 0 if none of the functions from `list' succeeded, i.e. returned non-zero value. Otherwise it returns the return code from the succeeded function. - Function: struct mu_auth_data * mu_get_auth_by_name (const char *USERNAME) Search the information about given user by its username. Similar to system's `getpwnam' call). - Function: struct mu_auth_data * mu_get_auth_by_uid (uid_t UID) Search the information about given user by its uid. Similar to system's `getpwuid' call). - Function: int mu_authenticate (struct mu_auth_data *AUTH_DATA, char *PASS) Authenticate the user whose data are in AUTH_DATA using password PASS. Return 0 if the user is authenticated. Existing Modules ================ - Function: int mu_auth_nosupport (void *return_data, void *key, void *func_data, void *call_data); The "not-supported" module. Always returns `ENOSYS'. - Variable: mu_auth_system_module This module is always registered even if `libmuauth' is not linked. It performs usual authentication using system user database (`/etc/password' et al.) - Variable: mu_auth_generic_module This module is always registered even if `libmuauth' is not linked. Both its authorization handlers are `mu_auth_nosupport'. Its authentication handler computes the MD5 or DES hash over the supplied password with the seed taken from `passwd' member of its KEY argument. Then it compares the obtained hash with the `passwd' member itself and returns 1 if both strings match. - Variable: mu_auth_pam_module Implements PAM authentication. Both authorization handlers are `mu_auth_nosupport()'. - Variable: mu_auth_sql_module Implements authentication and authorization via MySQL database. The credentials for accessing the database are taken from global variables `sql_host', `sql_port', `sql_user', `sql_passwd' and `sql_db'. The SQL queries for retrieving user information from global variables `sql_getpwnam_query' and `sql_getpwuid_query'. The variable `sql_getpass_query' keeps the query used for retrieving user's password. *Note auth::, for information on command line options used to set these variables. - Variable: mu_auth_virtual_module Implements `mu_get_auth_by_name' method using virtual mail domains. Neither `mu_get_auth_by_uid' nor `mu_authenticate' is implemented. This module must be used together with `generic' module. Using Libmuauth in Your Programs ================================ To link your program against `libmuauth', obtain loader arguments by running `mailutils-config' as follows: mailutils-config --link auth *Note mailutils-config::, for more information about this utility. Here is a sample Makefile fragment: MU_LDFLAGS=`mailutils-config --link auth` MU_INCLUDES=`mailutils-config --include` myprog: myprog.c $(CC) -omyprog $(CFLAGS) $(MU_INCLUDES) myprog.c $(MU_LDFLAGS) If your program will be using only default modules provided by the library, then it will suffice to call `MU_AUTH_REGISTER_ALL_MODULES()' somewhere near the start of your program. As an example, consider the following code fragment (it is taken from the `imap4d' daemon): int main (int argc, char **argv) { struct group *gr; int status = EXIT_SUCCESS; state = STATE_NONAUTH; /* Starting state in non-auth. */ MU_AUTH_REGISTER_ALL_MODULES (); mu_argp_parse (&argp, &argc, &argv, 0, imap4d_capa, NULL, &daemon_param); ... Otherwise, if your program will use it's own modules, first register them with `mu_auth_register_module' and then call `mu_auth_init()', e.g.: struct mu_auth_module radius_module = { ... }; struct mu_auth_module ext_module = { ... }; int main (int argc, char **argv) { mu_auth_register_module (&radius_module); mu_auth_register_module (&ext_module); mu_auth_init (); ... These two approaches may be combined, allowing you to use both your modules and the ones provided by Mailutils. Consider the example below: int main (int argc, char **argv) { mu_auth_register_module (&radius_module); mu_auth_register_module (&ext_module); MU_AUTH_REGISTER_ALL_MODULES (); ... } Mailutils to Scheme interface ***************************** The library `libmu_scm' provides an interface between Mailutils and Guile, allowing to access the Mailutils functionality from a Scheme program. For more information about Guile, refer to *Note Overview: (guile)Top. For information about Scheme programming language, *Note Top: (r4rs)Top. Address Functions ================= - Scheme Function: mu-address-get-personal ADDRESS NUM Return personal part of an email address. - Scheme Function: mu-address-get-comments ADDRESS NUM - Scheme Function: mu-address-get-email ADDRESS NUM Return email part of an email address. - Scheme Function: mu-address-get-domain ADDRESS NUM Return domain part of an email address - Scheme Function: mu-address-get-local ADDRESS NUM Return local part of an email address. - Scheme Function: mu-address-get-count ADDRESS Return number of parts in email address. Mailbox Functions ================= - Scheme Function: mu-mailbox-open URL MODE Opens a mailbox specified by URL. - Scheme Function: mu-mailbox-close MBOX Closes mailbox MBOX - Scheme Function: mu-mailbox-get-url MBOX Returns the URL of the mailbox. - Scheme Function: mu-mailbox-get-port MBOX MODE Returns a port associated with the contents of the MBOX. MODE is a string defining operation mode of the stream. It may contain any of the two characters: `r' for reading, `w' for writing. - Scheme Function: mu-mailbox-get-message MBOX MSGNO Retrieve from MBOX message # MSGNO. - Scheme Function: mu-mailbox-messages-count MBOX Returns number of messages in the mailbox. - Scheme Function: mu-mailbox-expunge MBOX Expunges deleted messages from the mailbox. - Scheme Function: mu-mailbox-url MBOX Returns the URL of the mailbox - Scheme Function: mu-mailbox-append-message MBOX MESG Appends the message to the mailbox Message Functions ================= - Scheme Function: mu-message-copy MESG Creates the copy of the given message. - Scheme Function: mu-message-set-header MESG HEADER VALUE REPLACE Sets new VALUE to the header HEADER of the message MESG. If the HEADER is already present in the message its value is replaced with the supplied one if the optional REPLACE is #t. Otherwise new header is created and appended. - Scheme Function: mu-message-get-size MESG Returns the size of the given message. - Scheme Function: mu-message-get-lines MESG Returns number of lines in the given message. - Scheme Function: mu-message-get-sender MESG Returns the sender email address for the message MESG. - Scheme Function: mu-message-get-header MESG HEADER Returns the header value of the HEADER in the MESG. - Scheme Function: mu-message-get-header-fields MESG HEADERS Returns the list of headers in the MESG. If optional HEADERS is specified it should be a list of header names to restrict return value to. - Scheme Function: mu-message-set-header-fields MESG LIST REPLACE Set the headers in the message MESG from LIST LIST is a list of (cons HEADER VALUE) Optional parameter REPLACE specifies whether the new header values should replace the headers already present in the message. - Scheme Function: mu-message-delete MESG FLAG Mark given message as deleted. Optional FLAG allows to toggle deleted mark The message is deleted if it is #t and undeleted if it is #f - Scheme Function: mu-message-get-flag MESG FLAG Return value of the attribute FLAG. - Scheme Function: mu-message-set-flag MESG FLAG VALUE Set the given attribute of the message. If optional VALUE is #f, the attribute is unset. - Scheme Function: mu-message-get-user-flag MESG FLAG Returns value of the user attribute FLAG. - Scheme Function: mu-message-set-user-flag MESG FLAG VALUE Set the given user attribute of the message. If optional VALUE is #f, the attribute is unset. - Scheme Function: mu-message-get-port MESG MODE FULL Returns a port associated with the given MESG. MODE is a string defining operation mode of the stream. It may contain any of the two characters: `r' for reading, `w' for writing. If optional FULL argument specified, it should be a boolean value. If it is #t then the returned port will allow access to any part of the message (including headers). If it is #f then the port accesses only the message body (the default). - Scheme Function: mu-message-get-body MESG Returns the message body for the message MESG. - Scheme Function: mu-message-send MESG MAILER Sends the message MESG. Optional MAILER overrides default mailer settings in mu-mailer. MIME Functions ============== - Scheme Function: mu-mime-create FLAGS MESG Creates a new MIME object. - Scheme Function: mu-mime-multipart? MIME Returns #t if MIME is a multipart object. - Scheme Function: mu-mime-get-num-parts MIME Returns number of parts in a MIME object. - Scheme Function: mu-mime-get-part MIME PART Returns part number PART from a MIME object. - Scheme Function: mu-mime-add-part MIME MESG Adds MESG to the MIME object. - Scheme Function: mu-mime-get-message MIME Converts MIME object to a message. Log Functions ============= - Scheme Function: mu-openlog IDENT OPTION FACILITY Opens a connection to the system logger for Guile program. - Scheme Function: mu-logger PRIO TEXT Generates a log message to be distributed via syslogd. - Scheme Function: mu-closelog Closes the channel to the system logger open by mu-openlog. Direct Linking ============== If you plan to link your program directly to `libguile', it will probably make sense to link `libmu_scm' directly as well. The arguments to the program loader may be obtained by running mailutils-config --link guile *Note mailutils-config::, for more information about this utility. Here is a sample Makefile fragment: MU_LDFLAGS=`mailutils-config --link guile` MU_INCLUDES=`mailutils-config --include` myprog: myprog.c $(CC) -omyprog $(CFLAGS) $(MU_INCLUDES) myprog.c $(MU_LDFLAGS) Dynamic Linking =============== Dynamic linking is the preferred method of using `libmu_scm'. It uses Guile "use-modules" mechanism. An interface module `mailutils.scm' is provided in order to facilitate using this method. This module is installed in the package data directory (by default it is PREFIX/share/mailutils). A sample use of this module is: (set! %load-path (list "/usr/local/share/mailutils")) (use-modules (mailutils)) # Now you may use mailutils functions: (let ((mb (mu-mailbox-open "/var/spool/mail/gray" "r"))) ... _Note_, that you should explicitly modify the `%load-path' before calling `use-modules', otherwise Guile will not be able to find `mailutils.scm'. Sieve Library ************* This chapter describes GNU Sieve library. Library Description =================== `Libsieve' is GNU implementation of the mail filtering language Sieve. The library is built around a "Sieve Machine" -- an abstract computer constructed specially to handle mail filtering tasks. This computer has two registers: program counter and numeric accumulator; a runtime stack of unlimited depth and the code segment. A set of functions is provided for creating and destroying instances of Sieve Machine, manipulating its internal data, compiling and executing a sieve program. The following is a typical scenario of using `libsieve': 1. Application program creates the instance of sieve machine. 2. Then `sieve_compile' function is called to translate the Sieve source into an equivalent program executable by the Machine 3. A mailbox is opened and associated with the Machine 4. The Machine executes the program over the mailbox 5. When the execution of the program is finished, all messages upon which an action was executed other than `keep' are marked with the delete flag. Thus, running `mailbox_expunge' upon the mailbox finishes the job, leaving in the mailbox only those messages that were preserved by the filter. 6. Finally, the instance of Sieve Machine is destroyed and the resources allocated for it are reclaimed. The following sections describe in detail the functions from the Sieve Library. 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 *Note 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_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] 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 __P((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 `' 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. Logging and Diagnostic Functions -------------------------------- - Function: void sieve_error (sieve_machine_t MACH, const char *FMT, ...) Format and output an error message using error printer of the machine MACH. - Function: void sieve_debug (sieve_machine_t MACH, const char *FMT, ...) Format and output a debug message using debug printer of the machine MACH. - Function: void sieve_log_action (sieve_machine_t MACH, const char *ACTION, const char *FMT, ...) Log a sieve action using logger function associated with the machine MACH. - Function: void sieve_abort (sieve_machine_t MACH) Immediately abort the execution of the script. Symbol Space Functions ---------------------- - Function: sieve_register_t * sieve_test_lookup (sieve_machine_t MACH, const char *NAME) Find a register object describing the test NAME. Returns `NULL' if no such test exists. - Function: sieve_register_t * sieve_action_lookup (sieve_machine_t MACH, const char *NAME) Find a register object describing the action NAME. Returns `NULL' if no such action exists. - Function: int sieve_register_test (sieve_machine_t MACH, const char *NAME, sieve_handler_t HANDLER, sieve_data_type *ARG_TYPES, sieve_tag_group_t *TAGS, int REQUIRED) - Function: int sieve_register_action (sieve_machine_t MACH, const char *NAME, sieve_handler_t HANDLER, sieve_data_type *ARG_TYPES, sieve_tag_group_t *TAGS, int REQUIRED) - Function: int sieve_register_comparator (sieve_machine_t MACH, const char *NAME, int REQUIRED, sieve_comparator_t IS, sieve_comparator_t CONTAINS, sieve_comparator_t MATCHES, sieve_comparator_t REGEX) - Function: int sieve_tag_lookup (list_t TAGLIST, char *NAME, sieve_value_t **ARG) - Function: int sieve_load_ext (sieve_machine_t MACH, const char *NAME) Memory Allocation ----------------- The following functions act as their libc counterparts. The allocated memory is associated with the MACH argument and is automatically freed upon the call to `sieve_machine_destroy (MACH)'. - Function: void * sieve_malloc (sieve_machine_t MACH, size_t SIZE) Allocates SIZE bytes and returns a pointer to the allocated memory. - Function: char * sieve_mstrdup (sieve_machine_t MACH, const char *STR) This function returns a pointer to a new string which is a duplicate of the string STR. - Function: void * sieve_mrealloc (sieve_machine_t MACH, void *PTR, size_t SIZE) Changes the size of the memory block pointed to by PTR to SIZE bytes. The contents will be unchanged to the minimum of the old and new sizes; newly allocated memory will be uninitialized. If PTR is `NULL', the call is equivalent to `sieve_malloc(MACH, SIZE)'; if SIZE is equal to zero, the call is equivalent to `sieve_mfree(PTR)'. Unless PTR is `NULL', it must have been returned by an earlier call to `sieve_malloc()' or `sieve_mrealloc()'. - Function: void sieve_mfree (sieve_machine_t MACH, void *PTR) `sieve_mfree()' frees the memory space pointed to by PTR and detaches it from the destructor list of MACH. The PTR must have been returned by a previous call to `sieve_malloc()' or `sieve_mrealloc()'. Otherwise, or if `sieve_mfree(PTR)' has already been called before, undefined behaviour occurs. If PTR is `NULL', no operation is performed. Compiling and Executing the Script ---------------------------------- - Function: int sieve_compile (sieve_machine_t MACH, const char *NAME) Compile the sieve script from the file NAME. - Function: int sieve_mailbox (sieve_machine_t MACH, mailbox_t MBOX) Execute the code from the given instance of sieve machine MACH over each message in the mailbox MBOX. - Function: int sieve_message (sieve_machine_t MACH, message_t MESSAGE) Execute the code from the given instance of sieve machine MACH over the MESSAGE. - Function: int sieve_disass (sieve_machine_t MACH) Dump the disassembled code of the sieve machine MACH. Input Language ============== The input language understood by the GNU Sieve Library is a superset of the Sieve language as described in RFC 3028. Lexical Structure ----------------- Whitespace and Comments ----------------------- Comments are semantically equivalent to whitespace and can be used anyplace that whitespace is (with one exception in multi-line strings, as described below). There are two kinds of comments: hash comments, that begin with a `#' character that is not contained within a string and continue until the next newline, and C-style or bracketed comments, that are delimited by `/*' and `*/' tokens. The bracketed comments may span multiple lines. E.g.: if size :over 100K { # this is a comment discard; } if size :over 100K { /* this is a comment this is still a comment */ discard /* this is a comment again */ ; } Like in C, bracketed comments do not nest. Lexical Tokens -------------- The basic lexical entities are "identifiers" and "literals". An "identifier" is a sequence of letters, digits and underscores, started with a letter or underscore. For example, `header' and `check_822_again' are valid identifiers, whereas `1st' is not. A special form of identifier is "tag": it is an identifier prefixed with a colon (`:'), e.g.: `:comparator'. A "literal" is a data that is not executed, merely evaluated "as is", to be used as arguments to commands. There are four kinds of literals: * Number "Numbers" are given as ordinary unsigned decimal numbers. An optional suffix may be used to indicate a multiple of a power of two. The suffixes are: `K' specifying "kibi-", or 1,024 (2^10) times the value of the number; `M' specifying "mebi-", or 1,048,576 (2^20) times the value of the number; and `G' specifying "tebi-", or 1,073,741,824 (2^30) times the value of the number. The numbers have 32 bits of magnitude. * String A "string" is any sequence of characters enclosed in double quotes (`"'). A string cannot contain newlines and double quote characters. This limitation will disappear in future releases. * Multiline Strings A "multiline string" is used to represent large blocks of text with embedded newlines and special characters. It starts with the keyword `text:' followed by a newline and ends with a dot (`.') on a newline by itself. Any characters between these two markers are taken verbatim. For example: text: ** This is an authomatic response from my message ** ** filtering program. ** I can not attend your message right now. However it will be saved, and I will read it as soon as I am back. Regards, Fred . Notice that a hashed comment or whitespace may occur between `text:' and the newline. However, when used inside the multiline string a hash sign looses its special meaning (except in one case, see below) and is taken as is, as well as bracketed comment delimiters. In other words, no comments are allowed within a multiline string. E.g.: text: # This is a comment Sample text # This line is taken verbatim /* And this line too */ . The only exception to this rule is that preprocessor `include' statement is expanded as usual when found within a multiline string (*note #include::), e.g.: text: #include . This results in the contents of file `myresponse.txt' being read and interpreted as the contents of the multiline string. * String Lists A "string list" is a comma-delimited list of quoted strings, enclosed in a pair of square brackets, e.g.: ["me@example.com", "me00@landru.example.edu"] For convenience, in any context where a list of strings is appropriate, a single string is allowed without being a member of a list: it is equivalent to a list with a single member. For example, the following two statements are equivalent: exists "To"; exists ["To"]; Syntax ------ Being designed for the sole purpose of filtering mail, Sieve has a very simple syntax. Commands ........ The basic syntax element is a "command". It is defined as follows: COMMAND-NAME [TAGS] ARGS where COMMAND-NAME is an identifier representing the name of the command, TAGS is an optional list of "optional" or "tagged arguments" and ARGS is a list of "required" or "positional arguments". Positional arguments are literals delimited with whitespace. They provide the command with the information necessary to its proper functioning. Each command has a fixed number of positional arguments. It is an error to supply more arguments to the command or to give it fewer arguments than it accepts. Optional arguments allow to modify the behaviour of the command, like command line options in UNIX do. They are a list of "tags" (*note Lexical Structure::) separated by whitespace. An optional argument may have at most one parameter. Each command understands a set of optional arguments. Supplying it tags that it does not understand results in an error. For example, consider the following command header :mime :comparator "i;octet" ["to", "from"] "bug-mailutils@gnu.org" Here, given that `header' takes two positional arguments: `header' is command name, the list `["to", "from"]' is first positional argument and the string `"bug-mailutils@gnu.org"' is second positional argument. There are two optional arguments: `:mime' and `:comparator'. The latter has a string `"i;octet"' as its parameter. Actions Described ................. An "action" is a Sieve command that performs some operation over the message. Actions do the main job in any Sieve program. Syntactically, an action is a command terminated with semicolon, e.g.: keep; fileinto "mbox"; GNU Sieve provides the full set of actions described in RFC 3028. It also allows to extend this set using loadable actions. *Note Actions::, for detailed discussion of actions. Control Flow ............ The only control flow statement Sieve has is "if" statement. In its simplest form it is: if `condition' { ... } The effect of this statement is that the sequence of actions between the curly braces is executed only if the `condition' evaluates to `true'. A more elaborate form of this statement allows to execute two different sets of actions depending on whether the condition is true or not: if `condition' { ... } else { ... } The most advanced form of the "if" statement allows to select an action depending on what condition from the set of conditions is met. if `cond1' { ... } elsif `cond2' { ... } else { ... } There may be any number of "elsif" branches in an "if" statement. However it may have at most one "else" branch. Notes for C programmers: 1. The braces surrounding each branch of an "if" statement are required. 2. The "else if" construct is disallowed. Use "elsif" keyword instead. Here's an example of "if" statement: if header :contains "from" "coyote" { discard; } elsif header :contains ["subject"] ["$$$"] { discard; } else { fileinto "INBOX"; } The following section describes in detail conditions used in "if" statements. Tests and Conditions .................... "Tests" are Sieve commands that return boolean value. E.g. the test header :contains "from" "coyote" returns true only if the header "From" of the current message contains substring "coyote". The tests shipped with the GNU Sieve are described in *Note Tests::. "Condition" is a Sieve expression that evaluates to `true' or `false'. In its simplest form, condition is just a Sieve test. To reverse the sense of a condition use keyword `not', e.g.: not header :contains "from" "coyote" The results of several conditions may be joined together by logical `and' and `or' operations. The special form `allof' takes several tests as its arguments and computes the logical `and' of their results. Similarly, the form `anyof' performs logical `or' over the results of its arguments. E.g.: if anyof (not exists ["From", "Date"], header :contains "from" "fool@example.edu") { discard; } Preprocessor ------------ The preprocessor statements are a GNU extension to the Sieve language. The syntax for a preprocessor statement is similar to that used in `C' programming language, i.e.: a pound character (`#') followed by a preprocessor directive and its arguments. Any amount of whitespace can be inserted between the `#' and the directive. Currently implemented directives are `include' and `searchpath'. Sieve #include directive ........................ The `#include' directive reads in the contents of the given file. The contents is "inserted" into the text being parsed starting at the line where the directive appears. The directive takes two forms: `#include "FILENAME"' The FILENAME is taken relative to the current directory. `#include "' The FILENAME is searched in the list of include directories as specified by the `-I' command line options. If FILENAME starts with a directory separator character (`/') both forms have the same effect. Sieve #searchpath directive ........................... The `#searchpath' directive adds its argument to the list of directories searched for loadable modules. It has the same effect as `-L' command line switch used by GNU sieve utility (*note sieve group::). Require Statement ----------------- Syntax: require STRING; require STRING-LIST; The require statement informs the parser that a script makes use of a certain extension. Multiple capabilities can be declared using the second form of the statement. The actual handling of a capability name depends on its suffix. If the name starts with `comparator-', it is understood as a request to use the specified comparator. The comparator name consists of the characters following the suffix. If the name starts with `test-', it means a request to use the given test. The test name consists of the characters following the suffix. Otherwise, the capability is understood as a name of an action to be used. The `require' statement, if present, must be used before any other statement that is using the required capability. As an extension, the GNU sieve allows the `require' and any other statements to be interspersed. By default the following actions and comparators are always required: * stop * keep * discard * i;octet * i;ascii-casemap Example: require ["fileinto", "reject"]; require "fileinto"; require "comparator-i;ascii-numeric"; When processing arguments for `require' statement, GNU libsieve uses the following algorithm: 1. Look up the name in a symbol table. If the name begins with `comparator-' it is looked up in the comparator table. If it begins with `test-', the test table is used instead. Otherwise the name is looked up in the action table. 2. If the name is found, the search is terminated. 3. Otherwise, transform the name. First, any `comparator-' or `test-' prefix is stripped. Then, any character other than alphanumeric characters, `.' and `,' is replaced with dash (`-'). The name thus obtained is used as a file name of an external loadable module. 4. Try to load the module. The module is searched in the following search paths (in the order given): 1. Mailutils module directory. By default it is `$prefix/lib/mailutils'. 2. Sieve library path as given with the `-L' options in the command line 3. Additional search directories specified with the `#searchpath' directive. 4. The value of the environment variable LTDL_LIBRARY_PATH. 5. System library search path: The system dependent library search path (e.g. on Linux it is set by the contents of the file `/etc/ld.so.conf' and the value of the environment variable LD_LIBRARY_PATH). The value of LTDL_LIBRARY_PATH and LD_LIBRARY_PATH must be a colon-separated list of absolute directories, for example, `"/usr/lib/mypkg:/lib/foo"'. In any of these directories, `libsieve' first attempts to find and load the given filename. If this fails, it tries to append the following suffixes to the file name: 1. the libtool archive extension `.la' 2. the extension used for native dynamic libraries on the host platform, e.g., `.so', `.sl', etc. 5. If the module is found, `libsieve' executes its initialization function (see below) and again looks up the name in the symbol table. If found, search terminates successfully. 6. If either the module is not found, or the symbol wasn't found after execution of the module initialization function, search is terminated with an error status. `libsieve' then issues the following diagnostic message: source for the required action NAME is not available Comparators ----------- GNU libsieve supports the following built-in comparators: `i;octet' This comparator simply compares the two arguments octet by octet `i;ascii-casemap' It treats uppercase and lowercase characters in the ASCII subset of UTF-8 as the same. This is the default comparator. `i;ascii-numeric' Treats the two arguments as ASCII representation of decimal numbers and compares their numeric values. This comparator must be explicitly required prior to use. Tests ----- This section describes the built-in tests supported by GNU libsieve. In the discussion below the following macro-notations are used: MATCH-TYPE This tag specifies the matching type to be used with the test. It can be one of the following: `:is' The `:is' match type describes an absolute match; if the contents of the first string are absolutely the same as the contents of the second string, they match. Only the string "frobnitzm" is the string "frobnitzm". The null key ":is" and only ":is" the null value. This is the default match-type. `:contains' The `:contains' match type describes a substring match. If the value argument contains the key argument as a substring, the match is true. For instance, the string "frobnitzm" contains "frob" and "nit", but not "fbm". The null key "" is contained in all values. `:matches' The `:matches' version specifies a wildcard match using the characters `*' and `?'. `*' matches zero or more characters, and `?' matches a single character. `?' and `*' may be escaped as `\\?' and `\\*' in strings to match against themselves. The first backslash escapes the second backslash; together, they escape the `*'. `:regex' The `:regex' version specifies a match using POSIX Extended Regular Expressions. COMPARATOR A COMPARATOR syntax item is defined as follows: :comparator "COMPARATOR-NAME" It instructs sieve to use the given comparator with the test. If COMPARATOR-NAME is not one of `i;octet', `i;ascii-casemap' it must be required prior to using it. For example: require "comparator-i;ascii-numeric"; if header :comparator "i;ascii-numeric" :is "X-Num" "10" { ... ADDRESS-PART This syntax item is used when testing structured Internet addresses. It specifies which part of an address must be used in comparisons. Exactly one of the following tags may be used: `:all' Use the whole address. This is the default. `:localpart' Use local part of the address. `:domain' Use domain part of the address. _Notice_, that MATCH-TYPE modifiers interact with comparators. Some comparators are not suitable for matching with `:contains' or `:matches'. If this occurs, sieve issues an appropriate error message. For example, the statement: if header :matches :comparator "i;ascii-numeric" would result in the following error message: comparator `i;ascii-numeric' is incompatible with match type `:matches' in call to `header' - Test: false This test always evaluates to "false". - Test: true This test always evaluates to "true". - Test: address [ADDRESS-PART][COMPARATOR][MATCH-TYPE] HEADER-NAMES KEY-LIST Tagged arguments: ADDRESS-PART Selects the address part to compare. Default is the whole email address (`:all'). COMPARATOR Specifies the comparator to be used instead of the default `i;ascii-casemap'. MATCH-TYPE Specifies the match type to be used instead of the default `:is'. Required arguments: HEADER-NAMES A list of header names. KEY-LIST A list of address values. The `address' test matches Internet addresses in structured headers that contain addresses. It returns `true' if any header contains any key in the specified part of the address, as modified by COMPARATOR and MATCH-TYPE optional arguments. This test returns `true' if any combination of the HEADER-NAMES and KEY-LIST arguments match. The `address' primitive never acts on the phrase part of an email address, nor on comments within that address. Use the `header' test instead. It also never acts on group names, although it does act on the addresses within the group construct. Example: if address :is :all "from" "tim@example.com" { discard; } - Test: size [:over|:under] NUMBER The `size' test deals with the size of a message. The required argument NUMBER represents the size of the message in bytes. It may be suffixed with the following quantifiers: `k' `K' The number is expressed in kilobytes. `m' `M' The number is expressed in megabytes. `g' `G' The number is expressed in gigabytes. If the tagged argument is `:over', and the size of the message is greater than NUMBER, the test is true; otherwise, it is false. If the argument is `:under', and the size of the message is less than the NUMBER, the test is true; otherwise, it is false. Otherwise, the test is true only if the size of the message equals exactly NUMBER. This is a GNU extension. The size of a message is defined to be the number of octets from the initial header until the last character in the message body. - Test: envelope [ADDRESS-PART][COMPARATOR][MATCH-TYPE] ENVELOPE-PART KEY-LIST Tagged arguments: ADDRESS-PART Selects the address part to compare. Default is the whole email address (`:all'). COMPARATOR Specifies the comparator to be used instead of the default `i;ascii-casemap'. MATCH-TYPE Specifies the match type to be used instead of the default `:is'. Required arguments: ENVELOPE-PARTS A list of envelope parts to operate upon. KEY-LIST A list of address values. The `envelope' test is true if the specified part of the SMTP envelope matches the specified key. If the envelope-part strings is (case insensitive) `from', then matching occurs against the FROM address used in the `SMTP MAIL' command. _Notice_, that due to the limitations imposed by SMTP envelope structure the use of any other values in ENVELOPE-PARTS header is meaningless. - Test: exists HEADER-NAMES Required arguments: HEADER-NAMES List of message header names. The `exists' test is `true' if the headers listed in HEADER-NAMES argument exist within the message. All of the headers must exist or the test is false. The following example throws out mail that doesn't have a From header and a Date header: if not exists ["From","Date"] { discard; } - Test: header [COMPARATOR] [MATCH-TYPE] [:mime] HEADER-NAMES KEY-LIST Tagged arguments: COMPARATOR Specifies the comparator to be used instead of the default `i;ascii-casemap'. MATCH-TYPE Specifies the match type to be used instead of the default `:is'. :mime This tag instructs `header' to search through the mime headers in multipart messages as well. Required arguments: HEADER-NAMES A list of header names. KEY-LIST A list of header values. The `header' test evaluates to true if any header name matches any key. The type of match is specified by the optional match argument, which defaults to ":is" if not explicitly given. The test returns `true' if any combination of the HEADER-NAMES and KEY-LIST arguments match. If a header listed in HEADER-NAMES exists, it contains the null key (`""'). However, if the named header is not present, it does not contain the null key. So if a message contained the header X-Caffeine: C8H10N4O2 these tests on that header evaluate as follows: header :is ["X-Caffeine"] [""] => false header :contains ["X-Caffeine"] [""] => true - Test: numaddr [:over|:under] HEADER-NAMES NUMBER This test is provided as an example of loadable extension tests. You must use `require "test-numaddr"' statement before actually using it. The `numaddr' test counts Internet addresses in structured headers that contain addresses. It returns true if the total number of addresses satisfies the requested relation. If the tagged argument is `:over' and the number of addresses is greater than NUMBER, the test is true; otherwise, it is false. If the tagged argument is `:under' and the number of addresses is less than NUMBER, the test is true; otherwise, it is false. If the tagged argument is not given, `:over' is assumed. Actions ------- The GNU libsieve supports the following default actions: * stop * keep * discard * fileinto * reject * redirect Among them the first three actions do not need to be explicitly required by a `require' statement, while the others do. These actions are described in detail below. - Action: stop The `stop' action ends all processing. If no actions have been executed, then the `keep' action is taken. - Action: keep The effect of this action is to preserve the current message in the mailbox. This action is executed if no other action has been executed. - Action: discard `Discard' silently throws away the current message. No notification is returned to the sender, the message is deleted from the mailbox. Example: if header :contains ["from"] ["idiot@example.edu"] { discard; } - Action: fileinto FOLDER Required arguments: FOLDER A string representing the folder name The `fileinto' action delivers the message into the specified folder. - Action: reject REASON The optional `reject' action refuses delivery of a message by sending back a message delivery notification to the sender. It resends the message to the sender, wrapping it in a "reject" form, noting that it was rejected by the recipient. The required argument REASON is a string specifying the reason for rejecting the message. Example: If the message contained Date: Tue, 1 Apr 1997 09:06:31 -0800 (PST) From: coyote@desert.example.org To: roadrunner@acme.example.com Subject: I have a present for you I've got some great birdseed over here at my place. Want to buy it? and the user's script contained: if header :contains "from" "coyote@desert.example.org" { reject "I am not taking mail from you, and I don't want your birdseed, either!"; } then the original sender would receive the following notification: To: X-Authentication-Warning: roadrunner set sender using -f flag Content-Type: multipart/mixed; boundary=----- =_aaaaaaaaaa0 MIME-Version: 1.0 ----- =_aaaaaaaaaa0 The original message was received at Tue, 1 Apr 1997 09:07:15 -0800 from coyote@desert.example.org. Message was refused by recipient's mail filtering program. Reason given was as follows: I am not taking mail from you, and I don't want your birdseed, either! ----- =_aaaaaaaaaa0 Content-Type: message/delivery-status Reporting-UA: sieve; GNU Mailutils 0.1.3 Arrival-Date: Tue, 1 Apr 1997 09:07:15 -0800 Final-Recipient: RFC822; roadrunner@acme.example.com Action: deleted Disposition: automatic-action/MDN-sent-automatically;deleted Last-Attempt-Date: Tue, 1 Apr 1997 09:07:15 -0800 ----- =_aaaaaaaaaa0 Content-Type: message/rfc822 From: coyote@desert.example.org To: roadrunner@acme.example.com Subject: I have a present for you I've got some great birdseed over here at my place. Want to buy it? ----- =_aaaaaaaaaa0 If the REASON argument is rather long, the common approach is to use the combination of the `text:' and `#include' keywords, e.g.: if header :mime :matches "Content-Type" [ "*application/msword;*", "*audio/x-midi*" ] { reject text: #include "nomsword.txt" . ; } - Action: redirect ADDRESS The `redirect' action is used to send the message to another user at a supplied ADDRESS, as a mail forwarding feature does. This action makes no changes to the message body or existing headers, but it may add new headers. It also modifies the envelope recipient. The `redirect' command performs an MTA-style "forward" -- that is, what you get from a `.forward' file using `sendmail' under UNIX. The address on the SMTP envelope is replaced with the one on the `redirect' command and the message is sent back out. _Notice_, that it differs from the MUA-style forward, which creates a new message with a different sender and message ID, wrapping the old message in a new one. Extensions ========== This section summarizes the GNU extensions to the sieve language 1. Handling of the `require' statement. * According to the RFC an error must occur if a `require' appears after a command other than `require'. The GNU sieve library allows interspersing the `require' and other statements. The only requirement is that `require' must occur before a statement that is using the required capability (*note Require Statement::). * Prefixing the required capability with "test" requires the use of an extension test. 2. `header' test The `header' takes an optional argument `:mime', meaning to scan the headers from each part of a multipart message. 3. `size' test The `size' test allows to omit the optional argument (:over|:under). In this case exact equality is assumed. 4. `envelope' test The only value that can be meaningfully used as the first required argument of an `envelope' test is `from'. This limitation may disappear from the subsequent releases. 5. Match type optional argument. Along with the usual `:is', `:matches' and `contains' matching type, GNU sieve library understands `:regex' type. This matching type toggles POSIX Extended Regular Expression matching. Writing Loadable Commands ========================= This section contains an example of how to write external loadable commands for GNU libsieve. /* This is an example on how to write extension tests for GNU sieve. It provides test "numaddr". Syntax: numaddr [":over" / ":under"] The "numaddr" test counts Internet addresses in structured headers that contain addresses. It returns true if the total number of addresses satisfies the requested relation: If the argument is ":over" and the number of addresses is greater than the number provided, the test is true; otherwise, it is false. If the argument is ":under" and the number of addresses is less than the number provided, the test is true; otherwise, it is false. If the argument is empty, ":over" is assumed. */ #ifdef HAVE_CONFIG_H # include #endif #include #include struct val_ctr { /* Data passed to the counter function */ header_t hdr; /* Headers of the current message */ size_t limit; /* Limit for the number of addresses */ size_t count; /* Number of addresses counted so far */ }; /* Count addresses in a single header value. Input: ITEM is the name of the header to scan. DATA is a pointer to the val_ctr structure Return value: non-zero if the limit on the number of addresses has been reached. */ static int _count_items (void *item, void *data) { char *name = item; struct val_