Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Net::IMAP::Server::MaiUser(Contributed Perl DocumNet::IMAP::Server::Mailbox(3)

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:

       o   "uidnext" is	set to 1000

       o   "messages" and "uids" are initialized to an empty list reference
	   and an empty	hash reference,	respectively.

       o   "children" is set to	an empty list reference.

       o   "uidvalidity" is set	to the number of seconds since the epoch.

       o   "subscribed"	and "is_selectable" are	set true.

       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.

perl v5.32.0			  2016-05-01	 Net::IMAP::Server::Mailbox(3)

NAME | DESCRIPTION | METHODS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Net::IMAP::Server::Mailbox&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help