1<?php
2/**
3 * The driver definition for accessing Kolab storage.
4 *
5 * PHP version 5
6 *
7 * @category Kolab
8 * @package  Kolab_Storage
9 * @author   Gunnar Wrobel <wrobel@pardus.de>
10 * @license  http://www.horde.org/licenses/lgpl21 LGPL 2.1
11 */
12
13/**
14 * The driver definition for accessing Kolab storage.
15 *
16 * Copyright 2004-2017 Horde LLC (http://www.horde.org/)
17 *
18 * See the enclosed file COPYING for license information (LGPL). If you
19 * did not receive this file, see http://www.horde.org/licenses/lgpl21.
20 *
21 * @category Kolab
22 * @package  Kolab_Storage
23 * @author   Gunnar Wrobel <wrobel@pardus.de>
24 * @license  http://www.horde.org/licenses/lgpl21 LGPL 2.1
25 */
26interface Horde_Kolab_Storage_Driver
27{
28    /** Generic functionality */
29
30    /**
31     * Create the backend driver.
32     *
33     * @return mixed The backend driver.
34     */
35    public function createBackend();
36
37    /**
38     * Returns the actual backend driver.
39     *
40     * If there is no driver set the driver should be constructed within this
41     * method.
42     *
43     * @return mixed The backend driver.
44     */
45    public function getBackend();
46
47    /**
48     * Set the backend driver.
49     *
50     * @param mixed $backend The driver that should be used.
51     *
52     * @return NULL
53     */
54    public function setBackend($backend);
55
56    /**
57     * Return the id of the user currently authenticated.
58     *
59     * @return string The id of the user that opened the connection.
60     */
61    public function getAuth();
62
63    /**
64     * Return the unique connection id.
65     *
66     * @return string The connection id.
67     */
68    public function getId();
69
70    /**
71     * Return the connection parameters.
72     *
73     * @return array The connection parameters.
74     */
75    public function getParameters();
76
77    /**
78     * Checks if the backend supports CATENATE.
79     *
80     * @return boolean True if the backend supports CATENATE.
81     */
82    public function hasCatenateSupport();
83
84
85    /** List functionality */
86
87    /**
88     * Retrieves a list of folders from the server.
89     *
90     * @return array The list of folders.
91     */
92    public function listFolders();
93
94    /**
95     * Create the specified folder.
96     *
97     * @param string $folder The folder to create.
98     *
99     * @return NULL
100     */
101    public function create($folder);
102
103    /**
104     * Delete the specified folder.
105     *
106     * @param string $folder  The folder to delete.
107     *
108     * @return NULL
109     */
110    public function delete($folder);
111
112    /**
113     * Rename the specified folder.
114     *
115     * @param string $old  The folder to rename.
116     * @param string $new  The new name of the folder.
117     *
118     * @return NULL
119     */
120    public function rename($old, $new);
121
122    /**
123     * Does the backend support ACL?
124     *
125     * @return boolean True if the backend supports ACLs.
126     */
127    public function hasAclSupport();
128
129    /**
130     * Retrieve the access rights for a folder.
131     *
132     * @param string $folder The folder to retrieve the ACL for.
133     *
134     * @return array An array of rights.
135     */
136    public function getAcl($folder);
137
138    /**
139     * Retrieve the access rights the current user has on a folder.
140     *
141     * @param string $folder The folder to retrieve the user ACL for.
142     *
143     * @return string The user rights.
144     */
145    public function getMyAcl($folder);
146
147    /**
148     * Set the access rights for a folder.
149     *
150     * @param string $folder  The folder to act upon.
151     * @param string $user    The user to set the ACL for.
152     * @param string $acl     The ACL.
153     *
154     * @return NULL
155     */
156    public function setAcl($folder, $user, $acl);
157
158    /**
159     * Delete the access rights for user on a folder.
160     *
161     * @param string $folder  The folder to act upon.
162     * @param string $user    The user to delete the ACL for
163     *
164     * @return NULL
165     */
166    public function deleteAcl($folder, $user);
167
168    /**
169     * Retrieves the specified annotation for the complete list of folders.
170     *
171     * @param string $annotation The name of the annotation to retrieve.
172     *
173     * @return array An associative array combining the folder names as key with
174     * the corresponding annotation value.
175     */
176    public function listAnnotation($annotation);
177
178    /**
179     * Fetches the annotation from a folder.
180     *
181     * @param string $folder     The name of the folder.
182     * @param string $annotation The annotation to get.
183     *
184     * @return string The annotation value.
185     */
186    public function getAnnotation($folder, $annotation);
187
188    /**
189     * Sets the annotation on a folder.
190     *
191     * @param string $folder     The name of the folder.
192     * @param string $annotation The annotation to set.
193     * @param array  $value      The values to set
194     *
195     * @return NULL
196     */
197    public function setAnnotation($folder, $annotation, $value);
198
199    /**
200     * Retrieve the namespace information for this connection.
201     *
202     * @return Horde_Kolab_Storage_Driver_Namespace The initialized namespace handler.
203     */
204    public function getNamespace();
205
206
207
208    /** Data functionality */
209
210    /**
211     * Returns a stamp for the current folder status. This stamp can be used to
212     * identify changes in the folder data.
213     *
214     * @param string $folder Return the stamp for this folder.
215     *
216     * @return Horde_Kolab_Storage_Folder_Stamp A stamp indicating the current
217     *                                          folder status.
218     */
219    public function getStamp($folder);
220
221    /**
222     * Returns the status of the current folder.
223     *
224     * @param string $folder Check the status of this folder.
225     *
226     * @return array An array that contains 'uidvalidity' and 'uidnext'.
227     */
228    public function status($folder);
229
230    /**
231     * Returns the message ids of the messages in this folder.
232     *
233     * @param string $folder Check the status of this folder.
234     *
235     * @return array The message ids.
236     */
237    public function getUids($folder);
238
239    /**
240     * Retrieves the messages for the given message ids.
241     *
242     * @param string $folder The folder to fetch the messages from.
243     * @param array  $uids   The message UIDs.
244     *
245     * @return array An array of message structures parsed into Horde_Mime_Part
246     *               instances.
247     */
248    public function fetchStructure($folder, $uids);
249
250    /**
251     * Retrieves a bodypart for the given message ID and mime part ID.
252     *
253     * @param string $folder The folder to fetch the messages from.
254     * @param array  $uid    The message UID.
255     * @param array  $id     The mime part ID.
256     *
257     * @return resource|string The body part, as a stream resource or string.
258     */
259    public function fetchBodypart($folder, $uid, $id);
260
261    /**
262     * Retrieves a complete message.
263     *
264     * @param string $folder The folder to fetch the messages from.
265     * @param array  $uid    The message UID.
266     *
267     * @return array The message encapsuled as an array that contains a
268     *               Horde_Mime_Headers and a Horde_Mime_Part object.
269     */
270    public function fetchComplete($folder, $uid);
271
272    /**
273     * Retrieves the message headers.
274     *
275     * @param string $folder The folder to fetch the message from.
276     * @param array  $uid    The message UID.
277     *
278     * @return Horde_Mime_Headers The message headers.
279     */
280    public function fetchHeaders($folder, $uid);
281
282    /**
283     * Appends a message to the given folder.
284     *
285     * @param string   $folder  The folder to append the message(s) to.
286     * @param resource $msg     The message to append.
287     *
288     * @return mixed True or the UID of the new message in case the backend
289     *               supports UIDPLUS.
290     */
291    public function appendMessage($folder, $msg);
292
293    /**
294     * Deletes messages from the specified folder.
295     *
296     * @param string  $folder  The folder to delete messages from.
297     * @param integer $uids    IMAP message ids.
298     *
299     * @return NULL
300     */
301    public function deleteMessages($folder, $uids);
302
303    /**
304     * Moves a message to a new folder.
305     *
306     * @param integer $uid         IMAP message id.
307     * @param string  $old_folder  Source folder.
308     * @param string  $new_folder  Target folder.
309     *
310     * @return NULL
311     */
312    public function moveMessage($uid, $old_folder, $new_folder);
313
314    /**
315     * Expunges messages in the current folder.
316     *
317     * @param string $folder The folder to expunge.
318     *
319     * @return NULL
320     */
321    public function expunge($folder);
322}
323