diff options
Diffstat (limited to 'lib/public/Share/IManager.php')
| -rw-r--r-- | lib/public/Share/IManager.php | 112 |
1 files changed, 72 insertions, 40 deletions
diff --git a/lib/public/Share/IManager.php b/lib/public/Share/IManager.php index f6b74c4de4a..35915ad9d90 100644 --- a/lib/public/Share/IManager.php +++ b/lib/public/Share/IManager.php @@ -1,31 +1,9 @@ <?php + /** - * @copyright Copyright (c) 2016, ownCloud, Inc. - * - * @author Bjoern Schiessle <bjoern@schiessle.org> - * @author Daniel Calviño Sánchez <danxuliu@gmail.com> - * @author Joas Schilling <coding@schilljs.com> - * @author John Molakvoæ <skjnldsv@protonmail.com> - * @author Julius Härtl <jus@bitgrid.net> - * @author Lukas Reschke <lukas@statuscode.ch> - * @author Morris Jobke <hey@morrisjobke.de> - * @author Robin Appelman <robin@icewind.nl> - * @author Roeland Jago Douma <roeland@famdouma.nl> - * - * @license AGPL-3.0 - * - * This code is free software: you can redistribute it and/or modify - * it under the terms of the GNU Affero General Public License, version 3, - * as published by the Free Software Foundation. - * - * This program is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU Affero General Public License for more details. - * - * You should have received a copy of the GNU Affero General Public License, version 3, - * along with this program. If not, see <http://www.gnu.org/licenses/> - * + * SPDX-FileCopyrightText: 2016-2024 Nextcloud GmbH and Nextcloud contributors + * SPDX-FileCopyrightText: 2016 ownCloud, Inc. + * SPDX-License-Identifier: AGPL-3.0-only */ namespace OCP\Share; @@ -35,6 +13,7 @@ use OCP\Files\Node; use OCP\IUser; use OCP\Share\Exceptions\GenericShareException; use OCP\Share\Exceptions\ShareNotFound; +use OCP\Share\Exceptions\ShareTokenException; /** * This interface allows to manage sharing files between users and groups. @@ -46,7 +25,6 @@ use OCP\Share\Exceptions\ShareNotFound; * @since 9.0.0 */ interface IManager { - /** * Create a Share * @@ -64,11 +42,12 @@ interface IManager { * The state can't be changed this way: use acceptShare * * @param IShare $share + * @param bool $onlyValid Only updates valid shares, invalid shares will be deleted automatically and are not updated * @return IShare The share object * @throws \InvalidArgumentException * @since 9.0.0 */ - public function updateShare(IShare $share); + public function updateShare(IShare $share, bool $onlyValid = true); /** * Accept a share. @@ -135,10 +114,11 @@ interface IManager { * @param string $userId * @param Folder $node * @param bool $reshares + * @param bool $shallow Whether the method should stop at the first level, or look into sub-folders. * @return IShare[][] [$fileId => IShare[], ...] * @since 11.0.0 */ - public function getSharesInFolder($userId, Folder $node, $reshares = false); + public function getSharesInFolder($userId, Folder $node, $reshares = false, $shallow = true); /** * Get shares shared by (initiated) by the provided user. @@ -149,10 +129,11 @@ interface IManager { * @param bool $reshares * @param int $limit The maximum number of returned results, -1 for all results * @param int $offset + * @param bool $onlyValid Only returns valid shares, invalid shares will be deleted automatically and are not returned * @return IShare[] * @since 9.0.0 */ - public function getSharesBy($userId, $shareType, $path = null, $reshares = false, $limit = 50, $offset = 0); + public function getSharesBy($userId, $shareType, $path = null, $reshares = false, $limit = 50, $offset = 0, bool $onlyValid = true); /** * Get shares shared with $user. @@ -190,11 +171,12 @@ interface IManager { * * @param string $id * @param string|null $recipient userID of the recipient + * @param bool $onlyValid Only returns valid shares, invalid shares will be deleted automatically and are not returned * @return IShare * @throws ShareNotFound * @since 9.0.0 */ - public function getShareById($id, $recipient = null); + public function getShareById($id, $recipient = null, bool $onlyValid = true); /** * Get the share by token possible with password @@ -210,7 +192,7 @@ interface IManager { * Verify the password of a public share * * @param IShare $share - * @param string $password + * @param ?string $password * @return bool * @since 9.0.0 */ @@ -256,9 +238,10 @@ interface IManager { * |-folder2 (32) * |-fileA (42) * - * fileA is shared with user1 and user1@server1 + * fileA is shared with user1 and user1@server1 and email1@maildomain1 * folder2 is shared with group2 (user4 is a member of group2) * folder1 is shared with user2 (renamed to "folder (1)") and user2@server2 + * and email2@maildomain2 * * Then the access list to '/folder1/folder2/fileA' with $currentAccess is: * [ @@ -272,15 +255,17 @@ interface IManager { * 'user2@server2' => ['node_id' => 23, 'token' => 'FooBaR'], * ], * public => bool - * mail => bool - * ] + * mail => [ + * 'email1@maildomain1' => ['node_id' => 42, 'token' => 'aBcDeFg'], + * 'email2@maildomain2' => ['node_id' => 23, 'token' => 'hIjKlMn'], + * ] * * The access list to '/folder1/folder2/fileA' **without** $currentAccess is: * [ * users => ['user1', 'user2', 'user4'], * remote => bool, * public => bool - * mail => bool + * mail => ['email1@maildomain1', 'email2@maildomain2'] * ] * * This is required for encryption/activity @@ -319,7 +304,7 @@ interface IManager { public function shareApiAllowLinks(); /** - * Is password on public link requires + * Is password on public link required * * @param bool $checkGroupMembership Check group membership exclusion * @return bool @@ -416,6 +401,15 @@ interface IManager { public function shareWithGroupMembersOnly(); /** + * If shareWithGroupMembersOnly is enabled, return an optional + * list of groups that must be excluded from the principle of + * belonging to the same group. + * @return array + * @since 27.0.0 + */ + public function shareWithGroupMembersOnlyExcludeGroupsList(); + + /** * Check if users can share with groups * @return bool * @since 9.0.1 @@ -455,6 +449,38 @@ interface IManager { public function allowEnumerationFullMatch(): bool; /** + * Check if the search should match the email + * + * @return bool + * @since 25.0.0 + */ + public function matchEmail(): bool; + + /** + * Check if the search should ignore the second in parentheses display name if there is any + * + * @return bool + * @since 25.0.0 + */ + public function ignoreSecondDisplayName(): bool; + + + /** + * Check if custom tokens are allowed + * + * @since 31.0.0 + */ + public function allowCustomTokens(): bool; + + /** + * Check if the current user can view the share + * even if the download is disabled. + * + * @since 32.0.0 + */ + public function allowViewWithoutDownload(): bool; + + /** * Check if the current user can enumerate the target user * * @param IUser|null $currentUser @@ -467,11 +493,9 @@ interface IManager { /** * Check if sharing is disabled for the given user * - * @param string $userId - * @return bool * @since 9.0.0 */ - public function sharingDisabledForUser($userId); + public function sharingDisabledForUser(?string $userId): bool; /** * Check if outgoing server2server shares are allowed @@ -513,4 +537,12 @@ interface IManager { * @since 18.0.0 */ public function getAllShares(): iterable; + + /** + * Generate a unique share token + * + * @throws ShareTokenException Failed to generate a unique token + * @since 31.0.0 + */ + public function generateToken(): string; } |