IShareProvider.php 6.4 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239
  1. <?php
  2. /**
  3. * @copyright Copyright (c) 2016, ownCloud, Inc.
  4. *
  5. * @author Bjoern Schiessle <bjoern@schiessle.org>
  6. * @author Daniel Calviño Sánchez <danxuliu@gmail.com>
  7. * @author Joas Schilling <coding@schilljs.com>
  8. * @author Robin Appelman <robin@icewind.nl>
  9. * @author Roeland Jago Douma <roeland@famdouma.nl>
  10. *
  11. * @license AGPL-3.0
  12. *
  13. * This code is free software: you can redistribute it and/or modify
  14. * it under the terms of the GNU Affero General Public License, version 3,
  15. * as published by the Free Software Foundation.
  16. *
  17. * This program is distributed in the hope that it will be useful,
  18. * but WITHOUT ANY WARRANTY; without even the implied warranty of
  19. * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  20. * GNU Affero General Public License for more details.
  21. *
  22. * You should have received a copy of the GNU Affero General Public License, version 3,
  23. * along with this program. If not, see <http://www.gnu.org/licenses/>
  24. *
  25. */
  26. namespace OCP\Share;
  27. use OCP\Files\Folder;
  28. use OCP\Files\Node;
  29. use OCP\Share\Exceptions\GenericShareException;
  30. use OCP\Share\Exceptions\ShareNotFound;
  31. /**
  32. * Interface IShareProvider
  33. *
  34. * @since 9.0.0
  35. */
  36. interface IShareProvider {
  37. /**
  38. * Return the identifier of this provider.
  39. *
  40. * @return string Containing only [a-zA-Z0-9]
  41. * @since 9.0.0
  42. */
  43. public function identifier();
  44. /**
  45. * Create a share
  46. *
  47. * @param \OCP\Share\IShare $share
  48. * @return \OCP\Share\IShare The share object
  49. * @since 9.0.0
  50. */
  51. public function create(\OCP\Share\IShare $share);
  52. /**
  53. * Update a share
  54. *
  55. * @param \OCP\Share\IShare $share
  56. * @return \OCP\Share\IShare The share object
  57. * @since 9.0.0
  58. */
  59. public function update(\OCP\Share\IShare $share);
  60. /**
  61. * Accept a share.
  62. *
  63. * @param IShare $share
  64. * @param string $recipient
  65. * @return IShare The share object
  66. * @since 17.0.0
  67. */
  68. // public function acceptShare(IShare $share, string $recipient): IShare;
  69. /**
  70. * Delete a share
  71. *
  72. * @param \OCP\Share\IShare $share
  73. * @since 9.0.0
  74. */
  75. public function delete(\OCP\Share\IShare $share);
  76. /**
  77. * Unshare a file from self as recipient.
  78. * This may require special handling. If a user unshares a group
  79. * share from their self then the original group share should still exist.
  80. *
  81. * @param \OCP\Share\IShare $share
  82. * @param string $recipient UserId of the recipient
  83. * @since 9.0.0
  84. */
  85. public function deleteFromSelf(\OCP\Share\IShare $share, $recipient);
  86. /**
  87. * Restore a share for a given recipient. The implementation could be provider independant.
  88. *
  89. * @param IShare $share
  90. * @param string $recipient
  91. * @return IShare The restored share object
  92. *
  93. * @since 14.0.0
  94. * @throws GenericShareException In case the share could not be restored
  95. */
  96. public function restore(IShare $share, string $recipient): IShare;
  97. /**
  98. * Move a share as a recipient.
  99. * This is updating the share target. Thus the mount point of the recipient.
  100. * This may require special handling. If a user moves a group share
  101. * the target should only be changed for them.
  102. *
  103. * @param \OCP\Share\IShare $share
  104. * @param string $recipient userId of recipient
  105. * @return \OCP\Share\IShare
  106. * @since 9.0.0
  107. */
  108. public function move(\OCP\Share\IShare $share, $recipient);
  109. /**
  110. * Get all shares by the given user in a folder
  111. *
  112. * @param string $userId
  113. * @param Folder $node
  114. * @param bool $reshares Also get the shares where $user is the owner instead of just the shares where $user is the initiator
  115. * @param bool $shallow Whether the method should stop at the first level, or look into sub-folders.
  116. * @return \OCP\Share\IShare[][]
  117. * @since 11.0.0
  118. */
  119. public function getSharesInFolder($userId, Folder $node, $reshares, $shallow = true);
  120. /**
  121. * Get all shares by the given user
  122. *
  123. * @param string $userId
  124. * @param int $shareType
  125. * @param Node|null $node
  126. * @param bool $reshares Also get the shares where $user is the owner instead of just the shares where $user is the initiator
  127. * @param int $limit The maximum number of shares to be returned, -1 for all shares
  128. * @param int $offset
  129. * @return \OCP\Share\IShare[]
  130. * @since 9.0.0
  131. */
  132. public function getSharesBy($userId, $shareType, $node, $reshares, $limit, $offset);
  133. /**
  134. * Get share by id
  135. *
  136. * @param int $id
  137. * @param string|null $recipientId
  138. * @return \OCP\Share\IShare
  139. * @throws ShareNotFound
  140. * @since 9.0.0
  141. */
  142. public function getShareById($id, $recipientId = null);
  143. /**
  144. * Get shares for a given path
  145. *
  146. * @param Node $path
  147. * @return \OCP\Share\IShare[]
  148. * @since 9.0.0
  149. */
  150. public function getSharesByPath(Node $path);
  151. /**
  152. * Get shared with the given user
  153. *
  154. * @param string $userId get shares where this user is the recipient
  155. * @param int $shareType
  156. * @param Node|null $node
  157. * @param int $limit The max number of entries returned, -1 for all
  158. * @param int $offset
  159. * @return \OCP\Share\IShare[]
  160. * @since 9.0.0
  161. */
  162. public function getSharedWith($userId, $shareType, $node, $limit, $offset);
  163. /**
  164. * Get a share by token
  165. *
  166. * @param string $token
  167. * @return \OCP\Share\IShare
  168. * @throws ShareNotFound
  169. * @since 9.0.0
  170. */
  171. public function getShareByToken($token);
  172. /**
  173. * A user is deleted from the system
  174. * So clean up the relevant shares.
  175. *
  176. * @param string $uid
  177. * @param int $shareType
  178. * @since 9.1.0
  179. */
  180. public function userDeleted($uid, $shareType);
  181. /**
  182. * A group is deleted from the system.
  183. * We have to clean up all shares to this group.
  184. * Providers not handling group shares should just return
  185. *
  186. * @param string $gid
  187. * @since 9.1.0
  188. */
  189. public function groupDeleted($gid);
  190. /**
  191. * A user is deleted from a group
  192. * We have to clean up all the related user specific group shares
  193. * Providers not handling group shares should just return
  194. *
  195. * @param string $uid
  196. * @param string $gid
  197. * @since 9.1.0
  198. */
  199. public function userDeletedFromGroup($uid, $gid);
  200. /**
  201. * Get the access list to the array of provided nodes.
  202. *
  203. * @see IManager::getAccessList() for sample docs
  204. *
  205. * @param Node[] $nodes The list of nodes to get access for
  206. * @param bool $currentAccess If current access is required (like for removed shares that might get revived later)
  207. * @return array
  208. * @since 12
  209. */
  210. public function getAccessList($nodes, $currentAccess);
  211. /**
  212. * Get all the shares in this provider returned as iterable to reduce memory
  213. * overhead
  214. *
  215. * @return iterable
  216. * @since 18.0.0
  217. */
  218. public function getAllShares(): iterable;
  219. }