Storage.php 11 KB

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