Storage.php 10 KB

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