IManager.php 13 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533
  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 John Molakvoæ <skjnldsv@protonmail.com>
  9. * @author Julius Härtl <jus@bitgrid.net>
  10. * @author Lukas Reschke <lukas@statuscode.ch>
  11. * @author Morris Jobke <hey@morrisjobke.de>
  12. * @author Robin Appelman <robin@icewind.nl>
  13. * @author Roeland Jago Douma <roeland@famdouma.nl>
  14. *
  15. * @license AGPL-3.0
  16. *
  17. * This code is free software: you can redistribute it and/or modify
  18. * it under the terms of the GNU Affero General Public License, version 3,
  19. * as published by the Free Software Foundation.
  20. *
  21. * This program is distributed in the hope that it will be useful,
  22. * but WITHOUT ANY WARRANTY; without even the implied warranty of
  23. * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  24. * GNU Affero General Public License for more details.
  25. *
  26. * You should have received a copy of the GNU Affero General Public License, version 3,
  27. * along with this program. If not, see <http://www.gnu.org/licenses/>
  28. *
  29. */
  30. namespace OCP\Share;
  31. use OCP\Files\Folder;
  32. use OCP\Files\Node;
  33. use OCP\IUser;
  34. use OCP\Share\Exceptions\GenericShareException;
  35. use OCP\Share\Exceptions\ShareNotFound;
  36. /**
  37. * This interface allows to manage sharing files between users and groups.
  38. *
  39. * This interface must not be implemented in your application but
  40. * instead should be used as a service and injected in your code with
  41. * dependency injection.
  42. *
  43. * @since 9.0.0
  44. */
  45. interface IManager {
  46. /**
  47. * Create a Share
  48. *
  49. * @param IShare $share
  50. * @return IShare The share object
  51. * @throws \Exception
  52. * @since 9.0.0
  53. */
  54. public function createShare(IShare $share);
  55. /**
  56. * Update a share.
  57. * The target of the share can't be changed this way: use moveShare
  58. * The share can't be removed this way (permission 0): use deleteShare
  59. * The state can't be changed this way: use acceptShare
  60. *
  61. * @param IShare $share
  62. * @return IShare The share object
  63. * @throws \InvalidArgumentException
  64. * @since 9.0.0
  65. */
  66. public function updateShare(IShare $share);
  67. /**
  68. * Accept a share.
  69. *
  70. * @param IShare $share
  71. * @param string $recipientId
  72. * @return IShare The share object
  73. * @throws \InvalidArgumentException
  74. * @since 18.0.0
  75. */
  76. public function acceptShare(IShare $share, string $recipientId): IShare;
  77. /**
  78. * Delete a share
  79. *
  80. * @param IShare $share
  81. * @throws ShareNotFound
  82. * @throws \InvalidArgumentException
  83. * @since 9.0.0
  84. */
  85. public function deleteShare(IShare $share);
  86. /**
  87. * Unshare a file as the recipient.
  88. * This can be different from a regular delete for example when one of
  89. * the users in a groups deletes that share. But the provider should
  90. * handle this.
  91. *
  92. * @param IShare $share
  93. * @param string $recipientId
  94. * @since 9.0.0
  95. */
  96. public function deleteFromSelf(IShare $share, $recipientId);
  97. /**
  98. * Restore the share when it has been deleted
  99. * Certain share types can be restored when they have been deleted
  100. * but the provider should properly handle this\
  101. *
  102. * @param IShare $share The share to restore
  103. * @param string $recipientId The user to restore the share for
  104. * @return IShare The restored share object
  105. * @throws GenericShareException In case restoring the share failed
  106. *
  107. * @since 14.0.0
  108. */
  109. public function restoreShare(IShare $share, string $recipientId): IShare;
  110. /**
  111. * Move the share as a recipient of the share.
  112. * This is updating the share target. So where the recipient has the share mounted.
  113. *
  114. * @param IShare $share
  115. * @param string $recipientId
  116. * @return IShare
  117. * @throws \InvalidArgumentException If $share is a link share or the $recipient does not match
  118. * @since 9.0.0
  119. */
  120. public function moveShare(IShare $share, $recipientId);
  121. /**
  122. * Get all shares shared by (initiated) by the provided user in a folder.
  123. *
  124. * @param string $userId
  125. * @param Folder $node
  126. * @param bool $reshares
  127. * @param bool $shallow Whether the method should stop at the first level, or look into sub-folders.
  128. * @return IShare[][] [$fileId => IShare[], ...]
  129. * @since 11.0.0
  130. */
  131. public function getSharesInFolder($userId, Folder $node, $reshares = false, $shallow = true);
  132. /**
  133. * Get shares shared by (initiated) by the provided user.
  134. *
  135. * @param string $userId
  136. * @param int $shareType
  137. * @param Node|null $path
  138. * @param bool $reshares
  139. * @param int $limit The maximum number of returned results, -1 for all results
  140. * @param int $offset
  141. * @return IShare[]
  142. * @since 9.0.0
  143. */
  144. public function getSharesBy($userId, $shareType, $path = null, $reshares = false, $limit = 50, $offset = 0);
  145. /**
  146. * Get shares shared with $user.
  147. * Filter by $node if provided
  148. *
  149. * @param string $userId
  150. * @param int $shareType
  151. * @param Node|null $node
  152. * @param int $limit The maximum number of shares returned, -1 for all
  153. * @param int $offset
  154. * @return IShare[]
  155. * @since 9.0.0
  156. */
  157. public function getSharedWith($userId, $shareType, $node = null, $limit = 50, $offset = 0);
  158. /**
  159. * Get deleted shares shared with $user.
  160. * Filter by $node if provided
  161. *
  162. * @param string $userId
  163. * @param int $shareType
  164. * @param Node|null $node
  165. * @param int $limit The maximum number of shares returned, -1 for all
  166. * @param int $offset
  167. * @return IShare[]
  168. * @since 14.0.0
  169. */
  170. public function getDeletedSharedWith($userId, $shareType, $node = null, $limit = 50, $offset = 0);
  171. /**
  172. * Retrieve a share by the share id.
  173. * If the recipient is set make sure to retrieve the file for that user.
  174. * This makes sure that if a user has moved/deleted a group share this
  175. * is reflected.
  176. *
  177. * @param string $id
  178. * @param string|null $recipient userID of the recipient
  179. * @return IShare
  180. * @throws ShareNotFound
  181. * @since 9.0.0
  182. */
  183. public function getShareById($id, $recipient = null);
  184. /**
  185. * Get the share by token possible with password
  186. *
  187. * @param string $token
  188. * @return IShare
  189. * @throws ShareNotFound
  190. * @since 9.0.0
  191. */
  192. public function getShareByToken($token);
  193. /**
  194. * Verify the password of a public share
  195. *
  196. * @param IShare $share
  197. * @param ?string $password
  198. * @return bool
  199. * @since 9.0.0
  200. */
  201. public function checkPassword(IShare $share, $password);
  202. /**
  203. * The user with UID is deleted.
  204. * All share providers have to cleanup the shares with this user as well
  205. * as shares owned by this user.
  206. * Shares only initiated by this user are fine.
  207. *
  208. * @param string $uid
  209. * @since 9.1.0
  210. */
  211. public function userDeleted($uid);
  212. /**
  213. * The group with $gid is deleted
  214. * We need to clear up all shares to this group
  215. *
  216. * @param string $gid
  217. * @since 9.1.0
  218. */
  219. public function groupDeleted($gid);
  220. /**
  221. * The user $uid is deleted from the group $gid
  222. * All user specific group shares have to be removed
  223. *
  224. * @param string $uid
  225. * @param string $gid
  226. * @since 9.1.0
  227. */
  228. public function userDeletedFromGroup($uid, $gid);
  229. /**
  230. * Get access list to a path. This means
  231. * all the users that can access a given path.
  232. *
  233. * Consider:
  234. * -root
  235. * |-folder1 (23)
  236. * |-folder2 (32)
  237. * |-fileA (42)
  238. *
  239. * fileA is shared with user1 and user1@server1
  240. * folder2 is shared with group2 (user4 is a member of group2)
  241. * folder1 is shared with user2 (renamed to "folder (1)") and user2@server2
  242. *
  243. * Then the access list to '/folder1/folder2/fileA' with $currentAccess is:
  244. * [
  245. * users => [
  246. * 'user1' => ['node_id' => 42, 'node_path' => '/fileA'],
  247. * 'user4' => ['node_id' => 32, 'node_path' => '/folder2'],
  248. * 'user2' => ['node_id' => 23, 'node_path' => '/folder (1)'],
  249. * ],
  250. * remote => [
  251. * 'user1@server1' => ['node_id' => 42, 'token' => 'SeCr3t'],
  252. * 'user2@server2' => ['node_id' => 23, 'token' => 'FooBaR'],
  253. * ],
  254. * public => bool
  255. * mail => bool
  256. * ]
  257. *
  258. * The access list to '/folder1/folder2/fileA' **without** $currentAccess is:
  259. * [
  260. * users => ['user1', 'user2', 'user4'],
  261. * remote => bool,
  262. * public => bool
  263. * mail => bool
  264. * ]
  265. *
  266. * This is required for encryption/activity
  267. *
  268. * @param \OCP\Files\Node $path
  269. * @param bool $recursive Should we check all parent folders as well
  270. * @param bool $currentAccess Should the user have currently access to the file
  271. * @return array
  272. * @since 12
  273. */
  274. public function getAccessList(\OCP\Files\Node $path, $recursive = true, $currentAccess = false);
  275. /**
  276. * Instantiates a new share object. This is to be passed to
  277. * createShare.
  278. *
  279. * @return IShare
  280. * @since 9.0.0
  281. */
  282. public function newShare();
  283. /**
  284. * Is the share API enabled
  285. *
  286. * @return bool
  287. * @since 9.0.0
  288. */
  289. public function shareApiEnabled();
  290. /**
  291. * Is public link sharing enabled
  292. *
  293. * @return bool
  294. * @since 9.0.0
  295. */
  296. public function shareApiAllowLinks();
  297. /**
  298. * Is password on public link requires
  299. *
  300. * @param bool $checkGroupMembership Check group membership exclusion
  301. * @return bool
  302. * @since 9.0.0
  303. * @since 24.0.0 Added optional $checkGroupMembership parameter
  304. */
  305. public function shareApiLinkEnforcePassword(bool $checkGroupMembership = true);
  306. /**
  307. * Is default expire date enabled
  308. *
  309. * @return bool
  310. * @since 9.0.0
  311. */
  312. public function shareApiLinkDefaultExpireDate();
  313. /**
  314. * Is default expire date enforced
  315. *`
  316. * @return bool
  317. * @since 9.0.0
  318. */
  319. public function shareApiLinkDefaultExpireDateEnforced();
  320. /**
  321. * Number of default expire days
  322. *
  323. * @return int
  324. * @since 9.0.0
  325. */
  326. public function shareApiLinkDefaultExpireDays();
  327. /**
  328. * Is default internal expire date enabled
  329. *
  330. * @return bool
  331. * @since 22.0.0
  332. */
  333. public function shareApiInternalDefaultExpireDate(): bool;
  334. /**
  335. * Is default remote expire date enabled
  336. *
  337. * @return bool
  338. * @since 22.0.0
  339. */
  340. public function shareApiRemoteDefaultExpireDate(): bool;
  341. /**
  342. * Is default expire date enforced
  343. *
  344. * @return bool
  345. * @since 22.0.0
  346. */
  347. public function shareApiInternalDefaultExpireDateEnforced(): bool;
  348. /**
  349. * Is default expire date enforced for remote shares
  350. *
  351. * @return bool
  352. * @since 22.0.0
  353. */
  354. public function shareApiRemoteDefaultExpireDateEnforced(): bool;
  355. /**
  356. * Number of default expire days
  357. *
  358. * @return int
  359. * @since 22.0.0
  360. */
  361. public function shareApiInternalDefaultExpireDays(): int;
  362. /**
  363. * Number of default expire days for remote shares
  364. *
  365. * @return int
  366. * @since 22.0.0
  367. */
  368. public function shareApiRemoteDefaultExpireDays(): int;
  369. /**
  370. * Allow public upload on link shares
  371. *
  372. * @return bool
  373. * @since 9.0.0
  374. */
  375. public function shareApiLinkAllowPublicUpload();
  376. /**
  377. * check if user can only share with group members
  378. * @return bool
  379. * @since 9.0.0
  380. */
  381. public function shareWithGroupMembersOnly();
  382. /**
  383. * Check if users can share with groups
  384. * @return bool
  385. * @since 9.0.1
  386. */
  387. public function allowGroupSharing();
  388. /**
  389. * Check if user enumeration is allowed
  390. *
  391. * @return bool
  392. * @since 19.0.0
  393. */
  394. public function allowEnumeration(): bool;
  395. /**
  396. * Check if user enumeration is limited to the users groups
  397. *
  398. * @return bool
  399. * @since 19.0.0
  400. */
  401. public function limitEnumerationToGroups(): bool;
  402. /**
  403. * Check if user enumeration is limited to the phonebook matches
  404. *
  405. * @return bool
  406. * @since 21.0.1
  407. */
  408. public function limitEnumerationToPhone(): bool;
  409. /**
  410. * Check if user enumeration is allowed to return on full match
  411. *
  412. * @return bool
  413. * @since 21.0.1
  414. */
  415. public function allowEnumerationFullMatch(): bool;
  416. /**
  417. * Check if the search should match the email
  418. *
  419. * @return bool
  420. * @since 25.0.0
  421. */
  422. public function matchEmail(): bool;
  423. /**
  424. * Check if the search should ignore the second in parentheses display name if there is any
  425. *
  426. * @return bool
  427. * @since 25.0.0
  428. */
  429. public function ignoreSecondDisplayName(): bool;
  430. /**
  431. * Check if the current user can enumerate the target user
  432. *
  433. * @param IUser|null $currentUser
  434. * @param IUser $targetUser
  435. * @return bool
  436. * @since 23.0.0
  437. */
  438. public function currentUserCanEnumerateTargetUser(?IUser $currentUser, IUser $targetUser): bool;
  439. /**
  440. * Check if sharing is disabled for the given user
  441. *
  442. * @param string $userId
  443. * @return bool
  444. * @since 9.0.0
  445. */
  446. public function sharingDisabledForUser($userId);
  447. /**
  448. * Check if outgoing server2server shares are allowed
  449. * @return bool
  450. * @since 9.0.0
  451. */
  452. public function outgoingServer2ServerSharesAllowed();
  453. /**
  454. * Check if outgoing server2server shares are allowed
  455. * @return bool
  456. * @since 14.0.0
  457. */
  458. public function outgoingServer2ServerGroupSharesAllowed();
  459. /**
  460. * Check if a given share provider exists
  461. * @param int $shareType
  462. * @return bool
  463. * @since 11.0.0
  464. */
  465. public function shareProviderExists($shareType);
  466. /**
  467. * @param string $shareProviderClass
  468. * @since 21.0.0
  469. */
  470. public function registerShareProvider(string $shareProviderClass): void;
  471. /**
  472. * @Internal
  473. *
  474. * Get all the shares as iterable to reduce memory overhead
  475. * Note, since this opens up database cursors the iterable should
  476. * be fully itterated.
  477. *
  478. * @return iterable
  479. * @since 18.0.0
  480. */
  481. public function getAllShares(): iterable;
  482. }