1: <?php
2: /**
3: * Defines the Kolab data handler.
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: * Defines the Kolab data handler.
16: *
17: * Copyright 2011-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_Data
29: extends Horde_Kolab_Storage_Queriable
30: {
31: /** Identifies the preferences query */
32: /** @since Horde_Kolab_Storage 1.1.0 */
33: const QUERY_PREFS = 'Preferences';
34: const QUERY_HISTORY = 'History';
35:
36: /**
37: * Return the folder path for this data handler.
38: *
39: * @since Horde_Kolab_Storage 1.1.0
40: *
41: * @return string The folder path.
42: */
43: public function getPath();
44:
45: /**
46: * Return the ID of the current user.
47: *
48: * @since Horde_Kolab_Storage 1.1.0
49: *
50: * @return string The current user.
51: */
52: public function getAuth();
53:
54: /**
55: * Return the ID of this data handler.
56: *
57: * @return string The ID.
58: */
59: public function getId();
60:
61: /**
62: * Return the ID parameters for this data handler.
63: *
64: * @return array The ID parameters.
65: */
66: public function getIdParameters();
67:
68: /**
69: * Return the data type represented by this object.
70: *
71: * @return string The type of data this instance handles.
72: */
73: public function getType();
74:
75: /**
76: * Return the data version.
77: *
78: * @return string The data version.
79: */
80: public function getVersion();
81:
82: /**
83: * Report the status of this folder.
84: *
85: * @return Horde_Kolab_Storage_Folder_Stamp The stamp that can be used for
86: * detecting folder changes.
87: */
88: public function getStamp();
89:
90: /**
91: * Create a new object.
92: *
93: * @param array &$object The array that holds the object data.
94: * @param boolean $raw True if the data to be stored has been provided in
95: * raw format.
96: *
97: * @return string The ID of the new object or true in case the backend does
98: * not support this return value.
99: *
100: * @throws Horde_Kolab_Storage_Exception In case an error occured while
101: * saving the data.
102: */
103: public function create(&$object, $raw = false);
104:
105: /**
106: * Modify an existing object.
107: *
108: * @param array $object The array that holds the updated object data.
109: * @param boolean $raw True if the data to be stored has been provided in
110: * raw format.
111: *
112: * @return NULL
113: *
114: * @throws Horde_Kolab_Storage_Exception In case an error occured while
115: * saving the data.
116: */
117: public function modify($object, $raw = false);
118:
119: /**
120: * Retrieves the objects for the given UIDs.
121: *
122: * @param array $uids The message UIDs.
123: *
124: * @return array An array of objects.
125: */
126: public function fetch($uids);
127:
128: /**
129: * Retrieves the complete message for the given UID.
130: *
131: * @param string $uid The message UID.
132: *
133: * @return array The message encapsuled as an array that contains a
134: * Horde_Mime_Headers and a Horde_Mime_Part object.
135: */
136: public function fetchComplete($uid);
137:
138: /**
139: * Return the backend ID for the given object ID.
140: *
141: * @param string $object_uid The object ID.
142: *
143: * @return string The backend ID for the object.
144: */
145: public function getBackendId($object_id);
146:
147: /**
148: * Generate a unique object ID.
149: *
150: * @return string The unique ID.
151: */
152: public function generateUid();
153:
154: /**
155: * Check if the given object ID exists.
156: *
157: * @param string $object_id The object ID.
158: *
159: * @return boolean True if the ID was found, false otherwise.
160: */
161: public function objectIdExists($object_id);
162:
163: /**
164: * Return the specified object.
165: *
166: * @param string $object_id The object id.
167: *
168: * @return array The object data as an array.
169: */
170: public function getObject($object_id);
171:
172: /**
173: * Return the specified attachment.
174: *
175: * @param string $attachment_id The attachment id.
176: *
177: * @return resource An open stream to the attachment data.
178: */
179: public function getAttachment($attachment_id);
180:
181: /**
182: * Retrieve all object ids in the current folder.
183: *
184: * @return array The object ids.
185: */
186: public function getObjectIds();
187:
188: /**
189: * Retrieve all objects in the current folder.
190: *
191: * @return array An array of all objects.
192: */
193: public function getObjects();
194:
195: /**
196: * Retrieve all objects in the current folder by backend id.
197: *
198: * @since Horde_Kolab_Storage 1.1.0
199: *
200: * @return array An array of all objects.
201: */
202: public function getObjectsByBackendId();
203:
204: /**
205: * Retrieve an object in the current folder by backend id.
206: *
207: * @since Horde_Kolab_Storage 1.1.0
208: *
209: * @param string $uid Backend id of the object to be returned.
210: *
211: * @return array An array of all objects.
212: */
213: public function getObjectByBackendId($uid);
214:
215: /**
216: * Return the mapping of object IDs to backend IDs.
217: *
218: * @since Horde_Kolab_Storage 1.1.0
219: *
220: * @return array The object to backend mapping.
221: */
222: public function getObjectToBackend();
223:
224: /**
225: * Retrieve the list of object duplicates.
226: *
227: * @since Horde_Kolab_Storage 1.1.0
228: *
229: * @return array The list of duplicates.
230: */
231: public function getDuplicates();
232:
233: /**
234: * Retrieve the list of object errors.
235: *
236: * @since Horde_Kolab_Storage 1.1.0
237: *
238: * @return array The list of errors.
239: */
240: public function getErrors();
241:
242: /**
243: * Move the specified message from the current folder into a new
244: * folder.
245: *
246: * @param string $object_id ID of the message to be moved.
247: * @param string $new_folder Target folder.
248: *
249: * @return NULL
250: */
251: public function move($object_id, $new_folder);
252:
253: /**
254: * Delete the specified objects from this data set.
255: *
256: * @param array|string $object_ids Id(s) of the object to be deleted.
257: *
258: * @return NULL
259: */
260: public function delete($object_ids);
261:
262: /**
263: * Delete all objects from this data set.
264: *
265: * @return NULL
266: */
267: public function deleteAll();
268:
269: /**
270: * Delete the specified messages from this folder.
271: *
272: * @since Horde_Kolab_Storage 1.1.0
273: *
274: * @param array|string $uids Backend id(s) of the message to be deleted.
275: *
276: * @return NULL
277: */
278: public function deleteBackendIds($uids);
279: }