1
0

Folder.php 4.8 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201
  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\Search\ISearchQuery;
  11. /**
  12. * @since 6.0.0
  13. */
  14. interface Folder extends Node {
  15. /**
  16. * Get the full path of an item in the folder within owncloud's filesystem
  17. *
  18. * @param string $path relative path of an item in the folder
  19. * @return string
  20. * @throws \OCP\Files\NotPermittedException
  21. * @since 6.0.0
  22. */
  23. public function getFullPath($path);
  24. /**
  25. * Get the path of an item in the folder relative to the folder
  26. *
  27. * @param string $path absolute path of an item in the folder
  28. * @throws \OCP\Files\NotFoundException
  29. * @return string|null
  30. * @since 6.0.0
  31. */
  32. public function getRelativePath($path);
  33. /**
  34. * check if a node is a (grand-)child of the folder
  35. *
  36. * @param \OCP\Files\Node $node
  37. * @return bool
  38. * @since 6.0.0
  39. */
  40. public function isSubNode($node);
  41. /**
  42. * get the content of this directory
  43. *
  44. * @throws \OCP\Files\NotFoundException
  45. * @return \OCP\Files\Node[]
  46. * @since 6.0.0
  47. */
  48. public function getDirectoryListing();
  49. /**
  50. * Get the node at $path
  51. *
  52. * @param string $path relative path of the file or folder
  53. * @return \OCP\Files\Node
  54. * @throws \OCP\Files\NotFoundException
  55. * @since 6.0.0
  56. */
  57. public function get($path);
  58. /**
  59. * Check if a file or folder exists in the folder
  60. *
  61. * @param string $path relative path of the file or folder
  62. * @return bool
  63. * @since 6.0.0
  64. */
  65. public function nodeExists($path);
  66. /**
  67. * Create a new folder
  68. *
  69. * @param string $path relative path of the new folder
  70. * @return \OCP\Files\Folder
  71. * @throws \OCP\Files\NotPermittedException
  72. * @since 6.0.0
  73. */
  74. public function newFolder($path);
  75. /**
  76. * Create a new file
  77. *
  78. * @param string $path relative path of the new file
  79. * @param string|resource|null $content content for the new file, since 19.0.0
  80. * @return \OCP\Files\File
  81. * @throws \OCP\Files\NotPermittedException
  82. * @since 6.0.0
  83. */
  84. public function newFile($path, $content = null);
  85. /**
  86. * search for files with the name matching $query
  87. *
  88. * @param string|ISearchQuery $query
  89. * @return \OCP\Files\Node[]
  90. * @since 6.0.0
  91. */
  92. public function search($query);
  93. /**
  94. * search for files by mimetype
  95. * $mimetype can either be a full mimetype (image/png) or a wildcard mimetype (image)
  96. *
  97. * @param string $mimetype
  98. * @return \OCP\Files\Node[]
  99. * @since 6.0.0
  100. */
  101. public function searchByMime($mimetype);
  102. /**
  103. * search for files by tag
  104. *
  105. * @param string|int $tag tag name or tag id
  106. * @param string $userId owner of the tags
  107. * @return \OCP\Files\Node[]
  108. * @since 8.0.0
  109. */
  110. public function searchByTag($tag, $userId);
  111. /**
  112. * search for files by system tag
  113. *
  114. * @param string|int $tag tag name
  115. * @param string $userId user id to ensure access on returned nodes
  116. * @return \OCP\Files\Node[]
  117. * @since 28.0.0
  118. */
  119. public function searchBySystemTag(string $tagName, string $userId, int $limit = 0, int $offset = 0);
  120. /**
  121. * get a file or folder inside the folder by its internal id
  122. *
  123. * This method could return multiple entries. For example once the file/folder
  124. * is shared or mounted (files_external) to the user multiple times.
  125. *
  126. * Note that the different entries can have different permissions.
  127. *
  128. * @param int $id
  129. * @return \OCP\Files\Node[]
  130. * @since 6.0.0
  131. */
  132. public function getById($id);
  133. /**
  134. * get a file or folder inside the folder by its internal id
  135. *
  136. * Unlike getById, this method only returns a single node even if the user has
  137. * access to the file with the requested id multiple times.
  138. *
  139. * This method provides no guarantee about which of the nodes in returned and the
  140. * returned node might, for example, have less permissions than other nodes for the same file
  141. *
  142. * Apps that require accurate information about the users access to the file should use getById
  143. * instead of pick the correct node out of the result.
  144. *
  145. * @param int $id
  146. * @return Node|null
  147. * @since 29.0.0
  148. */
  149. public function getFirstNodeById(int $id): ?Node;
  150. /**
  151. * Get the amount of free space inside the folder
  152. *
  153. * @return int
  154. * @since 6.0.0
  155. */
  156. public function getFreeSpace();
  157. /**
  158. * Check if new files or folders can be created within the folder
  159. *
  160. * @return bool
  161. * @since 6.0.0
  162. */
  163. public function isCreatable();
  164. /**
  165. * Add a suffix to the name in case the file exists
  166. *
  167. * @param string $name
  168. * @return string
  169. * @throws NotPermittedException
  170. * @since 8.1.0
  171. */
  172. public function getNonExistingName($name);
  173. /**
  174. * @param int $limit
  175. * @param int $offset
  176. * @return \OCP\Files\Node[]
  177. * @since 9.1.0
  178. */
  179. public function getRecent($limit, $offset = 0);
  180. }