Class Sieve.

Inherits EventHandler

The Sieve class interprets the Sieve language, which processes incoming messages to determine their fate.

The class requires fairly specific usage: An object is created, the message sender is set using setSender(), the recipients with addRecipient() and the message itself with setMessage().

Once addRecipient() has been called, evaluate() may be, and can give results. It's unlikely (but possible) that results may be available before setMessage() has been called.

Sieve extensions are implemented in SieveProduction and Sieve. The list is in SieveProduction::supportedExtensions();

Sieve::Sieve()

Constructs an empty message Sieve.

Reimplements EventHandler::EventHandler().

void Sieve::act( EventHandler * handler )

Starts executing all the actions(), notifying handler when done.

List<SieveAction> * Sieve::actions( const Address * address ) const

Returns a list of all actions this Sieve has decided that address need performed. It returns a null pointer if address has never been passed to addRecipient(), and a pointer to a (possibly empty) list if address has been added.

void Sieve::addAction( SieveAction * action )

Records that action is to be performed if evaluation of the current user's sieve script does not fail.

At some point, this may/will also do something of a more general nature if there is no current recipient. Global sieve scripts, etc.

void Sieve::addRecipient( Address * address, EventHandler * user )

Looks up address in the aliases table, finds the related sieve script and other needed information so that delivery to address can be evaluated. Calls user when the information is available.

If address is not a registered alias, Sieve will refuse mail to it.

void Sieve::addRecipient( Address * address, Mailbox * destination, User * user, SieveScript * script )

Records that address is one of the recipients for this message, and that destination is where the mailbox should be stored by default. Sieve will use script as script. If user is non-null, Sieve will check that fileinto statement only files mail into mailboxes owned by user.

void Sieve::addSubmission( Address * address )

Records that the message should be forwarded via the smarthost to address.

bool Sieve::done() const

Returns true if the Sieve has finished evaluation (although not execution), and false if there's more to do before evaluation is complete. injected() is this function's bigger sister.

EString Sieve::error( Address * address ) const

Returns an error message if delivery to address caused a run-time error, and an empty string if all is in order or address is not a valid address.

EString Sieve::error() const

Returns an error message if delivery to any address caused a run-time error, and an empty string in all other cases.

void Sieve::evaluate()

Runs any sieve scripts currently available, sees what results can be found, and returns when it can't do anything more. If done() is true after evaluate(), evaluate() need not be called again.

void Sieve::execute()

Used only for database chores - selecting the scripts mostly. Anything else?

Reimplements EventHandler::execute().

bool Sieve::failed( Address * address ) const

Returns true if delivery to address failed or will fail, and false if it succeeded or if evaluation is not yet complete.

List<Address> * Sieve::forwarded() const

Returns a list of the Address objects to which this message should be forwarded.

The return value is never 0.

Date * Sieve::forwardingDate() const

Returns what setForwardingDate() recorded, or null if setForwardingDate() has not been called.

bool Sieve::injected() const

Returns true if every injector created by this Sieve has finished its work. When ready() and done() and injected(), the Sieve is completely done.

bool Sieve::local( Address * address ) const

Returns true if address is known to be a local address, and false if address is not known, if the Sieve isn't ready() or if address is remote.

If the Sieve is ready() and address is not local(), then it must be a remote address.

List<Mailbox> * Sieve::mailboxes() const

Returns a list of the Mailbox objects to which the message should be delivered. This won't quite do when we implement the imapflags extension - then, the different mailboxes mailboxes may need different flags.

The return value is never 0.

bool Sieve::ready() const

Returns true if evaluate() may be called, and false if execute() still has work to do.

Address * Sieve::recipient() const

Returns a pointer to the recipient currently being sieved, or a null pointer if the Sieve engine is not currently working on any particular recipient.

In the future, I think we'll add a way to sieve between MAIL FROM and RCPT TO, so recipient() can realistically return 0.

bool Sieve::rejected( Address * address ) const

Returns true if delivery to address should be rejected, and false if it should be accepted, if evaluation is not yet complete or if address is not managed by this sieve.

bool Sieve::rejected() const

Returns true if this message has been rejected by (all of its) recipient(s), and false if it has no recipients or has been accepted by at least one.

Address * Sieve::sender() const

Returns a pointer to the address set with setSender(), or a null pointer if setSender() has not yet been called.

void Sieve::setForwardingDate( Date * later )

Records that this message should be delivered to the smarthost sometime later. This applies only to messages delivered to the smarthost, messages injected into local mailboxes are always injected at once.

void Sieve::setMessage( Injectee * message, Date * when )

Records that message is to be used while sieving, and when we received it. All sieve tests that look at e.g. header fields look at message, and message is stored using fileinto/keep and forwarded using redirect. when is only used to record the message's arrival time by fileinto/keep.

void Sieve::setSender( Address * address )

Records that the envelope sender is address.

bool Sieve::softError() const

Returns true if an error has happened and should be signalled as a soft error, false if an error has happened and should be signalled as configured by soft-bounce, and an undefined value if no error has occured.

bool Sieve::succeeded( Address * address ) const

Returns true if delivery to address succeeded, and false if it failed or if evaluation is not yet complete.

List<SieveAction> * Sieve::vacations() const

Returns a list of all vacation actions. The list may be empty, but it never is a null pointer.

This web page based on source code belonging to The Archiveopteryx Developers. All rights reserved.