Roundcube Framework
Back to top  

rcube_storage

Abstract class for accessing mail messages storage server

package

Framework
subpackage

Storage
author

Thomas Bruederli roundcube@gmail.com
author

Aleksander Machniak alec@alec.pl

Methods

Delete outdated cache entries

cache_gc()
abstract

Check connection state, connect if not connected.

check_connection() : boolean
abstract

Response

boolean

Connection state.

Checks the PERMANENTFLAGS capability of the current folder and returns true if the given flag is supported by the server.

check_permflag(string $flag) : boolean
abstract

Arguments

$flag

string

Permanentflag name

Response

boolean

True if this flag is supported

Clears the cache.

clear_cache(string $key = null, boolean $prefix_mode = false)
abstract

Arguments

$key

string

Cache key name or pattern

$prefix_mode

boolean

Enable it to clear all keys starting with prefix specified in $key

Remove all messages in a folder.

clear_folder(string $folder = null) : boolean

.

Arguments

$folder

string

Folder name

Response

boolean

True on success, False on error

Close connection. Usually done on script shutdown

close()
abstract

Connect to the server

connect(string $host, string $user, string $pass, integer $port = 143, string $use_ssl = null) : boolean
abstract

Arguments

$host

string

Host to connect

$user

string

Username for IMAP account

$pass

string

Password for IMAP account

$port

integer

Port to connect to

$use_ssl

string

SSL schema (either ssl or tls) or null if plain connection

Response

boolean

TRUE on success, FALSE on failure

Copy message(s) from one mailbox to another.

copy_message(mixed $uids, string $to, string $from = null) : boolean
abstract

Arguments

$uids

mixed

Message UIDs as array or comma-separated string, or '*'

$to

string

Target folder

$from

string

Source folder

Response

boolean

True on success, False on error

Get messages count for a specific folder.

count(string $folder = null, string $mode = 'ALL', boolean $force = false, boolean $status = true) : integer
abstract

Arguments

$folder

string

Folder name

$mode

string

Mode for count [ALL|THREADS|UNSEEN|RECENT|EXISTS]

$force

boolean

Force reading from server and update cache

$status

boolean

Enables storing folder status info (max UID/count), required for folder_status()

Response

integer

Number of messages

Create all folders specified as default

create_default_folders()

Create a new folder on the server.

create_folder(string $folder, boolean $subscribe = false) : boolean
abstract

Arguments

$folder

string

New folder name

$subscribe

boolean

True if the newvfolder should be subscribed

Response

boolean

True on success, False on error

Removes any <identifier,rights> pair for the specified user from the ACL for the specified folder (DELETEACL).

delete_acl(string $folder, string $user) : boolean
abstract

Arguments

$folder

string

Folder name

$user

string

User name

Response

boolean

True on success, False on failure

Remove a folder from the server.

delete_folder(string $folder) : boolean
abstract

Arguments

$folder

string

Folder name

Response

boolean

True on success, False on error

Mark message(s) as deleted and expunge.

delete_message(mixed $uids, string $folder = null) : boolean
abstract

Arguments

$uids

mixed

Message UIDs as array or comma-separated string, or '*'

$folder

string

Source folder

Response

boolean

True on success, False on error

Unsets metadata/annotations (SETMETADATA/SETANNOTATION)

delete_metadata(string $folder, array $entries) : boolean
abstract

Arguments

$folder

string

Folder name (empty for server metadata)

$entries

array

Entry names array

Response

boolean

True on success, False on failure

Send expunge command and clear the cache.

expunge_folder(string $folder = null, boolean $clear_cache = true) : boolean

Arguments

$folder

string

Folder name

$clear_cache

boolean

False if cache should not be cleared

Response

boolean

True on success, False on error

Expunge message(s) and clear the cache.

expunge_message(mixed $uids, string $folder = null, boolean $clear_cache = true) : boolean
abstract

Arguments

$uids

mixed

Message UIDs as array or comma-separated string, or '*'

$folder

string

Folder name

$clear_cache

boolean

False if cache should not be cleared

Response

boolean

True on success, False on error

Gets folder attributes (from LIST response, e.g. \Noselect, \Noinferiors).

folder_attributes(string $folder, boolean $force = false) : array
abstract

Arguments

$folder

string

Folder name

$force

boolean

Set to True if attributes should be refreshed

Response

array

Options list

Gets connection (and current folder) data: UIDVALIDITY, EXISTS, RECENT, PERMANENTFLAGS, UIDNEXT, UNSEEN

folder_data(string $folder) : array
abstract

Arguments

$folder

string

Folder name

Response

array

Data

Checks if folder exists and is subscribed

folder_exists(string $folder, boolean $subscription = false) : boolean
abstract

Arguments

$folder

string

Folder name

$subscription

boolean

Enable subscription checking

Response

boolean

True if folder exists, False otherwise

Returns extended information about the folder.

folder_info(string $folder) : array
abstract

Arguments

$folder

string

Folder name

Response

array

Data

Returns the namespace where the folder is in

folder_namespace(string $folder) : string
abstract

Arguments

$folder

string

Folder name

Response

string

One of 'personal', 'other' or 'shared'

Get folder size (size of all messages in a folder)

folder_size(string $folder) : integer
abstract

Arguments

$folder

string

Folder name

Response

integer

Folder size in bytes, False on error

Returns current status of a folder (compared to the last time use)

folder_status(string $folder = null, array &$diff = array()) : integer
abstract

Arguments

$folder

string

Folder name

$diff

array

Difference data

Response

integer

Folder status

Synchronizes messages cache.

folder_sync(string $folder)
abstract

Arguments

$folder

string

Folder name

Returns the access control list for a folder (GETACL).

get_acl(string $folder) : array
abstract

Arguments

$folder

string

Folder name

Response

array

User-rights array on success, NULL on error

Fetch message body of a specific message from the server

get_body(integer $uid,  $part = 1) : string
see \rcube_imap::get_message_part()

Arguments

$uid

integer

Message UID

$part

Response

string

$part Message/part body

Returns cached value

get_cache(string $key) : mixed
abstract

Arguments

$key

string

Cache key

Response

mixed

Cached value

Returns the storage server's (IMAP) capability

get_capability(string $cap) : mixed
abstract

Arguments

$cap

string

Capability name

Response

mixed

Capability value or TRUE if supported, FALSE if not

Returns code of last error

get_error_code() : integer
abstract

Response

integer

Error code

Returns message of last error

get_error_str() : string
abstract

Response

string

Error message

Returns the currently used folder name

get_folder() : string

Response

string

Name of the folder

Returns the delimiter that is used by the server for folder hierarchy separation.

get_hierarchy_delimiter() : string
abstract

Response

string

Delimiter string

Fetch message headers and body structure from the server and build an object structure.

get_message(integer $uid, string $folder = null) : object
abstract

Arguments

$uid

integer

Message UID to fetch

$folder

string

Folder to read from

Response

object

rcube_message_header Message data

Return message headers object of a specific message

get_message_headers( $uid, string $folder = null, boolean $force = false) : \rcube_message_header
abstract

Arguments

$uid

$folder

string

Folder to read from

$force

boolean

True to skip cache

Response

\rcube_message_header

Message headers

Fetch message body of a specific message from the server

get_message_part(integer $uid, string $part = 1, \rcube_message_part $o_part = null, mixed $print = null, resource $fp = null, boolean $skip_charset_conv = false) : string
abstract

Arguments

$uid

integer

Message UID

$part

string

Part number

$o_part

\rcube_message_part

Part object created by get_structure()

$print

mixed

True to print part, ressource to write part contents in

$fp

resource

File pointer to save the message part

$skip_charset_conv

boolean

Disables charset conversion

Response

string

Message/part body if not printed

Returns folder metadata/annotations (GETMETADATA/GETANNOTATION).

get_metadata(string $folder, array $entries, array $options = array(), boolean $force = false) : array
abstract

Arguments

$folder

string

Folder name (empty for server metadata)

$entries

array

Entries

$options

array

Command options (with MAXSIZE and DEPTH keys)

$force

boolean

Disables cache use

Response

array

Metadata entry-value hash array on success, NULL on error

Get namespace

get_namespace(string $name = null) : array
abstract

Arguments

$name

string

Namespace array index: personal, other, shared, prefix

Response

array

Namespace data

Get connection/class option

get_option(string $name)

Arguments

$name

string

Option name

Gets internal list page number.

get_page() : integer

Response

integer

Page number

Get internal page size

get_pagesize() : integer

Response

integer

Number of messages to display on one page

Get mailbox quota information.

get_quota(string $folder = null) : mixed
abstract

Arguments

$folder

string

Folder name

Response

mixed

Quota info or False if not supported

Returns the whole message source as string (or saves to a file)

get_raw_body(integer $uid, resource $fp = null, string $part = null) : string
abstract

Arguments

$uid

integer

Message UID

$fp

resource

File pointer to save the message

$part

string

Optional message part ID

Response

string

Message source string

Returns the message headers as string

get_raw_headers(integer $uid, string $part = null) : string
abstract

Arguments

$uid

integer

Message UID

$part

string

Optional message part ID

Response

string

Message headers string

Returns code of last command response

get_response_code() : integer
abstract

Response

integer

Response code (class constant)

Return the saved search set.

get_search_set() : array
abstract

Response

array

Search set in driver specific format, NULL if search wasn't initialized

Return configured special folders

get_special_folders( $forced = false)

Arguments

$forced

Get current threading flag.

get_threading() : mixed

Response

mixed

Threading algorithm or False if THREAD is not supported or disabled

Return sorted list of message UIDs

index(string $folder = null, string $sort_field = null, string $sort_order = null) : \rcube_result_index|\rcube_result_thread
abstract

Arguments

$folder

string

Folder to get index from

$sort_field

string

Sort column

$sort_order

string

Sort order [ASC, DESC]

Response

\rcube_result_index|\rcube_result_thread

List of messages (UIDs)

Checks connection state.

is_connected() : boolean
abstract

Response

boolean

TRUE on success, FALSE on failure

Check if specified folder is a special folder

is_special_folder( $name)

Arguments

$name

Public method for listing message flags

list_flags(string $folder, array $uids, integer $mod_seq = null) : array
abstract

Arguments

$folder

string

Folder name

$uids

array

Message UIDs

$mod_seq

integer

Optional MODSEQ value

Response

array

Indexed array with message flags

Get a list of all folders available on the server.

list_folders(string $root = '', string $name = '*', mixed $filter = null, string $rights = null, boolean $skip_sort = false) : array
abstract

Arguments

$root

string

IMAP root dir

$name

string

Optional name pattern

$filter

mixed

Optional filter

$rights

string

Optional ACL requirements

$skip_sort

boolean

Enable to return unsorted list (for better performance)

Response

array

Indexed array with folder names

Get a list of subscribed folders.

list_folders_subscribed(string $root = '', string $name = '*', string $filter = null, string $rights = null, boolean $skip_sort = false) : array
abstract

Arguments

$root

string

Optional root folder

$name

string

Optional name pattern

$filter

string

Optional filter

$rights

string

Optional ACL requirements

$skip_sort

boolean

Enable to return unsorted list (for better performance)

Response

array

List of folders

Public method for listing headers.

list_messages(string $folder = null, integer $page = null, string $sort_field = null, string $sort_order = null, integer $slice) : array
abstract

Arguments

$folder

string

Folder name

$page

integer

Current page to list

$sort_field

string

Header field to sort by

$sort_order

string

Sort order [ASC|DESC]

$slice

integer

Number of slice items to extract from result array

Response

array

Indexed array with message header objects

Returns information about what rights can be granted to the user (identifier) in the ACL for the folder (LISTRIGHTS).

list_rights(string $folder, string $user) : array
abstract

Arguments

$folder

string

Folder name

$user

string

User name

Response

array

List of user rights

Modify folder name according to namespace.

mod_folder(string $folder, string $mode = 'out') : string
abstract

For output it removes prefix of the personal namespace if it's possible. For input it adds the prefix. Use it before creating a folder in root of the folders tree.

Arguments

$folder

string

Folder name

$mode

string

Mode name (out/in)

Response

string

Folder name

Move message(s) from one folder to another.

move_message(mixed $uids, string $to, string $from = null) : boolean
abstract

Arguments

$uids

mixed

Message UIDs as array or comma-separated string, or '*'

$to

string

Target folder

$from

string

Source folder

Response

boolean

True on success, False on error

Returns the set of rights that the current user has to a folder (MYRIGHTS).

my_rights(string $folder) : array
abstract

Arguments

$folder

string

Folder name

Response

array

MYRIGHTS response on success, NULL on error

Parse message UIDs input

parse_uids(mixed $uids) : array

Arguments

$uids

mixed

UIDs array or comma-separated list or '' or '1:'

Response

array

Two elements array with UIDs converted to list and ALL flag

Sends the whole message source to stdout

print_raw_body(integer $uid, boolean $formatted = true)
abstract

Arguments

$uid

integer

Message UID

$formatted

boolean

Enables line-ending formatting

Refresh saved search set

refresh_search() : array
abstract

Response

array

Current search set

Set a new name to an existing folder

rename_folder(string $folder, string $new_name) : boolean
abstract

Arguments

$folder

string

Folder to rename

$new_name

string

New folder name

Response

boolean

True on success, False on error

Append a mail message (source) to a specific folder.

save_message(string $folder, string|array &$message, string $headers = '', boolean $is_file = false, array $flags = array(), mixed $date = null) : integer|boolean
abstract

Arguments

$folder

string

Target folder

$message

string|array

The message source string or filename or array (of strings and file pointers)

$headers

string

Headers string if $message contains only the body

$is_file

boolean

True if $message is a filename

$flags

array

Message flags

$date

mixed

Message internal date

Response

integer|boolean

Appended message UID or True on success, False on error

Invoke search request to the server.

search(string $folder = null, string $str = 'ALL', string $charset = null, string $sort_field = null)
abstract
todo

: Search criteria should be provided in non-IMAP format, eg. array

Arguments

$folder

string

Folder name to search in

$str

string

Search criteria

$charset

string

Search charset

$sort_field

string

Header field to sort by

Direct (real and simple) search request (without result sorting and caching).

search_once(string $folder = null, string $str = 'ALL') : \rcube_result_index
abstract

Arguments

$folder

string

Folder name to search in

$str

string

Search string

Response

\rcube_result_index

Search result (UIDs)

Changes the ACL on the specified folder (SETACL)

set_acl(string $folder, string $user, string $acl) : boolean
abstract

Arguments

$folder

string

Folder name

$user

string

User name

$acl

string

ACL string

Response

boolean

True on success, False on failure

Set default message charset.

set_charset(string $cs)

This will be used for message decoding if a charset specification is not available

Arguments

$cs

string

Charset string

Activate/deactivate debug mode.

set_debug(boolean $dbg = true)
abstract

Arguments

$dbg

boolean

True if conversation with the server should be logged

Set message flag to one or several messages

set_flag(mixed $uids, string $flag, string $folder = null, boolean $skip_cache = false) : boolean
abstract

Arguments

$uids

mixed

Message UIDs as array or comma-separated string, or '*'

$flag

string

Flag to set: SEEN, UNDELETED, DELETED, RECENT, ANSWERED, DRAFT, MDNSENT

$folder

string

Folder name

$skip_cache

boolean

True to skip message cache clean up

Response

boolean

Operation status

Set internal folder reference.

set_folder(string $folder)

All operations will be perfomed on this folder.

Arguments

$folder

string

Folder name

Sets metadata/annotations (SETMETADATA/SETANNOTATION)

set_metadata(string $folder, array $entries) : boolean
abstract

Arguments

$folder

string

Folder name (empty for server metadata)

$entries

array

Entry-value array (use NULL value as NIL)

Response

boolean

True on success, False on failure

Set connection and class options

set_options(array $opt)

Arguments

$opt

array

Options array

Set internal list page number.

set_page(integer $page)

Arguments

$page

integer

Page number to list

Set internal page size

set_pagesize(integer $size)

Arguments

$size

integer

Number of messages to display on one page

Save a search result for future message listing methods.

set_search_set(mixed $set)
abstract

Arguments

$set

mixed

Search set in driver specific format

Set special folder associations stored in backend

set_special_folders( $specials)

Arguments

$specials

Sets threading flag to the best supported THREAD algorithm.

set_threading(boolean $enable = false) : mixed

Enable/Disable threaded mode.

Arguments

$enable

boolean

TRUE to enable and FALSE

Response

mixed

Threading algorithm or False if THREAD is not supported

Subscribe to a specific folder(s)

subscribe(array $folders) : boolean
abstract

Arguments

$folders

array

Folder name(s)

Response

boolean

True on success

Remove message flag for one or several messages

unset_flag(mixed $uids, string $flag, string $folder = null) : boolean
see \set_flag

Arguments

$uids

mixed

Message UIDs as array or comma-separated string, or '*'

$flag

string

Flag to unset: SEEN, DELETED, RECENT, ANSWERED, DRAFT, MDNSENT

$folder

string

Folder name

Response

boolean

Operation status

Unsubscribe folder(s)

unsubscribe(array $folders) : boolean
abstract

Arguments

$folders

array

Folder name(s)

Response

boolean

True on success

Constants

UNKNOWN

UNKNOWN

NOPERM

NOPERM

READONLY

READONLY

TRYCREATE

TRYCREATE

INUSE

INUSE

OVERQUOTA

OVERQUOTA

ALREADYEXISTS

ALREADYEXISTS

NONEXISTENT

NONEXISTENT

CONTACTADMIN

CONTACTADMIN

Properties

Instance of connection object e.g. rcube_imap_generic

conn : mixed
var

Type(s)

mixed

List of supported special folder types

folder_types : array
static
var

Type(s)

array

folder

folder :

Type(s)

default_charset

default_charset :

Type(s)

search_set

search_set :

Type(s)

options

options :

Type(s)

page_size

page_size :

Type(s)

list_page

list_page :

Type(s)

threading

threading :

Type(s)

All (additional) headers used (in any way) by Roundcube Not listed here: DATE, FROM, TO, CC, REPLY-TO, SUBJECT, CONTENT-TYPE, LIST-POST (used for messages listing) are hardcoded in rcube_imap_generic::fetchHeaders()

all_headers : array
var

Type(s)

array