1<?php 2/** 3 * @copyright Copyright (c) 2016, ownCloud, Inc. 4 * 5 * @author Christoph Wurst <christoph@winzerhof-wurst.at> 6 * @author J0WI <J0WI@users.noreply.github.com> 7 * @author Lukas Reschke <lukas@statuscode.ch> 8 * @author Robin Appelman <robin@icewind.nl> 9 * @author Roeland Jago Douma <roeland@famdouma.nl> 10 * @author Tigran Mkrtchyan <tigran.mkrtchyan@desy.de> 11 * 12 * @license AGPL-3.0 13 * 14 * This code is free software: you can redistribute it and/or modify 15 * it under the terms of the GNU Affero General Public License, version 3, 16 * as published by the Free Software Foundation. 17 * 18 * This program is distributed in the hope that it will be useful, 19 * but WITHOUT ANY WARRANTY; without even the implied warranty of 20 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 21 * GNU Affero General Public License for more details. 22 * 23 * You should have received a copy of the GNU Affero General Public License, version 3, 24 * along with this program. If not, see <http://www.gnu.org/licenses/> 25 * 26 */ 27// use OCP namespace for all classes that are considered public. 28// This means that they should be used by apps instead of the internal Nextcloud classes 29 30namespace OCP\Files\Storage; 31 32use OCP\Files\Cache\ICache; 33use OCP\Files\Cache\IPropagator; 34use OCP\Files\Cache\IScanner; 35use OCP\Files\Cache\IUpdater; 36use OCP\Files\Cache\IWatcher; 37use OCP\Files\InvalidPathException; 38 39/** 40 * Provide a common interface to all different storage options 41 * 42 * All paths passed to the storage are relative to the storage and should NOT have a leading slash. 43 * 44 * @since 9.0.0 45 */ 46interface IStorage { 47 /** 48 * $parameters is a free form array with the configuration options needed to construct the storage 49 * 50 * @param array $parameters 51 * @since 9.0.0 52 */ 53 public function __construct($parameters); 54 55 /** 56 * Get the identifier for the storage, 57 * the returned id should be the same for every storage object that is created with the same parameters 58 * and two storage objects with the same id should refer to two storages that display the same files. 59 * 60 * @return string 61 * @since 9.0.0 62 */ 63 public function getId(); 64 65 /** 66 * see https://www.php.net/manual/en/function.mkdir.php 67 * implementations need to implement a recursive mkdir 68 * 69 * @param string $path 70 * @return bool 71 * @since 9.0.0 72 */ 73 public function mkdir($path); 74 75 /** 76 * see https://www.php.net/manual/en/function.rmdir.php 77 * 78 * @param string $path 79 * @return bool 80 * @since 9.0.0 81 */ 82 public function rmdir($path); 83 84 /** 85 * see https://www.php.net/manual/en/function.opendir.php 86 * 87 * @param string $path 88 * @return resource|bool 89 * @since 9.0.0 90 */ 91 public function opendir($path); 92 93 /** 94 * see https://www.php.net/manual/en/function.is-dir.php 95 * 96 * @param string $path 97 * @return bool 98 * @since 9.0.0 99 */ 100 public function is_dir($path); 101 102 /** 103 * see https://www.php.net/manual/en/function.is-file.php 104 * 105 * @param string $path 106 * @return bool 107 * @since 9.0.0 108 */ 109 public function is_file($path); 110 111 /** 112 * see https://www.php.net/manual/en/function.stat.php 113 * only the following keys are required in the result: size and mtime 114 * 115 * @param string $path 116 * @return array|bool 117 * @since 9.0.0 118 */ 119 public function stat($path); 120 121 /** 122 * see https://www.php.net/manual/en/function.filetype.php 123 * 124 * @param string $path 125 * @return string|bool 126 * @since 9.0.0 127 */ 128 public function filetype($path); 129 130 /** 131 * see https://www.php.net/manual/en/function.filesize.php 132 * The result for filesize when called on a folder is required to be 0 133 * 134 * @param string $path 135 * @return int|bool 136 * @since 9.0.0 137 */ 138 public function filesize($path); 139 140 /** 141 * check if a file can be created in $path 142 * 143 * @param string $path 144 * @return bool 145 * @since 9.0.0 146 */ 147 public function isCreatable($path); 148 149 /** 150 * check if a file can be read 151 * 152 * @param string $path 153 * @return bool 154 * @since 9.0.0 155 */ 156 public function isReadable($path); 157 158 /** 159 * check if a file can be written to 160 * 161 * @param string $path 162 * @return bool 163 * @since 9.0.0 164 */ 165 public function isUpdatable($path); 166 167 /** 168 * check if a file can be deleted 169 * 170 * @param string $path 171 * @return bool 172 * @since 9.0.0 173 */ 174 public function isDeletable($path); 175 176 /** 177 * check if a file can be shared 178 * 179 * @param string $path 180 * @return bool 181 * @since 9.0.0 182 */ 183 public function isSharable($path); 184 185 /** 186 * get the full permissions of a path. 187 * Should return a combination of the PERMISSION_ constants defined in lib/public/constants.php 188 * 189 * @param string $path 190 * @return int 191 * @since 9.0.0 192 */ 193 public function getPermissions($path); 194 195 /** 196 * see https://www.php.net/manual/en/function.file_exists.php 197 * 198 * @param string $path 199 * @return bool 200 * @since 9.0.0 201 */ 202 public function file_exists($path); 203 204 /** 205 * see https://www.php.net/manual/en/function.filemtime.php 206 * 207 * @param string $path 208 * @return int|bool 209 * @since 9.0.0 210 */ 211 public function filemtime($path); 212 213 /** 214 * see https://www.php.net/manual/en/function.file_get_contents.php 215 * 216 * @param string $path 217 * @return string|bool 218 * @since 9.0.0 219 */ 220 public function file_get_contents($path); 221 222 /** 223 * see https://www.php.net/manual/en/function.file_put_contents.php 224 * 225 * @param string $path 226 * @param mixed $data 227 * @return int|false 228 * @since 9.0.0 229 */ 230 public function file_put_contents($path, $data); 231 232 /** 233 * see https://www.php.net/manual/en/function.unlink.php 234 * 235 * @param string $path 236 * @return bool 237 * @since 9.0.0 238 */ 239 public function unlink($path); 240 241 /** 242 * see https://www.php.net/manual/en/function.rename.php 243 * 244 * @param string $path1 245 * @param string $path2 246 * @return bool 247 * @since 9.0.0 248 */ 249 public function rename($path1, $path2); 250 251 /** 252 * see https://www.php.net/manual/en/function.copy.php 253 * 254 * @param string $path1 255 * @param string $path2 256 * @return bool 257 * @since 9.0.0 258 */ 259 public function copy($path1, $path2); 260 261 /** 262 * see https://www.php.net/manual/en/function.fopen.php 263 * 264 * @param string $path 265 * @param string $mode 266 * @return resource|bool 267 * @since 9.0.0 268 */ 269 public function fopen($path, $mode); 270 271 /** 272 * get the mimetype for a file or folder 273 * The mimetype for a folder is required to be "httpd/unix-directory" 274 * 275 * @param string $path 276 * @return string|bool 277 * @since 9.0.0 278 */ 279 public function getMimeType($path); 280 281 /** 282 * see https://www.php.net/manual/en/function.hash-file.php 283 * 284 * @param string $type 285 * @param string $path 286 * @param bool $raw 287 * @return string|bool 288 * @since 9.0.0 289 */ 290 public function hash($type, $path, $raw = false); 291 292 /** 293 * see https://www.php.net/manual/en/function.free_space.php 294 * 295 * @param string $path 296 * @return int|bool 297 * @since 9.0.0 298 */ 299 public function free_space($path); 300 301 /** 302 * see https://www.php.net/manual/en/function.touch.php 303 * If the backend does not support the operation, false should be returned 304 * 305 * @param string $path 306 * @param int $mtime 307 * @return bool 308 * @since 9.0.0 309 */ 310 public function touch($path, $mtime = null); 311 312 /** 313 * get the path to a local version of the file. 314 * The local version of the file can be temporary and doesn't have to be persistent across requests 315 * 316 * @param string $path 317 * @return string|bool 318 * @since 9.0.0 319 */ 320 public function getLocalFile($path); 321 322 /** 323 * check if a file or folder has been updated since $time 324 * 325 * @param string $path 326 * @param int $time 327 * @return bool 328 * @since 9.0.0 329 * 330 * hasUpdated for folders should return at least true if a file inside the folder is add, removed or renamed. 331 * returning true for other changes in the folder is optional 332 */ 333 public function hasUpdated($path, $time); 334 335 /** 336 * get the ETag for a file or folder 337 * 338 * @param string $path 339 * @return string|bool 340 * @since 9.0.0 341 */ 342 public function getETag($path); 343 344 /** 345 * Returns whether the storage is local, which means that files 346 * are stored on the local filesystem instead of remotely. 347 * Calling getLocalFile() for local storages should always 348 * return the local files, whereas for non-local storages 349 * it might return a temporary file. 350 * 351 * @return bool true if the files are stored locally, false otherwise 352 * @since 9.0.0 353 */ 354 public function isLocal(); 355 356 /** 357 * Check if the storage is an instance of $class or is a wrapper for a storage that is an instance of $class 358 * 359 * @param string $class 360 * @return bool 361 * @since 9.0.0 362 */ 363 public function instanceOfStorage($class); 364 365 /** 366 * A custom storage implementation can return an url for direct download of a give file. 367 * 368 * For now the returned array can hold the parameter url - in future more attributes might follow. 369 * 370 * @param string $path 371 * @return array|bool 372 * @since 9.0.0 373 */ 374 public function getDirectDownload($path); 375 376 /** 377 * @param string $path the path of the target folder 378 * @param string $fileName the name of the file itself 379 * @return void 380 * @throws InvalidPathException 381 * @since 9.0.0 382 */ 383 public function verifyPath($path, $fileName); 384 385 /** 386 * @param IStorage $sourceStorage 387 * @param string $sourceInternalPath 388 * @param string $targetInternalPath 389 * @return bool 390 * @since 9.0.0 391 */ 392 public function copyFromStorage(IStorage $sourceStorage, $sourceInternalPath, $targetInternalPath); 393 394 /** 395 * @param IStorage $sourceStorage 396 * @param string $sourceInternalPath 397 * @param string $targetInternalPath 398 * @return bool 399 * @since 9.0.0 400 */ 401 public function moveFromStorage(IStorage $sourceStorage, $sourceInternalPath, $targetInternalPath); 402 403 /** 404 * Test a storage for availability 405 * 406 * @since 9.0.0 407 * @return bool 408 */ 409 public function test(); 410 411 /** 412 * @since 9.0.0 413 * @return array [ available, last_checked ] 414 */ 415 public function getAvailability(); 416 417 /** 418 * @since 9.0.0 419 * @param bool $isAvailable 420 */ 421 public function setAvailability($isAvailable); 422 423 /** 424 * @param string $path path for which to retrieve the owner 425 * @since 9.0.0 426 */ 427 public function getOwner($path); 428 429 /** 430 * @param string $path 431 * @param IStorage|null $storage 432 * @return ICache 433 * @since 9.0.0 434 */ 435 public function getCache($path = '', $storage = null); 436 437 /** 438 * @return IPropagator 439 * @since 9.0.0 440 */ 441 public function getPropagator(); 442 443 /** 444 * @return IScanner 445 * @since 9.0.0 446 */ 447 public function getScanner(); 448 449 /** 450 * @return IUpdater 451 * @since 9.0.0 452 */ 453 public function getUpdater(); 454 455 /** 456 * @return IWatcher 457 * @since 9.0.0 458 */ 459 public function getWatcher(); 460} 461