IStorage.php 10 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463
  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. namespace OCP\Files\Storage;
  30. use OCP\Files\Cache\ICache;
  31. use OCP\Files\Cache\IPropagator;
  32. use OCP\Files\Cache\IScanner;
  33. use OCP\Files\Cache\IUpdater;
  34. use OCP\Files\Cache\IWatcher;
  35. use OCP\Files\InvalidPathException;
  36. /**
  37. * Provide a common interface to all different storage options
  38. *
  39. * All paths passed to the storage are relative to the storage and should NOT have a leading slash.
  40. *
  41. * @since 9.0.0
  42. */
  43. interface IStorage {
  44. /**
  45. * $parameters is a free form array with the configuration options needed to construct the storage
  46. *
  47. * @param array $parameters
  48. * @since 9.0.0
  49. */
  50. public function __construct($parameters);
  51. /**
  52. * Get the identifier for the storage,
  53. * the returned id should be the same for every storage object that is created with the same parameters
  54. * and two storage objects with the same id should refer to two storages that display the same files.
  55. *
  56. * @return string
  57. * @since 9.0.0
  58. */
  59. public function getId();
  60. /**
  61. * see https://www.php.net/manual/en/function.mkdir.php
  62. * implementations need to implement a recursive mkdir
  63. *
  64. * @param string $path
  65. * @return bool
  66. * @since 9.0.0
  67. */
  68. public function mkdir($path);
  69. /**
  70. * see https://www.php.net/manual/en/function.rmdir.php
  71. *
  72. * @param string $path
  73. * @return bool
  74. * @since 9.0.0
  75. */
  76. public function rmdir($path);
  77. /**
  78. * see https://www.php.net/manual/en/function.opendir.php
  79. *
  80. * @param string $path
  81. * @return resource|false
  82. * @since 9.0.0
  83. */
  84. public function opendir($path);
  85. /**
  86. * see https://www.php.net/manual/en/function.is-dir.php
  87. *
  88. * @param string $path
  89. * @return bool
  90. * @since 9.0.0
  91. */
  92. public function is_dir($path);
  93. /**
  94. * see https://www.php.net/manual/en/function.is-file.php
  95. *
  96. * @param string $path
  97. * @return bool
  98. * @since 9.0.0
  99. */
  100. public function is_file($path);
  101. /**
  102. * see https://www.php.net/manual/en/function.stat.php
  103. * only the following keys are required in the result: size and mtime
  104. *
  105. * @param string $path
  106. * @return array|bool
  107. * @since 9.0.0
  108. */
  109. public function stat($path);
  110. /**
  111. * see https://www.php.net/manual/en/function.filetype.php
  112. *
  113. * @param string $path
  114. * @return string|bool
  115. * @since 9.0.0
  116. */
  117. public function filetype($path);
  118. /**
  119. * see https://www.php.net/manual/en/function.filesize.php
  120. * The result for filesize when called on a folder is required to be 0
  121. *
  122. * @param string $path
  123. * @return false|int|float
  124. * @since 9.0.0
  125. */
  126. public function filesize($path);
  127. /**
  128. * check if a file can be created in $path
  129. *
  130. * @param string $path
  131. * @return bool
  132. * @since 9.0.0
  133. */
  134. public function isCreatable($path);
  135. /**
  136. * check if a file can be read
  137. *
  138. * @param string $path
  139. * @return bool
  140. * @since 9.0.0
  141. */
  142. public function isReadable($path);
  143. /**
  144. * check if a file can be written to
  145. *
  146. * @param string $path
  147. * @return bool
  148. * @since 9.0.0
  149. */
  150. public function isUpdatable($path);
  151. /**
  152. * check if a file can be deleted
  153. *
  154. * @param string $path
  155. * @return bool
  156. * @since 9.0.0
  157. */
  158. public function isDeletable($path);
  159. /**
  160. * check if a file can be shared
  161. *
  162. * @param string $path
  163. * @return bool
  164. * @since 9.0.0
  165. */
  166. public function isSharable($path);
  167. /**
  168. * get the full permissions of a path.
  169. * Should return a combination of the PERMISSION_ constants defined in lib/public/constants.php
  170. *
  171. * @param string $path
  172. * @return int
  173. * @since 9.0.0
  174. */
  175. public function getPermissions($path);
  176. /**
  177. * see https://www.php.net/manual/en/function.file_exists.php
  178. *
  179. * @param string $path
  180. * @return bool
  181. * @since 9.0.0
  182. */
  183. public function file_exists($path);
  184. /**
  185. * see https://www.php.net/manual/en/function.filemtime.php
  186. *
  187. * @param string $path
  188. * @return int|bool
  189. * @since 9.0.0
  190. */
  191. public function filemtime($path);
  192. /**
  193. * see https://www.php.net/manual/en/function.file_get_contents.php
  194. *
  195. * @param string $path
  196. * @return string|false
  197. * @since 9.0.0
  198. */
  199. public function file_get_contents($path);
  200. /**
  201. * see https://www.php.net/manual/en/function.file_put_contents.php
  202. *
  203. * @param string $path
  204. * @param mixed $data
  205. * @return int|float|false
  206. * @since 9.0.0
  207. */
  208. public function file_put_contents($path, $data);
  209. /**
  210. * see https://www.php.net/manual/en/function.unlink.php
  211. *
  212. * @param string $path
  213. * @return bool
  214. * @since 9.0.0
  215. */
  216. public function unlink($path);
  217. /**
  218. * see https://www.php.net/manual/en/function.rename.php
  219. *
  220. * @param string $source
  221. * @param string $target
  222. * @return bool
  223. * @since 9.0.0
  224. */
  225. public function rename($source, $target);
  226. /**
  227. * see https://www.php.net/manual/en/function.copy.php
  228. *
  229. * @param string $source
  230. * @param string $target
  231. * @return bool
  232. * @since 9.0.0
  233. */
  234. public function copy($source, $target);
  235. /**
  236. * see https://www.php.net/manual/en/function.fopen.php
  237. *
  238. * @param string $path
  239. * @param string $mode
  240. * @return resource|bool
  241. * @since 9.0.0
  242. */
  243. public function fopen($path, $mode);
  244. /**
  245. * get the mimetype for a file or folder
  246. * The mimetype for a folder is required to be "httpd/unix-directory"
  247. *
  248. * @param string $path
  249. * @return string|bool
  250. * @since 9.0.0
  251. */
  252. public function getMimeType($path);
  253. /**
  254. * see https://www.php.net/manual/en/function.hash-file.php
  255. *
  256. * @param string $type
  257. * @param string $path
  258. * @param bool $raw
  259. * @return string|bool
  260. * @since 9.0.0
  261. */
  262. public function hash($type, $path, $raw = false);
  263. /**
  264. * see https://www.php.net/manual/en/function.free_space.php
  265. *
  266. * @param string $path
  267. * @return int|float|bool
  268. * @since 9.0.0
  269. */
  270. public function free_space($path);
  271. /**
  272. * see https://www.php.net/manual/en/function.touch.php
  273. * If the backend does not support the operation, false should be returned
  274. *
  275. * @param string $path
  276. * @param int $mtime
  277. * @return bool
  278. * @since 9.0.0
  279. */
  280. public function touch($path, $mtime = null);
  281. /**
  282. * get the path to a local version of the file.
  283. * The local version of the file can be temporary and doesn't have to be persistent across requests
  284. *
  285. * @param string $path
  286. * @return string|false
  287. * @since 9.0.0
  288. */
  289. public function getLocalFile($path);
  290. /**
  291. * check if a file or folder has been updated since $time
  292. *
  293. * @param string $path
  294. * @param int $time
  295. * @return bool
  296. * @since 9.0.0
  297. *
  298. * hasUpdated for folders should return at least true if a file inside the folder is add, removed or renamed.
  299. * returning true for other changes in the folder is optional
  300. */
  301. public function hasUpdated($path, $time);
  302. /**
  303. * get the ETag for a file or folder
  304. *
  305. * @param string $path
  306. * @return string|false
  307. * @since 9.0.0
  308. */
  309. public function getETag($path);
  310. /**
  311. * Returns whether the storage is local, which means that files
  312. * are stored on the local filesystem instead of remotely.
  313. * Calling getLocalFile() for local storages should always
  314. * return the local files, whereas for non-local storages
  315. * it might return a temporary file.
  316. *
  317. * @return bool true if the files are stored locally, false otherwise
  318. * @since 9.0.0
  319. */
  320. public function isLocal();
  321. /**
  322. * Check if the storage is an instance of $class or is a wrapper for a storage that is an instance of $class
  323. *
  324. * @template T of IStorage
  325. * @param string $class
  326. * @psalm-param class-string<T> $class
  327. * @return bool
  328. * @since 9.0.0
  329. * @psalm-assert-if-true T $this
  330. */
  331. public function instanceOfStorage($class);
  332. /**
  333. * A custom storage implementation can return an url for direct download of a give file.
  334. *
  335. * For now the returned array can hold the parameter url - in future more attributes might follow.
  336. *
  337. * @param string $path
  338. * @return array|bool
  339. * @since 9.0.0
  340. */
  341. public function getDirectDownload($path);
  342. /**
  343. * @param string $path the path of the target folder
  344. * @param string $fileName the name of the file itself
  345. * @return void
  346. * @throws InvalidPathException
  347. * @since 9.0.0
  348. */
  349. public function verifyPath($path, $fileName);
  350. /**
  351. * @param IStorage $sourceStorage
  352. * @param string $sourceInternalPath
  353. * @param string $targetInternalPath
  354. * @return bool
  355. * @since 9.0.0
  356. */
  357. public function copyFromStorage(IStorage $sourceStorage, $sourceInternalPath, $targetInternalPath);
  358. /**
  359. * @param IStorage $sourceStorage
  360. * @param string $sourceInternalPath
  361. * @param string $targetInternalPath
  362. * @return bool
  363. * @since 9.0.0
  364. */
  365. public function moveFromStorage(IStorage $sourceStorage, $sourceInternalPath, $targetInternalPath);
  366. /**
  367. * Test a storage for availability
  368. *
  369. * @since 9.0.0
  370. * @return bool
  371. */
  372. public function test();
  373. /**
  374. * @since 9.0.0
  375. * @return array [ available, last_checked ]
  376. */
  377. public function getAvailability();
  378. /**
  379. * @since 9.0.0
  380. * @param bool $isAvailable
  381. */
  382. public function setAvailability($isAvailable);
  383. /**
  384. * @param string $path path for which to retrieve the owner
  385. * @since 9.0.0
  386. */
  387. public function getOwner($path);
  388. /**
  389. * @param string $path
  390. * @param IStorage|null $storage
  391. * @return ICache
  392. * @since 9.0.0
  393. */
  394. public function getCache($path = '', $storage = null);
  395. /**
  396. * @return IPropagator
  397. * @since 9.0.0
  398. */
  399. public function getPropagator();
  400. /**
  401. * @return IScanner
  402. * @since 9.0.0
  403. */
  404. public function getScanner();
  405. /**
  406. * @return IUpdater
  407. * @since 9.0.0
  408. */
  409. public function getUpdater();
  410. /**
  411. * @return IWatcher
  412. * @since 9.0.0
  413. */
  414. public function getWatcher();
  415. }