You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

467 lines
11 KiB

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