/functions/imap_mailbox.php

Description
Description | Classes | Includes | Functions

imap_mailbox.php

This implements all functions that manipulate mailboxes

Classes
Description | Classes | Includes | Functions
Class Description
mailboxes Mailboxes class
Includes
Description | Classes | Includes | Functions
require_once (SM_PATH.'functions/imap_utf7_local.php') (line 16)

UTF7 support

Functions
Description | Classes | Includes | Functions
check_is_noinferiors (line 160)

Detects if mailbox has noinferiors flag (can't store subfolders)

  • return: whether this is a Noinferiors mailbox.
  • since: 1.5.0
bool check_is_noinferiors (string $lsub_line)
  • string $lsub_line: mailbox line from untagged LIST or LSUB response
check_is_noselect (line 150)

Detects if mailbox has noselect flag (can't store messages) In versions older than 1.4.5 function checks only LSUB responses and can produce pcre warnings.

  • return: whether this is a Noselect mailbox.
  • since: 1.3.2
bool check_is_noselect (string $lsub_line)
  • string $lsub_line: mailbox line from untagged LIST or LSUB response
compact_mailboxes_response (line 105)
  • since: 1.5.0
array compact_mailboxes_response (array $ary)
  • array $ary
find_mailbox_name (line 133)

Extract the mailbox name from an untagged LIST (7.2.2) or LSUB (7.2.3) answer (LIST|LSUB) (<Flags list>) (NIL|"<separator atom>") <mailbox name string>\r\n mailbox name in quoted string MUST be unquoted and stripslashed (sm API)

Originally stored in functions/strings.php. Since 1.2.6 stored in functions/imap_mailbox.php

  • return: mailbox name
string find_mailbox_name (string $line)
  • string $line: imap LIST/LSUB response line
handleAsSent (line 327)

Is the given folder "sent-like" in nature?

The most obvious use of this is to know what folders you usually want to show the To field instead of the From field on the mailbox list

This function returns TRUE if the given folder is the sent folder (or any of its subfolders) or if it is the draft folder (or any of its subfolders)

  • return: See explanation above
boolean handleAsSent (string $mailbox)
  • string $mailbox
isBoxBelow (line 198)

Check if $subbox is below the specified $parentbox

  • since: 1.2.3
boolean isBoxBelow (string $subbox, string $parentbox)
  • string $subbox: potential sub folder
  • string $parentbox: potential parent
isDraftMailbox (line 305)

Detects if mailbox is a Drafts folder or subfolder of Drafts

  • return: whether this is a Draft folder
  • since: 1.4.0
bool isDraftMailbox (string $box, [boolean $include_subs = true])
  • string $box: mailbox name
  • boolean $include_subs: (since 1.5.2) if true, subfolders of system folders are special. if false, subfolders are not special mailboxes.
isInboxMailbox (line 262)

Detects if mailbox is the Inbox folder or subfolder of the Inbox

  • return: Whether this is the Inbox or a child thereof.
  • since: 1.4.22
boolean isInboxMailbox (string $box, [boolean $include_subs = TRUE])
  • string $box: The mailbox name to test
  • boolean $include_subs: If true, subfolders of system folders are special. If false, subfolders are not special mailboxes.
isSentMailbox (line 290)

Detects if mailbox is a Sent folder or subfolder of Sent

  • return: whether this is a Sent folder
  • since: 1.4.0
bool isSentMailbox (string $box, [boolean $include_subs = true])
  • string $box: mailbox name
  • boolean $include_subs: (since 1.5.2) if true, subfolders of system folders are special. if false, subfolders are not special mailboxes.
isSpecialMailbox (line 236)

Defines special mailboxes: given a mailbox name, it checks if this is a "special" one: INBOX, Trash, Sent or Draft.

Since 1.2.5 function includes special_mailbox hook.

Since 1.4.3 hook supports more than one plugin.

Since 1.4.22/1.5.2, the administrator can add $subfolders_of_inbox_are_special = TRUE; to config/config_local.php and all subfolders of the INBOX will be treated as special.

  • since: 1.2.3
boolean isSpecialMailbox (string $box, [boolean $include_subs = true])
  • string $box: mailbox name
  • boolean $include_subs: (since 1.5.2) if true, subfolders of system folders are special. if false, subfolders are not special mailboxes unless they are tagged as special in 'special_mailbox' hook.
isTrashMailbox (line 275)

Detects if mailbox is a Trash folder or subfolder of Trash

  • return: whether this is a Trash folder
  • since: 1.4.0
bool isTrashMailbox (string $box, [boolean $include_subs = true])
  • string $box: mailbox name
  • boolean $include_subs: (since 1.5.2) if true, subfolders of system folders are special. if false, subfolders are not special mailboxes.
mbxSort (line 1235)

Callback function used for sorting mailboxes in sqimap_mailbox_tree

  • return: see php strnatcasecmp()
  • since: 1.5.1
integer mbxSort (string $a, string $b)
  • string $a
  • string $b
readMailboxParent (line 177)

Detects mailbox's parent folder

If $haystack is a full mailbox name, and $needle is the mailbox separator character, returns the second last part of the full mailbox name (i.e. the mailbox's parent mailbox)

Originally stored in functions/strings.php. Since 1.2.6 stored in functions/imap_mailbox.php

  • return: parent mailbox
string readMailboxParent (string $haystack, string $needle)
  • string $haystack: full mailbox name
  • string $needle: delimiter
sortSpecialMbx (line 82)

array callback used for sorting in mailboxes class

  • return: see php strnatcasecmp()
  • since: 1.3.0
integer sortSpecialMbx (object $a, object $b)
  • object $a
  • object $b
sqimap_fill_mailbox_tree (line 1249)

Fills mailbox object

Some code fragments are present in 1.3.0 - 1.4.4.

  • return: mailboxes class
  • since: 1.5.0
object see sqimap_fill_mailbox_tree (array $mbx_ary, [$mbxs $mbxs = false], stream $imap_stream)
  • array $mbx_ary
  • stream $imap_stream: imap connection resource
  • $mbxs $mbxs
sqimap_get_mailboxes (line 923)

Gets the list of mailboxes for sqimap_maolbox_tree and sqimap_mailbox_list

This is because both of those functions had duplicated logic, but with slightly different implementations. This will make both use the same implementation, which should make it easier to maintain and easier to modify in the future

  • return: - array of mailboxes and their attributes
  • since: 1.5.1
object boxesnew sqimap_get_mailboxes (stream $imap_stream, [bool $force = false], [bool $show_only_subscribed = true], [bool $session_register = true])
  • stream $imap_stream: imap connection resource
  • bool $force: force a reload and ignore cache
  • bool $show_only_subscribed: controls listing of visible or all folders
  • bool $session_register: controls registration of retrieved data in session.
sqimap_get_status_mbx_tree (line 1370)
  • since: since 1.5.0
void sqimap_get_status_mbx_tree (stream $imap_stream,  &$mbx_tree, object $mbx_tree)
  • stream $imap_stream: imap connection resource
  • object $mbx_tree
  • &$mbx_tree
sqimap_mailbox_create (line 491)

Creates a folder.

Mailbox is automatically subscribed.

Set $type to string that does not match 'noselect' (case insensitive), if you don't want to prepend delimiter to mailbox name. Please note that 'noinferiors' might be used someday as keyword for folders that store only messages.

  • since: 1.0 or older
void sqimap_mailbox_create ( $imap_stream, string $mailbox, string $type, stream $imap_steam)
  • stream $imap_steam: imap connection resource
  • string $mailbox: mailbox name
  • string $type: folder type.
  • $imap_stream
sqimap_mailbox_delete (line 537)

Deletes the given folder

Since 1.2.6 and 1.3.0 contains rename_or_delete_folder hook

  • since: 1.0 or older
void sqimap_mailbox_delete (stream $imap_stream, string $mailbox)
  • stream $imap_stream: imap connection resource
  • string $mailbox: mailbox name
sqimap_mailbox_exists (line 389)

Checks whether or not the specified mailbox exists

  • since: 1.0 or older
boolean sqimap_mailbox_exists (stream $imap_stream, string $mailbox, [array $mailboxlist = null])
  • stream $imap_stream: imap connection resource
  • string $mailbox: mailbox name
  • array $mailboxlist: (since 1.5.1) optional array of mailboxes from sqimap_get_mailboxes() (to avoid having to talk to imap server)
sqimap_mailbox_expunge (line 355)

Expunges a mailbox

WARNING: Select mailbox before calling this function.

permanently removes all messages that have the \Deleted flag set from the selected mailbox. See EXPUNGE command chapter in IMAP RFC.

  • return: number of expunged messages
  • since: 1.0 or older
integer sqimap_mailbox_expunge (stream $imap_stream, string $mailbox, [boolean $handle_errors = true], [mixed $id = ''])
  • stream $imap_stream: imap connection resource
  • string $mailbox: mailbox name (unused since 1.1.3).
  • boolean $handle_errors: error handling control (displays error_box on error).
  • mixed $id: (since 1.3.0) integer message id or array with integer ids
sqimap_mailbox_is_noinferiors (line 1493)

Checks if folder is noinferiors (can't store other folders)

Function does not check if folder subscribed.

  • return: true, when folder has noinferiors flag. false in any other case.
  • since: 1.5.1
boolean sqimap_mailbox_is_noinferiors (stream $oImapStream, string $sImapFolder,  &$oBoxes, object $oBoxes)
  • stream $oImapStream: imap connection resource
  • string $sImapFolder: imap folder name
  • object $oBoxes: mailboxes class object.
  • &$oBoxes
sqimap_mailbox_is_noselect (line 1472)

Checks if folder is noselect (can't store messages)

Function does not check if folder subscribed.

  • return: true, when folder has noselect flag. false in any other case.
  • since: 1.5.1
boolean sqimap_mailbox_is_noselect (stream $oImapStream, string $sImapFolder,  &$oBoxes, object $oBoxes)
  • stream $oImapStream: imap connection resource
  • string $sImapFolder: imap folder name
  • object $oBoxes: mailboxes class object.
  • &$oBoxes
sqimap_mailbox_is_subscribed (line 565)

Determines if the user is subscribed to the folder or not

  • since: 1.2.0
boolean sqimap_mailbox_is_subscribed (stream $imap_stream,  $folder, string $mailbox)
  • stream $imap_stream: imap connection resource
  • string $mailbox: mailbox name
  • $folder
sqimap_mailbox_list (line 885)

Returns sorted mailbox lists in several different ways.

Since 1.5.1 most of the functionality has been moved to new function sqimap_get_mailboxes

See comment on sqimap_mailbox_parse() for info about the returned array.

  • return: list of mailboxes
  • since: 1.0 or older
array sqimap_mailbox_list (resource $imap_stream, [boolean $force = false])
  • resource $imap_stream: imap connection resource
  • boolean $force: force update of mailbox listing. available since 1.4.2 and 1.5.0
sqimap_mailbox_list_all (line 902)

Returns a list of all folders, subscribed or not

Since 1.5.1 code moved to sqimap_get_mailboxes()

  • return: see sqimap_mailbox_parse()
  • since: 1.0 or older
array sqimap_mailbox_list_all (stream $imap_stream)
  • stream $imap_stream: imap connection resource
sqimap_mailbox_option_array (line 744)

Returns an array of mailboxes available. Separated from sqimap_mailbox_option_list() below for template development.

  • author: Steve Brown
  • since: 1.5.2
void sqimap_mailbox_option_array ( $imap_stream, [ $folder_skip = 0], [ $boxes = 0], [ $flag = 'noselect'], [ $use_long_format = false])
  • $imap_stream
  • $folder_skip
  • $boxes
  • $flag
  • $use_long_format
sqimap_mailbox_option_list (line 848)

Returns list of options (to be echoed into select statement based on available mailboxes and separators Caller should surround options with <select ...> </select> and any formatting.

  • return: html formated mailbox selection options
  • since: 1.3.2
string sqimap_mailbox_option_list (stream $imap_stream, [array $show_selected = 0], [array $folder_skip = 0], [$boxes $boxes = 0], [string $flag = 'noselect'], [boolean $use_long_format = false])
  • stream $imap_stream: imap connection resource to query for mailboxes
  • array $show_selected: array containing list of mailboxes to pre-select (0 if none)
  • array $folder_skip: array of folders to keep out of option list (compared in lower)
  • string $flag: (since 1.4.1) flag to check for in mailbox flags, used to filter out mailboxes. 'noselect' by default to remove unselectable mailboxes. 'noinferiors' used to filter out folders that can not contain subfolders. NULL to avoid flag check entirely. NOTE: noselect and noiferiors are used internally. The IMAP representation is \NoSelect and \NoInferiors
  • boolean $use_long_format: (since 1.4.1) override folder display preference and always show full folder name.
  • $boxes $boxes: list of already fetched boxes (for places like folder panel, where you know these options will be shown 3 times in a row.. (most often unset).
sqimap_mailbox_parse (line 663)

Formats a mailbox into parts for the $boxesall array

The parts are:

  • raw - Raw LIST/LSUB response from the IMAP server
  • formatted - nicely formatted folder name
  • unformatted - unformatted, but with delimiter at end removed
  • unformatted-dm - folder name as it appears in raw response
  • unformatted-disp - unformatted without $folder_prefix
  • id - TODO: document me
  • flags - TODO: document me
Before 1.2.0 used third argument for delimiter.

Before 1.5.1 used second argument for lsub line. Argument was removed in order to use find_mailbox_name() on the raw input. Since 1.5.1 includes RFC3501 names in flags array (for example, "\NoSelect" in addition to "noselect")

  • todo: document id and flags keys in boxes array and function arguments.
  • since: 1.0 or older
array sqimap_mailbox_parse (array $line)
  • array $line
sqimap_mailbox_rename (line 583)

Renames a mailbox.

Since 1.2.6 and 1.3.0 contains rename_or_delete_folder hook

  • since: 1.2.3
void sqimap_mailbox_rename (stream $imap_stream, string $old_name, string $new_name)
  • stream $imap_stream: imap connection resource
  • string $old_name: mailbox name
  • string $new_name: new mailbox name
sqimap_mailbox_select (line 424)

Selects a mailbox Before 1.3.0 used more arguments and returned data depended on those arguments.

  • return: results of select command (on success - permanentflags, flags and rights) (on failure (and when $handle_errors is false), empty array)
  • since: 1.0 or older
array sqimap_mailbox_select (stream $imap_stream, string $mailbox, [boolean $handle_errors = true])
  • stream $imap_stream: imap connection resource
  • string $mailbox: mailbox name
  • boolean $handle_errors: When TRUE, IMAP errors are handled herein, causing an error to be displayed on screen and execution to stop and when FALSE, error status is returned to the caller (OPTIONAL; default is TRUE)
sqimap_mailbox_tree (line 1196)

Fills mailbox object

this is passed the mailbox array by left_main.php who has previously obtained it from sqimap_get_mailboxes that way, the raw mailbox list is available in left_main to other things besides just sqimap_mailbox_tree imap_stream is just used now to get status info

most of the functionality is moved to sqimap_get_mailboxes also takes care of TODO items: caching mailbox tree config setting for UW imap section (not needed now)

Some code fragments are present in 1.3.0 - 1.4.4.

  • return: mailboxes class.
  • since: 1.5.0
object see sqimap_mailbox_tree (stream $imap_stream, array $lsub_ary)
  • stream $imap_stream: imap connection resource
  • array $lsub_ary: output array from sqimap_get_mailboxes (contains mailboxes and flags)
sqimap_subscribe (line 512)

Subscribes to an existing folder.

  • since: 1.0 or older
void sqimap_subscribe (stream $imap_stream, string $mailbox, [boolean $debug = true])
  • stream $imap_stream: imap connection resource
  • string $mailbox: mailbox name
  • boolean $debug: (since 1.5.1)
sqimap_tree_to_ref_array (line 1354)
  • since: 1.5.0
void sqimap_tree_to_ref_array ( &$mbx_tree,  &$aMbxs, object $mbx_tree, array $aMbxs)
  • object $mbx_tree
  • array $aMbxs
  • &$mbx_tree
  • &$aMbxs
sqimap_unsubscribe (line 524)

Unsubscribes from an existing folder

  • since: 1.0 or older
void sqimap_unsubscribe (stream $imap_stream, string $mailbox)
  • stream $imap_stream: imap connection resource
  • string $mailbox: mailbox name
sqimap_utf7_decode_mbx_tree (line 1325)
  • since: 1.5.0
void sqimap_utf7_decode_mbx_tree ( &$mbx_tree, object $mbx_tree)
  • object $mbx_tree
  • &$mbx_tree

Documentation generated on Mon, 13 Jan 2020 04:22:45 +0100 by phpDocumentor 1.4.3