Roundcube Webmail
Back to top  

rcube_storage

Abstract class for accessing mail messages storage server

package

Framework
subpackage

Storage
author

Thomas Bruederli

author

Aleksander Machniak

Methods

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

Close connection. Usually done on script shutdown

close()
abstract

Checks connection state.

is_connected() : boolean
abstract

Response

boolean

TRUE on success, FALSE on failure

Check connection state, connect if not connected.

check_connection() : bool
abstract

Response

bool

Connection state.

Returns code of last error

get_error_code() : int
abstract

Response

int

Error code

Returns message of last error

get_error_str() : string
abstract

Response

string

Error message

Returns code of last command response

get_response_code() : int
abstract

Response

int

Response code (class constant)

Set connection and class options

set_options(array $opt)

Arguments

$opt

array

Options array

Activate/deactivate debug mode.

set_debug(boolean $dbg = true)
abstract

Arguments

$dbg

boolean

True if conversation with the server should be logged

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

This list of folders will be listed above all other folders

set_default_folders(array $arr)

Arguments

$arr

array

Indexed list of folder names

Set internal folder reference.

set_folder(string $folder)

All operations will be perfomed on this folder.

Arguments

$folder

string

Folder name

Returns the currently used folder name

get_folder() : string

Response

string

Name of the folder

Set internal list page number.

set_page(int $page)

Arguments

$page

int

Page number to list

Gets internal list page number.

get_page() : int

Response

int

Page number

Set internal page size

set_pagesize(int $size)

Arguments

$size

int

Number of messages to display on one page

Get internal page size

get_pagesize() : int

Response

int

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

Return the saved search set.

get_search_set() : array
abstract

Response

array

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

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

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

Get current threading flag.

get_threading() : mixed

Response

mixed

Threading algorithm or False if THREAD is not supported or disabled

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

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

get_hierarchy_delimiter() : string
abstract

Response

string

Delimiter string

Get namespace

get_namespace(string $name = null) : array
abstract

Arguments

$name

string

Namespace array index: personal, other, shared, prefix

Response

array

Namespace data

Get messages count for a specific folder.

count(string $folder = null, string $mode = 'ALL', boolean $force = false, boolean $status = true) : int
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

int

Number of messages

Public method for listing message flags

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

Arguments

$folder

string

Folder name

$uids

array

Message UIDs

$mod_seq

int

Optional MODSEQ value

Response

array

Indexed array with message flags

Public method for listing headers.

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

Arguments

$folder

string

Folder name

$page

int

Current page to list

$sort_field

string

Header field to sort by

$sort_order

string

Sort order [ASC|DESC]

$slice

int

Number of slice items to extract from result array

Response

array

Indexed array with message header objects

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)

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)

Refresh saved search set

refresh_search() : array
abstract

Response

array

Current search set

Fetch message headers and body structure from the server and build an object structure similar to the one generated by PEAR::Mail_mimeDecode

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

Arguments

$uid

int

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, bool $force = false) : \rcube_message_header
abstract

Arguments

$uid

$folder

string

Folder to read from

$force

bool

True to skip cache

Response

\rcube_message_header

Message headers

Fetch message body of a specific message from the server

get_message_part(int $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

int

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

Fetch message body of a specific message from the server

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

Arguments

$uid

int

Message UID

$part

Response

string

$part Message/part body

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

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

Arguments

$uid

int

Message UID

$fp

resource

File pointer to save the message

Response

string

Message source string

Returns the message headers as string

get_raw_headers(int $uid) : string
abstract

Arguments

$uid

int

Message UID

Response

string

Message headers string

Sends the whole message source to stdout

print_raw_body(int $uid, bool $formatted = true)
abstract

Arguments

$uid

int

Message UID

$formatted

bool

Enables line-ending formatting

Set message flag to one or several messages

set_flag(mixed $uids, string $flag, string $folder = null, boolean $skip_cache = false) : bool
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

bool

Operation status

Remove message flag for one or several messages

unset_flag(mixed $uids, string $flag, string $folder = null) : bool
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

bool

Operation status

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) : int|bool
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

int|bool

Appended message UID or True on success, False on error

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

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

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

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

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

Get a list of subscribed folders.

list_folders_subscribed(string $root = '', string $name = '*', string $filter = null, string $rights = null, bool $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

bool

Enable to return unsorted list (for better performance)

Response

array

List of folders

Get a list of all folders available on the server.

list_folders(string $root = '', string $name = '*', mixed $filter = null, string $rights = null, bool $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

bool

Enable to return unsorted list (for better performance)

Response

array

Indexed array with folder names

Subscribe to a specific folder(s)

subscribe(array $folders) : boolean
abstract

Arguments

$folders

array

Folder name(s)

Response

boolean

True on success

Unsubscribe folder(s)

unsubscribe(array $folders) : boolean
abstract

Arguments

$folders

array

Folder name(s)

Response

boolean

True on success

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

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

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

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

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

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

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

folder_size(string $folder) : int
abstract

Arguments

$folder

string

Folder name

Response

int

Folder size in bytes, False on error

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'

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

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

Arguments

$folder

string

Folder name

$force

bool

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

Returns extended information about the folder.

folder_info(string $folder) : array
abstract

Arguments

$folder

string

Folder name

Response

array

Data

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

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

Arguments

$folder

string

Folder name

$diff

array

Difference data

Response

int

Folder status

Synchronizes messages cache.

folder_sync(string $folder)
abstract

Arguments

$folder

string

Folder name

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

Create all folders specified as default

create_default_folders()

Get mailbox quota information.

get_quota() : mixed
abstract

Response

mixed

Quota info or False if not supported

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

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

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

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

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

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

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

Returns folder metadata/annotations (GETMETADATA/GETANNOTATION).

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

Arguments

$folder

string

Folder name (empty for server metadata)

$entries

array

Entries

$options

array

Command options (with MAXSIZE and DEPTH keys)

Response

array

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

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

Returns cached value

get_cache(string $key) : mixed
abstract

Arguments

$key

string

Cache key

Response

mixed

Cached value

Delete outdated cache entries

cache_gc()
abstract

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

folder

folder :

default_charset

default_charset :

default_folders

default_folders :

search_set

search_set :

options

options :

page_size

page_size :

threading

threading :

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