githubFork/roundcubemail.git

Fix LIMIT/OFFSET queries handling on MS SQL Server (#1488984) - require ver...

Aleksander Machniak

2013-03-11 ec6a77bab27984ce05b003af07ac9f42ca410d94

commit \| author \| age
c321a9	1	<?php
T	2
	3	/*
	4	+-----------------------------------------------------------------------+
	5	\| This file is part of the Roundcube Webmail client \|
	6	\| Copyright (C) 2005-2012, The Roundcube Dev Team \|
	7	\| Copyright (C) 2012, Kolab Systems AG \|
7fe381	8	\| \|
T	9	\| Licensed under the GNU General Public License version 3 or \|
	10	\| any later version with exceptions for skins & plugins. \|
	11	\| See the README file for a full license statement. \|
c321a9	12	\| \|
T	13	\| PURPOSE: \|
	14	\| Mail Storage Engine \|
	15	+-----------------------------------------------------------------------+
	16	\| Author: Thomas Bruederli <roundcube@gmail.com> \|
	17	\| Author: Aleksander Machniak <alec@alec.pl> \|
	18	+-----------------------------------------------------------------------+
	19	*/
	20
	21	/**
	22	* Abstract class for accessing mail messages storage server
	23	*
9ab346	24	* @package Framework
AM	25	* @subpackage Storage
	26	* @author Thomas Bruederli <roundcube@gmail.com>
	27	* @author Aleksander Machniak <alec@alec.pl>
c321a9	28	*/
T	29	abstract class rcube_storage
	30	{
	31	/**
	32	* Instance of connection object e.g. rcube_imap_generic
	33	*
	34	* @var mixed
	35	*/
	36	public $conn;
	37
	38	protected $folder = 'INBOX';
	39	protected $default_charset = 'ISO-8859-1';
	40	protected $default_folders = array('INBOX');
	41	protected $search_set;
	42	protected $options = array('auth_method' => 'check');
	43	protected $page_size = 10;
	44	protected $threading = false;
	45
	46	/**
	47	* All (additional) headers used (in any way) by Roundcube
	48	* Not listed here: DATE, FROM, TO, CC, REPLY-TO, SUBJECT, CONTENT-TYPE, LIST-POST
	49	* (used for messages listing) are hardcoded in rcube_imap_generic::fetchHeaders()
	50	*
	51	* @var array
	52	*/
	53	protected $all_headers = array(
	54	'IN-REPLY-TO',
	55	'BCC',
83370e	56	'SENDER',
c321a9	57	'MESSAGE-ID',
T	58	'CONTENT-TRANSFER-ENCODING',
	59	'REFERENCES',
	60	'X-DRAFT-INFO',
	61	'MAIL-FOLLOWUP-TO',
	62	'MAIL-REPLY-TO',
	63	'RETURN-PATH',
30cc01	64	'DELIVERED-TO',
bb5d72	65	'ENVELOPE-TO',
c321a9	66	);
T	67
	68	const UNKNOWN = 0;
	69	const NOPERM = 1;
	70	const READONLY = 2;
	71	const TRYCREATE = 3;
	72	const INUSE = 4;
	73	const OVERQUOTA = 5;
	74	const ALREADYEXISTS = 6;
	75	const NONEXISTENT = 7;
	76	const CONTACTADMIN = 8;
	77
	78
	79	/**
	80	* Connect to the server
	81	*
	82	* @param string $host Host to connect
	83	* @param string $user Username for IMAP account
	84	* @param string $pass Password for IMAP account
	85	* @param integer $port Port to connect to
	86	* @param string $use_ssl SSL schema (either ssl or tls) or null if plain connection
	87	*
	88	* @return boolean TRUE on success, FALSE on failure
	89	*/
	90	abstract function connect($host, $user, $pass, $port = 143, $use_ssl = null);
	91
	92
	93	/**
	94	* Close connection. Usually done on script shutdown
	95	*/
	96	abstract function close();
	97
	98
	99	/**
	100	* Checks connection state.
	101	*
	102	* @return boolean TRUE on success, FALSE on failure
	103	*/
	104	abstract function is_connected();
	105
	106
	107	/**
8eae72	108	* Check connection state, connect if not connected.
A	109	*
	110	* @return bool Connection state.
	111	*/
	112	abstract function check_connection();
	113
	114
	115	/**
c321a9	116	* Returns code of last error
T	117	*
	118	* @return int Error code
	119	*/
	120	abstract function get_error_code();
	121
	122
	123	/**
	124	* Returns message of last error
	125	*
	126	* @return string Error message
	127	*/
	128	abstract function get_error_str();
	129
	130
	131	/**
	132	* Returns code of last command response
	133	*
	134	* @return int Response code (class constant)
	135	*/
	136	abstract function get_response_code();
	137
	138
	139	/**
	140	* Set connection and class options
	141	*
	142	* @param array $opt Options array
	143	*/
	144	public function set_options($opt)
	145	{
	146	$this->options = array_merge($this->options, (array)$opt);
	147	}
	148
	149
	150	/**
	151	* Activate/deactivate debug mode.
	152	*
	153	* @param boolean $dbg True if conversation with the server should be logged
	154	*/
	155	abstract function set_debug($dbg = true);
	156
	157
	158	/**
	159	* Set default message charset.
	160	*
	161	* This will be used for message decoding if a charset specification is not available
	162	*
	163	* @param string $cs Charset string
	164	*/
	165	public function set_charset($cs)
	166	{
	167	$this->default_charset = $cs;
	168	}
	169
	170
	171	/**
	172	* This list of folders will be listed above all other folders
	173	*
	174	* @param array $arr Indexed list of folder names
	175	*/
	176	public function set_default_folders($arr)
	177	{
	178	if (is_array($arr)) {
	179	$this->default_folders = $arr;
	180
	181	// add inbox if not included
	182	if (!in_array('INBOX', $this->default_folders)) {
	183	array_unshift($this->default_folders, 'INBOX');
	184	}
	185	}
	186	}
	187
	188
	189	/**
	190	* Set internal folder reference.
	191	* All operations will be perfomed on this folder.
	192	*
	193	* @param string $folder Folder name
	194	*/
	195	public function set_folder($folder)
	196	{
10562d	197	if ($this->folder === $folder) {
c321a9	198	return;
T	199	}
	200
	201	$this->folder = $folder;
	202	}
	203
	204
	205	/**
	206	* Returns the currently used folder name
	207	*
	208	* @return string Name of the folder
	209	*/
	210	public function get_folder()
	211	{
	212	return $this->folder;
	213	}
	214
	215
	216	/**
	217	* Set internal list page number.
	218	*
	219	* @param int $page Page number to list
	220	*/
	221	public function set_page($page)
	222	{
	223	$this->list_page = (int) $page;
	224	}
	225
	226
	227	/**
	228	* Gets internal list page number.
	229	*
	230	* @return int Page number
	231	*/
	232	public function get_page()
	233	{
	234	return $this->list_page;
	235	}
	236
	237
	238	/**
	239	* Set internal page size
	240	*
	241	* @param int $size Number of messages to display on one page
	242	*/
	243	public function set_pagesize($size)
	244	{
	245	$this->page_size = (int) $size;
	246	}
	247
	248
	249	/**
	250	* Get internal page size
	251	*
	252	* @return int Number of messages to display on one page
	253	*/
	254	public function get_pagesize()
	255	{
	256	return $this->page_size;
	257	}
	258
	259
	260	/**
	261	* Save a search result for future message listing methods.
	262	*
	263	* @param mixed $set Search set in driver specific format
	264	*/
	265	abstract function set_search_set($set);
	266
	267
	268	/**
	269	* Return the saved search set.
	270	*
	271	* @return array Search set in driver specific format, NULL if search wasn't initialized
	272	*/
	273	abstract function get_search_set();
	274
	275
	276	/**
	277	* Returns the storage server's (IMAP) capability
	278	*
	279	* @param string $cap Capability name
	280	*
	281	* @return mixed Capability value or TRUE if supported, FALSE if not
	282	*/
	283	abstract function get_capability($cap);
	284
	285
	286	/**
	287	* Sets threading flag to the best supported THREAD algorithm.
	288	* Enable/Disable threaded mode.
	289	*
	290	* @param boolean $enable TRUE to enable and FALSE
	291	*
	292	* @return mixed Threading algorithm or False if THREAD is not supported
	293	*/
	294	public function set_threading($enable = false)
	295	{
	296	$this->threading = false;
	297
	298	if ($enable && ($caps = $this->get_capability('THREAD'))) {
	299	$methods = array('REFS', 'REFERENCES', 'ORDEREDSUBJECT');
	300	$methods = array_intersect($methods, $caps);
	301
	302	$this->threading = array_shift($methods);
	303	}
	304
	305	return $this->threading;
	306	}
	307
	308
	309	/**
	310	* Get current threading flag.
	311	*
	312	* @return mixed Threading algorithm or False if THREAD is not supported or disabled
	313	*/
	314	public function get_threading()
	315	{
	316	return $this->threading;
	317	}
	318
	319
	320	/**
	321	* Checks the PERMANENTFLAGS capability of the current folder
	322	* and returns true if the given flag is supported by the server.
	323	*
	324	* @param string $flag Permanentflag name
	325	*
	326	* @return boolean True if this flag is supported
	327	*/
	328	abstract function check_permflag($flag);
	329
	330
	331	/**
	332	* Returns the delimiter that is used by the server
	333	* for folder hierarchy separation.
	334	*
	335	* @return string Delimiter string
	336	*/
	337	abstract function get_hierarchy_delimiter();
	338
	339
	340	/**
	341	* Get namespace
	342	*
	343	* @param string $name Namespace array index: personal, other, shared, prefix
	344	*
	345	* @return array Namespace data
	346	*/
	347	abstract function get_namespace($name = null);
	348
	349
	350	/**
	351	* Get messages count for a specific folder.
	352	*
	353	* @param string $folder Folder name
0435f4	354	* @param string $mode Mode for count [ALL\|THREADS\|UNSEEN\|RECENT\|EXISTS]
c321a9	355	* @param boolean $force Force reading from server and update cache
T	356	* @param boolean $status Enables storing folder status info (max UID/count),
	357	* required for folder_status()
	358	*
	359	* @return int Number of messages
	360	*/
	361	abstract function count($folder = null, $mode = 'ALL', $force = false, $status = true);
	362
	363
	364	/**
	365	* Public method for listing headers.
	366	*
	367	* @param string $folder Folder name
	368	* @param int $page Current page to list
	369	* @param string $sort_field Header field to sort by
	370	* @param string $sort_order Sort order [ASC\|DESC]
	371	* @param int $slice Number of slice items to extract from result array
	372	*
	373	* @return array Indexed array with message header objects
	374	*/
	375	abstract function list_messages($folder = null, $page = null, $sort_field = null, $sort_order = null, $slice = 0);
	376
	377
	378	/**
	379	* Return sorted list of message UIDs
	380	*
	381	* @param string $folder Folder to get index from
	382	* @param string $sort_field Sort column
	383	* @param string $sort_order Sort order [ASC, DESC]
	384	*
	385	* @return rcube_result_index\|rcube_result_thread List of messages (UIDs)
	386	*/
	387	abstract function index($folder = null, $sort_field = null, $sort_order = null);
	388
	389
	390	/**
	391	* Invoke search request to the server.
	392	*
	393	* @param string $folder Folder name to search in
	394	* @param string $str Search criteria
	395	* @param string $charset Search charset
	396	* @param string $sort_field Header field to sort by
	397	*
	398	* @todo: Search criteria should be provided in non-IMAP format, eg. array
	399	*/
	400	abstract function search($folder = null, $str = 'ALL', $charset = null, $sort_field = null);
	401
	402
	403	/**
	404	* Direct (real and simple) search request (without result sorting and caching).
	405	*
	406	* @param string $folder Folder name to search in
	407	* @param string $str Search string
	408	*
	409	* @return rcube_result_index Search result (UIDs)
	410	*/
	411	abstract function search_once($folder = null, $str = 'ALL');
	412
	413
	414	/**
	415	* Refresh saved search set
	416	*
	417	* @return array Current search set
	418	*/
	419	abstract function refresh_search();
	420
	421
	422	/* --------------------------------
	423	* messages management
	424	* --------------------------------*/
	425
	426	/**
	427	* Fetch message headers and body structure from the server and build
	428	* an object structure similar to the one generated by PEAR::Mail_mimeDecode
	429	*
	430	* @param int $uid Message UID to fetch
	431	* @param string $folder Folder to read from
	432	*
0c2596	433	* @return object rcube_message_header Message data
c321a9	434	*/
T	435	abstract function get_message($uid, $folder = null);
	436
	437
	438	/**
	439	* Return message headers object of a specific message
	440	*
	441	* @param int $id Message sequence ID or UID
	442	* @param string $folder Folder to read from
	443	* @param bool $force True to skip cache
	444	*
0c2596	445	* @return rcube_message_header Message headers
c321a9	446	*/
T	447	abstract function get_message_headers($uid, $folder = null, $force = false);
	448
	449
	450	/**
	451	* Fetch message body of a specific message from the server
	452	*
	453	* @param int $uid Message UID
	454	* @param string $part Part number
	455	* @param rcube_message_part $o_part Part object created by get_structure()
	456	* @param mixed $print True to print part, ressource to write part contents in
	457	* @param resource $fp File pointer to save the message part
	458	* @param boolean $skip_charset_conv Disables charset conversion
	459	*
	460	* @return string Message/part body if not printed
	461	*/
	462	abstract function get_message_part($uid, $part = 1, $o_part = null, $print = null, $fp = null, $skip_charset_conv = false);
	463
	464
	465	/**
	466	* Fetch message body of a specific message from the server
	467	*
	468	* @param int $uid Message UID
	469	*
	470	* @return string $part Message/part body
	471	* @see rcube_imap::get_message_part()
	472	*/
	473	public function get_body($uid, $part = 1)
	474	{
	475	$headers = $this->get_message_headers($uid);
0c2596	476	return rcube_charset::convert($this->get_message_part($uid, $part, null),
c321a9	477	$headers->charset ? $headers->charset : $this->default_charset);
T	478	}
	479
	480
	481	/**
	482	* Returns the whole message source as string (or saves to a file)
	483	*
	484	* @param int $uid Message UID
	485	* @param resource $fp File pointer to save the message
	486	*
	487	* @return string Message source string
	488	*/
	489	abstract function get_raw_body($uid, $fp = null);
	490
	491
	492	/**
	493	* Returns the message headers as string
	494	*
	495	* @param int $uid Message UID
	496	*
	497	* @return string Message headers string
	498	*/
	499	abstract function get_raw_headers($uid);
	500
	501
	502	/**
	503	* Sends the whole message source to stdout
fb2f82	504	*
AM	505	* @param int $uid Message UID
	506	* @param bool $formatted Enables line-ending formatting
c321a9	507	*/
fb2f82	508	abstract function print_raw_body($uid, $formatted = true);
c321a9	509
T	510
	511	/**
	512	* Set message flag to one or several messages
	513	*
	514	* @param mixed $uids Message UIDs as array or comma-separated string, or '*'
	515	* @param string $flag Flag to set: SEEN, UNDELETED, DELETED, RECENT, ANSWERED, DRAFT, MDNSENT
	516	* @param string $folder Folder name
	517	* @param boolean $skip_cache True to skip message cache clean up
	518	*
	519	* @return bool Operation status
	520	*/
	521	abstract function set_flag($uids, $flag, $folder = null, $skip_cache = false);
	522
	523
	524	/**
	525	* Remove message flag for one or several messages
	526	*
	527	* @param mixed $uids Message UIDs as array or comma-separated string, or '*'
	528	* @param string $flag Flag to unset: SEEN, DELETED, RECENT, ANSWERED, DRAFT, MDNSENT
	529	* @param string $folder Folder name
	530	*
	531	* @return bool Operation status
	532	* @see set_flag
	533	*/
	534	public function unset_flag($uids, $flag, $folder = null)
	535	{
	536	return $this->set_flag($uids, 'UN'.$flag, $folder);
	537	}
	538
	539
	540	/**
	541	* Append a mail message (source) to a specific folder.
	542	*
	543	* @param string $folder Target folder
	544	* @param string $message The message source string or filename
	545	* @param string $headers Headers string if $message contains only the body
	546	* @param boolean $is_file True if $message is a filename
7ac533	547	* @param array $flags Message flags
AM	548	* @param mixed $date Message internal date
c321a9	549	*
T	550	* @return int\|bool Appended message UID or True on success, False on error
	551	*/
7ac533	552	abstract function save_message($folder, &$message, $headers = '', $is_file = false, $flags = array(), $date = null);
c321a9	553
T	554
	555	/**
	556	* Move message(s) from one folder to another.
	557	*
	558	* @param mixed $uids Message UIDs as array or comma-separated string, or '*'
	559	* @param string $to Target folder
	560	* @param string $from Source folder
	561	*
	562	* @return boolean True on success, False on error
	563	*/
	564	abstract function move_message($uids, $to, $from = null);
	565
	566
	567	/**
	568	* Copy message(s) from one mailbox to another.
	569	*
	570	* @param mixed $uids Message UIDs as array or comma-separated string, or '*'
	571	* @param string $to Target folder
	572	* @param string $from Source folder
	573	*
	574	* @return boolean True on success, False on error
	575	*/
	576	abstract function copy_message($uids, $to, $from = null);
	577
	578
	579	/**
	580	* Mark message(s) as deleted and expunge.
	581	*
	582	* @param mixed $uids Message UIDs as array or comma-separated string, or '*'
	583	* @param string $folder Source folder
	584	*
	585	* @return boolean True on success, False on error
	586	*/
	587	abstract function delete_message($uids, $folder = null);
	588
	589
	590	/**
	591	* Expunge message(s) and clear the cache.
	592	*
	593	* @param mixed $uids Message UIDs as array or comma-separated string, or '*'
	594	* @param string $folder Folder name
	595	* @param boolean $clear_cache False if cache should not be cleared
	596	*
	597	* @return boolean True on success, False on error
	598	*/
	599	abstract function expunge_message($uids, $folder = null, $clear_cache = true);
	600
	601
	602	/**
	603	* Parse message UIDs input
	604	*
	605	* @param mixed $uids UIDs array or comma-separated list or '' or '1:'
	606	*
	607	* @return array Two elements array with UIDs converted to list and ALL flag
	608	*/
	609	protected function parse_uids($uids)
	610	{
	611	if ($uids === '' \|\| $uids === '1:') {
	612	if (empty($this->search_set)) {
	613	$uids = '1:*';
	614	$all = true;
	615	}
	616	// get UIDs from current search set
	617	else {
	618	$uids = join(',', $this->search_set->get());
	619	}
	620	}
	621	else {
	622	if (is_array($uids)) {
	623	$uids = join(',', $uids);
	624	}
	625
	626	if (preg_match('/[^0-9,]/', $uids)) {
	627	$uids = '';
	628	}
	629	}
	630
	631	return array($uids, (bool) $all);
	632	}
	633
	634
	635	/* --------------------------------
	636	* folder managment
	637	* --------------------------------*/
	638
	639	/**
	640	* Get a list of subscribed folders.
	641	*
	642	* @param string $root Optional root folder
	643	* @param string $name Optional name pattern
	644	* @param string $filter Optional filter
	645	* @param string $rights Optional ACL requirements
	646	* @param bool $skip_sort Enable to return unsorted list (for better performance)
	647	*
	648	* @return array List of folders
	649	*/
	650	abstract function list_folders_subscribed($root = '', $name = '*', $filter = null, $rights = null, $skip_sort = false);
	651
	652
	653	/**
	654	* Get a list of all folders available on the server.
	655	*
	656	* @param string $root IMAP root dir
	657	* @param string $name Optional name pattern
	658	* @param mixed $filter Optional filter
	659	* @param string $rights Optional ACL requirements
	660	* @param bool $skip_sort Enable to return unsorted list (for better performance)
	661	*
	662	* @return array Indexed array with folder names
	663	*/
	664	abstract function list_folders($root = '', $name = '*', $filter = null, $rights = null, $skip_sort = false);
	665
	666
	667	/**
	668	* Subscribe to a specific folder(s)
	669	*
	670	* @param array $folders Folder name(s)
	671	*
	672	* @return boolean True on success
	673	*/
	674	abstract function subscribe($folders);
	675
	676
	677	/**
	678	* Unsubscribe folder(s)
	679	*
	680	* @param array $folders Folder name(s)
	681	*
	682	* @return boolean True on success
	683	*/
	684	abstract function unsubscribe($folders);
	685
	686
	687	/**
	688	* Create a new folder on the server.
	689	*
	690	* @param string $folder New folder name
	691	* @param boolean $subscribe True if the newvfolder should be subscribed
	692	*
	693	* @return boolean True on success, False on error
	694	*/
	695	abstract function create_folder($folder, $subscribe = false);
	696
	697
	698	/**
	699	* Set a new name to an existing folder
	700	*
	701	* @param string $folder Folder to rename
	702	* @param string $new_name New folder name
	703	*
	704	* @return boolean True on success, False on error
	705	*/
	706	abstract function rename_folder($folder, $new_name);
	707
	708
	709	/**
	710	* Remove a folder from the server.
	711	*
	712	* @param string $folder Folder name
	713	*
	714	* @return boolean True on success, False on error
	715	*/
	716	abstract function delete_folder($folder);
	717
	718
	719	/**
	720	* Send expunge command and clear the cache.
	721	*
	722	* @param string $folder Folder name
	723	* @param boolean $clear_cache False if cache should not be cleared
	724	*
	725	* @return boolean True on success, False on error
	726	*/
	727	public function expunge_folder($folder = null, $clear_cache = true)
	728	{
	729	return $this->expunge_message('*', $folder, $clear_cache);
	730	}
	731
	732
	733	/**
	734	* Remove all messages in a folder..
	735	*
	736	* @param string $folder Folder name
	737	*
	738	* @return boolean True on success, False on error
	739	*/
	740	public function clear_folder($folder = null)
	741	{
	742	return $this->delete_message('*', $folder);
	743	}
	744
	745
	746	/**
	747	* Checks if folder exists and is subscribed
	748	*
	749	* @param string $folder Folder name
	750	* @param boolean $subscription Enable subscription checking
	751	*
	752	* @return boolean True if folder exists, False otherwise
	753	*/
	754	abstract function folder_exists($folder, $subscription = false);
	755
	756
	757	/**
	758	* Get folder size (size of all messages in a folder)
	759	*
	760	* @param string $folder Folder name
	761	*
	762	* @return int Folder size in bytes, False on error
	763	*/
	764	abstract function folder_size($folder);
	765
	766
	767	/**
	768	* Returns the namespace where the folder is in
	769	*
	770	* @param string $folder Folder name
	771	*
	772	* @return string One of 'personal', 'other' or 'shared'
	773	*/
	774	abstract function folder_namespace($folder);
	775
	776
	777	/**
	778	* Gets folder attributes (from LIST response, e.g. \Noselect, \Noinferiors).
	779	*
	780	* @param string $folder Folder name
	781	* @param bool $force Set to True if attributes should be refreshed
	782	*
	783	* @return array Options list
	784	*/
	785	abstract function folder_attributes($folder, $force = false);
	786
	787
	788	/**
	789	* Gets connection (and current folder) data: UIDVALIDITY, EXISTS, RECENT,
	790	* PERMANENTFLAGS, UIDNEXT, UNSEEN
	791	*
	792	* @param string $folder Folder name
	793	*
	794	* @return array Data
	795	*/
	796	abstract function folder_data($folder);
	797
	798
	799	/**
	800	* Returns extended information about the folder.
	801	*
	802	* @param string $folder Folder name
	803	*
	804	* @return array Data
	805	*/
	806	abstract function folder_info($folder);
	807
	808
	809	/**
	810	* Returns current status of a folder
	811	*
	812	* @param string $folder Folder name
	813	*
	814	* @return int Folder status
	815	*/
	816	abstract function folder_status($folder = null);
	817
	818
	819	/**
	820	* Synchronizes messages cache.
	821	*
	822	* @param string $folder Folder name
	823	*/
	824	abstract function folder_sync($folder);
	825
	826
	827	/**
	828	* Modify folder name according to namespace.
	829	* For output it removes prefix of the personal namespace if it's possible.
	830	* For input it adds the prefix. Use it before creating a folder in root
	831	* of the folders tree.
	832	*
	833	* @param string $folder Folder name
	834	* @param string $mode Mode name (out/in)
	835	*
	836	* @return string Folder name
	837	*/
	838	abstract function mod_folder($folder, $mode = 'out');
	839
	840
	841	/**
	842	* Create all folders specified as default
	843	*/
	844	public function create_default_folders()
	845	{
	846	// create default folders if they do not exist
	847	foreach ($this->default_folders as $folder) {
	848	if (!$this->folder_exists($folder)) {
	849	$this->create_folder($folder, true);
	850	}
	851	else if (!$this->folder_exists($folder, true)) {
	852	$this->subscribe($folder);
	853	}
	854	}
	855	}
	856
	857
	858	/**
	859	* Get mailbox quota information.
	860	*
	861	* @return mixed Quota info or False if not supported
	862	*/
	863	abstract function get_quota();
	864
	865
	866	/* -----------------------------------------
	867	* ACL and METADATA methods
	868	* ----------------------------------------*/
	869
	870	/**
	871	* Changes the ACL on the specified folder (SETACL)
	872	*
	873	* @param string $folder Folder name
	874	* @param string $user User name
	875	* @param string $acl ACL string
	876	*
	877	* @return boolean True on success, False on failure
	878	*/
	879	abstract function set_acl($folder, $user, $acl);
	880
	881
	882	/**
	883	* Removes any <identifier,rights> pair for the
	884	* specified user from the ACL for the specified
	885	* folder (DELETEACL).
	886	*
	887	* @param string $folder Folder name
	888	* @param string $user User name
	889	*
	890	* @return boolean True on success, False on failure
	891	*/
	892	abstract function delete_acl($folder, $user);
	893
	894
	895	/**
	896	* Returns the access control list for a folder (GETACL).
	897	*
	898	* @param string $folder Folder name
	899	*
	900	* @return array User-rights array on success, NULL on error
	901	*/
	902	abstract function get_acl($folder);
	903
	904
	905	/**
	906	* Returns information about what rights can be granted to the
	907	* user (identifier) in the ACL for the folder (LISTRIGHTS).
	908	*
	909	* @param string $folder Folder name
	910	* @param string $user User name
	911	*
	912	* @return array List of user rights
	913	*/
	914	abstract function list_rights($folder, $user);
	915
	916
	917	/**
	918	* Returns the set of rights that the current user has to a folder (MYRIGHTS).
	919	*
	920	* @param string $folder Folder name
	921	*
	922	* @return array MYRIGHTS response on success, NULL on error
	923	*/
	924	abstract function my_rights($folder);
	925
	926
	927	/**
	928	* Sets metadata/annotations (SETMETADATA/SETANNOTATION)
	929	*
	930	* @param string $folder Folder name (empty for server metadata)
	931	* @param array $entries Entry-value array (use NULL value as NIL)
	932	*
	933	* @return boolean True on success, False on failure
	934	*/
	935	abstract function set_metadata($folder, $entries);
	936
	937
	938	/**
	939	* Unsets metadata/annotations (SETMETADATA/SETANNOTATION)
	940	*
	941	* @param string $folder Folder name (empty for server metadata)
	942	* @param array $entries Entry names array
	943	*
	944	* @return boolean True on success, False on failure
	945	*/
	946	abstract function delete_metadata($folder, $entries);
	947
	948
	949	/**
	950	* Returns folder metadata/annotations (GETMETADATA/GETANNOTATION).
	951	*
	952	* @param string $folder Folder name (empty for server metadata)
	953	* @param array $entries Entries
	954	* @param array $options Command options (with MAXSIZE and DEPTH keys)
	955	*
	956	* @return array Metadata entry-value hash array on success, NULL on error
	957	*/
	958	abstract function get_metadata($folder, $entries, $options = array());
	959
	960
	961	/* -----------------------------------------
	962	* Cache related functions
	963	* ----------------------------------------*/
	964
	965	/**
	966	* Clears the cache.
	967	*
	968	* @param string $key Cache key name or pattern
	969	* @param boolean $prefix_mode Enable it to clear all keys starting
	970	* with prefix specified in $key
	971	*/
	972	abstract function clear_cache($key = null, $prefix_mode = false);
	973
0c2596	974
c321a9	975	/**
T	976	* Returns cached value
	977	*
	978	* @param string $key Cache key
	979	*
	980	* @return mixed Cached value
	981	*/
	982	abstract function get_cache($key);
	983
0c2596	984
fec2d8	985	/**
T	986	* Delete outdated cache entries
	987	*/
	988	abstract function expunge_cache();
	989
c321a9	990	} // end class rcube_storage