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