githubFork/roundcubemail.git

Allways call rcube_imap::set_folder() before rcube_imap::get_message_part()

Aleksander Machniak

2014-10-28 d93019125cca783e8acfaa68467024375321e55f

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