Class Mailbox.

This class represents a node in the global mailbox hierarchy.

Every Mailbox has a unique name() within the hierarchy. Any Mailbox that can contain messages has a non-zero numeric id() and attributes like uidvalidity() and uidnext(). Mailboxes have a parent() and may have a number of children().

Some mailboxes aren't quite real. A Mailbox can be deleted(), in which case it can contain no messags. If recreated, a deleted() mailbox preserves its uidvalidity() and uid series.

This class maintains a tree of mailboxes, based on the contents of the mailboxes table and descriptive messages from the OCServer. It can find() a named mailbox in this hierarchy.

Mailbox::Mailbox( const UString & name )

Creates a Mailbox named name. This constructor is only meant to be used via Mailbox::obtain().

void Mailbox::abortSessions()

Aborts all sessions on this Mailbox. Good to call when a mailbox is deleted.

void Mailbox::addSession( Session * s )

Adds s to the list of sessions watching this mailbox. The SessionInitialiser will update s when necessary.

Does nothing if s is already watching this mailbox.

List< Mailbox > * Mailbox::children() const

Returns a pointer to a List of this Mailbox's children, or 0 if it has none.

static Mailbox * Mailbox::closestParent( const UString & name )

Returns a pointer to the closest existing parent mailbox for name, or a null pointer if name doesn't look like a mailbox name at all, or if no parent mailboxes of name exist.

Query * Mailbox::create( Transaction * t, User * owner )

If this Mailbox does not exist, this function enqueues a Query to create it in the Transaction t and returns the Query. Otherwise it returns 0 and does nothing. It does not commit the transaction.

If owner is non-null, the new mailbox is owned by by owner.

bool Mailbox::deleted() const

Returns true if this mailbox is currently deleted.

static Mailbox * Mailbox::find( const UString & name, bool deleted )

Returns a pointer to a Mailbox named name, or 0 if the named mailbox doesn't exist. If deleted is true, deleted mailboxes are included in the search. The name must be fully-qualified.

static Mailbox * Mailbox::find( uint id )

Returns a pointer to the Mailbox with id, or a null pointer if there is no such (known) Mailbox.

Deleted mailboxes are included in the search.

bool Mailbox::hasChildren() const

Returns true if this mailbox has at least one real, existing child mailbox, including indirect children, and false if not.

uint Mailbox::id() const

Returns the database ID of this Mailbox.

bool Mailbox::isHome() const

Returns true if this Mailbox represents a user's "home directory", e.g. /users/ams.

static uint Mailbox::match( const UString & pattern, uint p, const UString & name, uint n )

This extremely slow pattern matching helper checks that pattern (starting at character p) matches name (starting at character n), and returns 2 in case of match, 1 if a child of name might match, and 0 if neither is the case.

There are only two wildcards: * matches zero or more characters. % matches zero or more characters, but does not match /.

Note that this match is case sensitive. Our mailbox names are case insensitive, so the caller typically has to call UString::titlecased() on both arguments.

UString Mailbox::name() const

Returns the fully qualified name of this Mailbox.

int64 Mailbox::nextModSeq() const

Returns the value last specified by nextModSeq(), or 1 initially.

static Mailbox * Mailbox::obtain( const UString & name, bool create )

Obtain a mailbox with name, creating Mailbox objects as necessary and permitted.

if create is true (this is the default) and there is no such Mailbox, obtain() creates one, including any necessary parents.

If create is false and there is no such Mailbox, obtain() returns null without creating anything.

bool Mailbox::ordinary() const

Returns true if this mailbox isn't "special".

uint Mailbox::owner() const

Returns the numeric user id of the owner of this mailbox, or 0 if the mailbox has no defined owner (or is not yet known to have one).

Mailbox * Mailbox::parent() const

Returns a pointer to the parent of this Mailbox, or 0 if it is the root Mailbox.

void Mailbox::refreshMailboxes( Transaction * t )

Adds one or more queries to t, to ensure that the Mailbox tree is up to date when t is commited.

bool Mailbox::refreshing()

Returns true if the Mailbox subsystem is currently in the process of relearning all the Mailbox objects from the database. Never returns true during normal operations, but may if if the database is wiped out by a test rig.

Query * Mailbox::remove( Transaction * t )

If this Mailbox can be deleted, this function enqueues a Query to do so in the Transaction t and returns the Query. If not, it returns 0 and does nothing. It does not commit the transaction.

void Mailbox::removeSession( Session * s )

Removes s from the list of sessions for this mailbox, or does nothing if s doesn't watch this mailbox.

static Mailbox * Mailbox::root()

Returns a pointer to the Mailbox object at the root of the global hierarchy.

EString Mailbox::selector() const

Returns the text of the selector that defines this view, or an empty string if this is not a View.

List<Session> * Mailbox::sessions() const

Returns a pointer to the sessions on this mailbox. The return value may be a null pointer. In the event of client/network problems it may also include sessions that have recently become invalid.

void Mailbox::setDeleted( bool del )

Changes this Mailbox's deletedness to del.

void Mailbox::setId( uint i ) const

Notifies this Mailbox that its database ID is i.

void Mailbox::setOwner( uint n )

Sets this Mailbox's owner to n (which is assumed to be a valid user id).

void Mailbox::setType( Type t )

Sets the type of this Mailbox to t. The initial value is Ordinary (because it has to be something).

void Mailbox::setUidnextAndNextModSeq( uint n, int64 m, Transaction * t )

Atomically sets both uidnext() to n and nextModSeq() to m. Uses subtransactions of t for all work needed.

void Mailbox::setUidvalidity( uint i )

Notifies this Mailbox that its correct uidvalidity is i. Should generally not be called.

static void Mailbox::setup( EventHandler * owner )

This static function is responsible for building a tree of Mailboxes from the contents of the mailboxes table. It expects to be called by ::main().

The owner (if one is specified) is notified of completion.

Mailbox * Mailbox::source() const

Returns a pointer to the source Mailbox that this View is based on, or 0 if this Mailbox is not a View.

Threader * Mailbox::threader() const

Returns a pointer to the Threader for this Mailbox. This is never a null pointer; if Mailbox doesn't have one it will create one.

The Threader usually lives until you stop caring about it, but if removeSession() removes the last Session, it also removes the Threader.

Type Mailbox::type() const

Returns the type of this Mailbox. May be Ordinary, Deleted, or View.

uint Mailbox::uidnext() const

Returns the next UID value that will be used for this mailbox.

uint Mailbox::uidvalidity() const

Returns the UIDVALIDITY value of this Mailbox. This never changes.

static bool Mailbox::validName( const UString & s )

Returns true if s is syntactically valid as a mailbox name, and false if not. Empty names are invalid, ones that do not start with '/' are too, etc, etc.

Notably, the root ("/") is not valid. This is a borderline case - for example "/" is valid as parent for creating new mailboxes, but not as name of a new mailbox.

bool Mailbox::view() const

Returns true if this mailbox is really a view.