1
0

Node.php 6.8 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269
  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\LockedException;
  12. /**
  13. * Interface Node
  14. *
  15. * @since 6.0.0 - extends FileInfo was added in 8.0.0
  16. */
  17. interface Node extends FileInfo {
  18. /**
  19. * Move the file or folder to a new location
  20. *
  21. * @param string $targetPath the absolute target path
  22. * @return Node
  23. * @throws NotFoundException
  24. * @throws NotPermittedException if move not allowed or failed
  25. * @throws LockedException
  26. * @throws InvalidPathException
  27. * @since 6.0.0
  28. */
  29. public function move($targetPath);
  30. /**
  31. * Delete the file or folder
  32. *
  33. * @return void
  34. * @throws NotPermittedException
  35. * @throws InvalidPathException
  36. * @throws NotFoundException
  37. * @since 6.0.0
  38. */
  39. public function delete();
  40. /**
  41. * Copy the file or folder to a new location
  42. *
  43. * @param string $targetPath the absolute target path
  44. * @return Node
  45. * @since 6.0.0
  46. */
  47. public function copy($targetPath);
  48. /**
  49. * Change the modified date of the file or folder
  50. * If $mtime is omitted the current time will be used
  51. *
  52. * @param int $mtime (optional) modified date as unix timestamp
  53. * @throws InvalidPathException
  54. * @throws NotFoundException
  55. * @throws NotPermittedException
  56. * @return void
  57. * @since 6.0.0
  58. */
  59. public function touch($mtime = null);
  60. /**
  61. * Get the storage backend the file or folder is stored on
  62. *
  63. * @return IStorage
  64. * @throws NotFoundException
  65. * @since 6.0.0
  66. */
  67. public function getStorage();
  68. /**
  69. * Get the full path of the file or folder
  70. *
  71. * @return string
  72. * @since 6.0.0
  73. */
  74. public function getPath();
  75. /**
  76. * Get the path of the file or folder relative to the mountpoint of it's storage
  77. *
  78. * @return string
  79. * @since 6.0.0
  80. */
  81. public function getInternalPath();
  82. /**
  83. * Get the internal file id for the file or folder
  84. *
  85. * @return int
  86. * @throws InvalidPathException
  87. * @throws NotFoundException
  88. * @since 6.0.0
  89. */
  90. public function getId();
  91. /**
  92. * Get metadata of the file or folder
  93. * The returned array contains the following values:
  94. * - mtime
  95. * - size
  96. *
  97. * @return array
  98. * @since 6.0.0
  99. */
  100. public function stat();
  101. /**
  102. * Get the modified date of the file or folder as unix timestamp
  103. *
  104. * @return int
  105. * @throws InvalidPathException
  106. * @throws NotFoundException
  107. * @since 6.0.0
  108. */
  109. public function getMTime();
  110. /**
  111. * Get the size of the file or folder in bytes
  112. *
  113. * @param bool $includeMounts
  114. * @return int|float
  115. * @throws InvalidPathException
  116. * @throws NotFoundException
  117. * @since 6.0.0
  118. */
  119. public function getSize($includeMounts = true);
  120. /**
  121. * Get the Etag of the file or folder
  122. * The Etag is an string id used to detect changes to a file or folder,
  123. * every time the file or folder is changed the Etag will change to
  124. *
  125. * @return string
  126. * @throws InvalidPathException
  127. * @throws NotFoundException
  128. * @since 6.0.0
  129. */
  130. public function getEtag();
  131. /**
  132. * Get the permissions of the file or folder as a combination of one or more of the following constants:
  133. * - \OCP\Constants::PERMISSION_READ
  134. * - \OCP\Constants::PERMISSION_UPDATE
  135. * - \OCP\Constants::PERMISSION_CREATE
  136. * - \OCP\Constants::PERMISSION_DELETE
  137. * - \OCP\Constants::PERMISSION_SHARE
  138. *
  139. * @return int
  140. * @throws InvalidPathException
  141. * @throws NotFoundException
  142. * @since 6.0.0 - namespace of constants has changed in 8.0.0
  143. */
  144. public function getPermissions();
  145. /**
  146. * Check if the file or folder is readable
  147. *
  148. * @return bool
  149. * @throws InvalidPathException
  150. * @throws NotFoundException
  151. * @since 6.0.0
  152. */
  153. public function isReadable();
  154. /**
  155. * Check if the file or folder is writable
  156. *
  157. * @return bool
  158. * @throws InvalidPathException
  159. * @throws NotFoundException
  160. * @since 6.0.0
  161. */
  162. public function isUpdateable();
  163. /**
  164. * Check if the file or folder is deletable
  165. *
  166. * @return bool
  167. * @throws InvalidPathException
  168. * @throws NotFoundException
  169. * @since 6.0.0
  170. */
  171. public function isDeletable();
  172. /**
  173. * Check if the file or folder is shareable
  174. *
  175. * @return bool
  176. * @throws InvalidPathException
  177. * @throws NotFoundException
  178. * @since 6.0.0
  179. */
  180. public function isShareable();
  181. /**
  182. * Get the parent folder of the file or folder
  183. *
  184. * @return Folder
  185. * @since 6.0.0
  186. */
  187. public function getParent();
  188. /**
  189. * Get the filename of the file or folder
  190. *
  191. * @return string
  192. * @since 6.0.0
  193. */
  194. public function getName();
  195. /**
  196. * Acquire a lock on this file or folder.
  197. *
  198. * A shared (read) lock will prevent any exclusive (write) locks from being created but any number of shared locks
  199. * can be active at the same time.
  200. * An exclusive lock will prevent any other lock from being created (both shared and exclusive).
  201. *
  202. * A locked exception will be thrown if any conflicting lock already exists
  203. *
  204. * Note that this uses mandatory locking, if you acquire an exclusive lock on a file it will block *all*
  205. * other operations for that file, even within the same php process.
  206. *
  207. * Acquiring any lock on a file will also create a shared lock on all parent folders of that file.
  208. *
  209. * Note that in most cases you won't need to manually manage the locks for any files you're working with,
  210. * any filesystem operation will automatically acquire the relevant locks for that operation.
  211. *
  212. * @param int $type \OCP\Lock\ILockingProvider::LOCK_SHARED or \OCP\Lock\ILockingProvider::LOCK_EXCLUSIVE
  213. * @throws LockedException
  214. * @since 9.1.0
  215. */
  216. public function lock($type);
  217. /**
  218. * Check the type of an existing lock.
  219. *
  220. * A shared lock can be changed to an exclusive lock is there is exactly one shared lock on the file,
  221. * an exclusive lock can always be changed to a shared lock since there can only be one exclusive lock int he first place.
  222. *
  223. * A locked exception will be thrown when these preconditions are not met.
  224. * Note that this is also the case if no existing lock exists for the file.
  225. *
  226. * @param int $targetType \OCP\Lock\ILockingProvider::LOCK_SHARED or \OCP\Lock\ILockingProvider::LOCK_EXCLUSIVE
  227. * @throws LockedException
  228. * @since 9.1.0
  229. */
  230. public function changeLock($targetType);
  231. /**
  232. * Release an existing lock.
  233. *
  234. * This will also free up the shared locks on any parent folder that were automatically acquired when locking the file.
  235. *
  236. * Note that this method will not give any sort of error when trying to free a lock that doesn't exist.
  237. *
  238. * @param int $type \OCP\Lock\ILockingProvider::LOCK_SHARED or \OCP\Lock\ILockingProvider::LOCK_EXCLUSIVE
  239. * @throws LockedException
  240. * @since 9.1.0
  241. */
  242. public function unlock($type);
  243. }