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