The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Net-IMAP-Server-1.38
River stage zero No dependents
++
/ Net::IMAP::Server::Mailbox

NAME

Net::IMAP::Server::Mailbox - A user's view of a mailbox

DESCRIPTION

This class encapsulates the view of messages in a mailbox. You may wish to subclass this class in order to source our messages from, say, a database.

METHODS

Initialization

new

Creates a new mailbox; returns undef if a mailbox with the same full path already exists. It calls "init", then "load_data".

init

Sets up basic properties of the mailbox:

load_data

This default mailbox implementation simply returns an empty mailbox. Subclasses will probably wish to override this method.

name

Gets or sets the name of the mailbox. This includes a workaround for Zimbra, which doesn't understand mailbox names with colons in them -- so we substitute dashes.

Actions

poll

Called when the server wishes the mailbox to update its state. By default, does nothing. Subclasses will probably wish to override this method.

add_message MESSAGE

Adds the given Net::IMAP::Server::Message MESSAGE to the mailbox, setting its "sequence" in Net::IMAP::Server::Message and "mailbox" in Net::IMAP::Server::Message. "uid" in Net::IMAP::Server::Message is set to "uidnext" if the message does not already have a uid.

add_child [...]

Creates a mailbox under this mailbox, of the same class as this mailbox is. Any arguments are passed to "new". Returns the newly added subfolder, or undef if a folder with that name already exists.

create [...]

Identical to "add_child". Should return false if the create is denied or fails.

reparent MAILBOX [NAME]

Reparents this mailbox to be a child of the given Net::IMAP::Server::Mailbox MAILBOX, with the given NAME. Should return 0 if the reparenting is denied or fails.

delete

Deletes this mailbox, removing it from its parent's list of children. Should return false if the deletion is denied or fails.

expunge [ARRAYREF]

Expunges messages marked as \Deleted. If an arrayref of message sequence numbers is provided, only expunges message from that set.

append MESSAGE

Appends, and returns, the given MESSAGE, which should be a string containing the message. Returns false is the append is denied or fails.

close

Called when the client selects a different mailbox, or when the client's connection closes. By default, does nothing.

Inspection

separator

Returns the path separator. Note that only the path separator of the root mailbox matters. Defaults to a forward slash.

If the function returns is undef, the server supports only flat mailboxes (i.e. no child mailboxes are allowed).

full_path [purge => 1]

Returns the full path to this mailbox. This value is cached aggressively on a per-connection basis; passing purge flushes this cache, if the path name has changed.

flags

Returns the list of flags that this mailbox supports.

can_set_flag FLAG

Returns true if the client is allowed to set the given flag in this mailbox; this simply scans "flags" to check.

exists

Returns the number of messages in this mailbox. Observing this also sets the "high water mark" for notifying the client of messages added.

recent

Returns the number of messages which have the \Recent flag set.

first_unseen

Returns the sequence number of the first message which does not have the \Seen flag set. Returns 0 if all messages have been marked as \Seen.

unseen

Returns the number of messages which do not have the \Seen flag set.

permanentflags

Returns the flags which will be stored permanently for this mailbox; defaults to the same set as "flags" returns.

status TYPES

Called when the clients requests a status update (via Net::IMAP::Server::Command::Status). TYPES should be the types of information requested, chosen from this list:

MESSAGES

The number of messages in the mailbox (via "exists")

RECENT

The number of messages marked as \Recent (via "recent")

UNSEEN

The number of messages not marked as \Seen (via "unseen")

UIDVALIDITY

The /uidvalidity of the mailbox.

UIDNEXT

The /uidnext of the mailbox.

read_only

Returns true if this mailbox is read-only. By default, the value of this depends on if the mailbox was selected using EXAMINE or SELECT (see Net::IMAP::Server::Command::Select and "selected_read_only" in Net::IMAP::Server::Connection)

select

Called when the mailbox is selected; by default does nothing. Note that this could be called a a result of either a SELECT or an EXAMINE.

selected

Returns true if this mailbox is the mailbox selected by the current Net::IMAP::Server::Connection.

This method exists to choose the most apppriate strategy to take the intersection of (uids asked for) n (uids we have), by examining the cardinality of each set, and iterating over the smaller of the two. This is particularly important, as many clients try to fetch UIDs 1:*, which will exhaust memory if the naive approach is taken, and there is one message with UID 100_000_000.

get_uids STR

Parses and returns messages fitting the given UID range.

get_messages STR

Parses and returns messages fitting the given sequence range. Note that since sequence numbers are connection-dependent, this simply passes the buck to "Net::IMAP::Server::Connection/get_messages".

update_tree

Called before the model's children are listed to the client. This is the right place to hook into for mailboxes whose children shift with time.

prep_for_destroy

Called before the mailbox is destroyed; this deals with cleaning up the several circular references involved. In turn, it calls "prep_for_destroy" on all child mailboxes, as well as all messages it has.