Storage.php 11 KB

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