githubFork/roundcubemail.git

Get rid of Mail_mimeDecode package dependency (#1490416)

Aleksander Machniak

2015-06-27 a7e552b5a436375e233e7d4df4ed6cfc9e58d435

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