diff options
Diffstat (limited to 'lib/public/Share')
23 files changed, 558 insertions, 296 deletions
diff --git a/lib/public/Share/Events/BeforeShareCreatedEvent.php b/lib/public/Share/Events/BeforeShareCreatedEvent.php new file mode 100644 index 00000000000..a2149b53e97 --- /dev/null +++ b/lib/public/Share/Events/BeforeShareCreatedEvent.php @@ -0,0 +1,49 @@ +<?php + +declare(strict_types=1); + +/** + * SPDX-FileCopyrightText: 2023 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later + */ +namespace OCP\Share\Events; + +use OCP\EventDispatcher\Event; +use OCP\Share\IShare; + +/** + * @since 28.0.0 + */ +class BeforeShareCreatedEvent extends Event { + private ?string $error = null; + + /** + * @since 28.0.0 + */ + public function __construct( + private IShare $share, + ) { + parent::__construct(); + } + + /** + * @since 28.0.0 + */ + public function getShare(): IShare { + return $this->share; + } + + /** + * @since 28.0.0 + */ + public function setError(string $error): void { + $this->error = $error; + } + + /** + * @since 28.0.0 + */ + public function getError(): ?string { + return $this->error; + } +} diff --git a/lib/public/Share/Events/BeforeShareDeletedEvent.php b/lib/public/Share/Events/BeforeShareDeletedEvent.php new file mode 100644 index 00000000000..0af902f7fb7 --- /dev/null +++ b/lib/public/Share/Events/BeforeShareDeletedEvent.php @@ -0,0 +1,33 @@ +<?php + +declare(strict_types=1); + +/** + * SPDX-FileCopyrightText: 2023 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later + */ +namespace OCP\Share\Events; + +use OCP\EventDispatcher\Event; +use OCP\Share\IShare; + +/** + * @since 28.0.0 + */ +class BeforeShareDeletedEvent extends Event { + /** + * @since 28.0.0 + */ + public function __construct( + private IShare $share, + ) { + parent::__construct(); + } + + /** + * @since 28.0.0 + */ + public function getShare(): IShare { + return $this->share; + } +} diff --git a/lib/public/Share/Events/ShareAcceptedEvent.php b/lib/public/Share/Events/ShareAcceptedEvent.php new file mode 100644 index 00000000000..dd9061563cc --- /dev/null +++ b/lib/public/Share/Events/ShareAcceptedEvent.php @@ -0,0 +1,33 @@ +<?php + +declare(strict_types=1); + +/** + * SPDX-FileCopyrightText: 2023 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later + */ +namespace OCP\Share\Events; + +use OCP\EventDispatcher\Event; +use OCP\Share\IShare; + +/** + * @since 28.0.0 + */ +class ShareAcceptedEvent extends Event { + /** + * @since 28.0.0 + */ + public function __construct( + private IShare $share, + ) { + parent::__construct(); + } + + /** + * @since 28.0.0 + */ + public function getShare(): IShare { + return $this->share; + } +} diff --git a/lib/public/Share/Events/ShareCreatedEvent.php b/lib/public/Share/Events/ShareCreatedEvent.php index 85de3a83040..e733c56bc74 100644 --- a/lib/public/Share/Events/ShareCreatedEvent.php +++ b/lib/public/Share/Events/ShareCreatedEvent.php @@ -3,25 +3,8 @@ declare(strict_types=1); /** - * @copyright Copyright (c) 2019, Roeland Jago Douma <roeland@famdouma.nl> - * - * @author Roeland Jago Douma <roeland@famdouma.nl> - * - * @license GNU AGPL version 3 or any later version - * - * This program is free software: you can redistribute it and/or modify - * it under the terms of the GNU Affero General Public License as - * published by the Free Software Foundation, either version 3 of the - * License, or (at your option) any later version. - * - * 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 - * along with this program. If not, see <http://www.gnu.org/licenses/>. - * + * SPDX-FileCopyrightText: 2019 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later */ namespace OCP\Share\Events; @@ -32,7 +15,6 @@ use OCP\Share\IShare; * @since 18.0.0 */ class ShareCreatedEvent extends Event { - /** @var IShare */ private $share; diff --git a/lib/public/Share/Events/ShareDeletedEvent.php b/lib/public/Share/Events/ShareDeletedEvent.php index 9a42088a8ff..70887a3f80b 100644 --- a/lib/public/Share/Events/ShareDeletedEvent.php +++ b/lib/public/Share/Events/ShareDeletedEvent.php @@ -3,26 +3,8 @@ declare(strict_types=1); /** - * @copyright Copyright (c) 2020, Maxence Lange <maxence@artificial-owl.com> - * - * @author Maxence Lange <maxence@artificial-owl.com> - * @author Roeland Jago Douma <roeland@famdouma.nl> - * - * @license GNU AGPL version 3 or any later version - * - * This program is free software: you can redistribute it and/or modify - * it under the terms of the GNU Affero General Public License as - * published by the Free Software Foundation, either version 3 of the - * License, or (at your option) any later version. - * - * 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 - * along with this program. If not, see <http://www.gnu.org/licenses/>. - * + * SPDX-FileCopyrightText: 2020 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later */ namespace OCP\Share\Events; @@ -33,7 +15,6 @@ use OCP\Share\IShare; * @since 21.0.0 */ class ShareDeletedEvent extends Event { - /** @var IShare */ private $share; diff --git a/lib/public/Share/Events/ShareDeletedFromSelfEvent.php b/lib/public/Share/Events/ShareDeletedFromSelfEvent.php new file mode 100644 index 00000000000..1e49975acea --- /dev/null +++ b/lib/public/Share/Events/ShareDeletedFromSelfEvent.php @@ -0,0 +1,33 @@ +<?php + +declare(strict_types=1); + +/** + * SPDX-FileCopyrightText: 2023 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later + */ +namespace OCP\Share\Events; + +use OCP\EventDispatcher\Event; +use OCP\Share\IShare; + +/** + * @since 28.0.0 + */ +class ShareDeletedFromSelfEvent extends Event { + /** + * @since 28.0.0 + */ + public function __construct( + private IShare $share, + ) { + parent::__construct(); + } + + /** + * @since 28.0.0 + */ + public function getShare(): IShare { + return $this->share; + } +} diff --git a/lib/public/Share/Events/VerifyMountPointEvent.php b/lib/public/Share/Events/VerifyMountPointEvent.php index c824eea4608..2eb392773e4 100644 --- a/lib/public/Share/Events/VerifyMountPointEvent.php +++ b/lib/public/Share/Events/VerifyMountPointEvent.php @@ -3,25 +3,8 @@ declare(strict_types=1); /** - * @copyright Copyright (c) 2020, Joas Schilling <coding@schilljs.com> - * - * @author Joas Schilling <coding@schilljs.com> - * - * @license GNU AGPL version 3 or any later version - * - * This program is free software: you can redistribute it and/or modify - * it under the terms of the GNU Affero General Public License as - * published by the Free Software Foundation, either version 3 of the - * License, or (at your option) any later version. - * - * 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 - * along with this program. If not, see <http://www.gnu.org/licenses/>. - * + * SPDX-FileCopyrightText: 2020 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later */ namespace OCP\Share\Events; @@ -33,7 +16,6 @@ use OCP\Share\IShare; * @since 19.0.0 */ class VerifyMountPointEvent extends Event { - /** @var IShare */ private $share; /** @var View */ @@ -45,8 +27,8 @@ class VerifyMountPointEvent extends Event { * @since 19.0.0 */ public function __construct(IShare $share, - View $view, - string $parent) { + View $view, + string $parent) { parent::__construct(); $this->share = $share; diff --git a/lib/public/Share/Exceptions/AlreadySharedException.php b/lib/public/Share/Exceptions/AlreadySharedException.php index 06cb93cb6af..ce58dd19e2a 100644 --- a/lib/public/Share/Exceptions/AlreadySharedException.php +++ b/lib/public/Share/Exceptions/AlreadySharedException.php @@ -3,25 +3,8 @@ declare(strict_types=1); /** - * @copyright Copyright (c) 2021 Robin Appelman <robin@icewind.nl> - * - * @author Robin Appelman <robin@icewind.nl> - * - * @license GNU AGPL version 3 or any later version - * - * This program is free software: you can redistribute it and/or modify - * it under the terms of the GNU Affero General Public License as - * published by the Free Software Foundation, either version 3 of the - * License, or (at your option) any later version. - * - * 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 - * along with this program. If not, see <http://www.gnu.org/licenses/>. - * + * SPDX-FileCopyrightText: 2021 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later */ namespace OCP\Share\Exceptions; diff --git a/lib/public/Share/Exceptions/GenericShareException.php b/lib/public/Share/Exceptions/GenericShareException.php index 85c440e2387..b94d210f970 100644 --- a/lib/public/Share/Exceptions/GenericShareException.php +++ b/lib/public/Share/Exceptions/GenericShareException.php @@ -1,26 +1,9 @@ <?php + /** - * @copyright Copyright (c) 2016, ownCloud, Inc. - * - * @author Christoph Wurst <christoph@winzerhof-wurst.at> - * @author Jan-Christoph Borchardt <hey@jancborchardt.net> - * @author Lukas Reschke <lukas@statuscode.ch> - * @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\Exceptions; @@ -32,7 +15,6 @@ use OCP\HintException; * @since 9.0.0 */ class GenericShareException extends HintException { - /** * @param string $message * @param string $hint @@ -40,7 +22,7 @@ class GenericShareException extends HintException { * @param \Exception|null $previous * @since 9.0.0 */ - public function __construct($message = '', $hint = '', $code = 0, \Exception $previous = null) { + public function __construct($message = '', $hint = '', $code = 0, ?\Exception $previous = null) { if (empty($message)) { $message = 'There was an error retrieving the share. Maybe the link is wrong, it was unshared, or it was deleted.'; } diff --git a/lib/public/Share/Exceptions/IllegalIDChangeException.php b/lib/public/Share/Exceptions/IllegalIDChangeException.php index 563a227e963..e9ff4b66c42 100644 --- a/lib/public/Share/Exceptions/IllegalIDChangeException.php +++ b/lib/public/Share/Exceptions/IllegalIDChangeException.php @@ -1,24 +1,9 @@ <?php + /** - * @copyright Copyright (c) 2016, ownCloud, Inc. - * - * @author Christoph Wurst <christoph@winzerhof-wurst.at> - * @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\Exceptions; diff --git a/lib/public/Share/Exceptions/ShareNotFound.php b/lib/public/Share/Exceptions/ShareNotFound.php index 66827b4d179..0876078424e 100644 --- a/lib/public/Share/Exceptions/ShareNotFound.php +++ b/lib/public/Share/Exceptions/ShareNotFound.php @@ -1,23 +1,9 @@ <?php + /** - * @copyright Copyright (c) 2016, ownCloud, Inc. - * - * @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\Exceptions; @@ -27,7 +13,6 @@ namespace OCP\Share\Exceptions; * @since 9.0.0 */ class ShareNotFound extends GenericShareException { - /** * @param string $message * @param string $hint diff --git a/lib/public/Share/Exceptions/ShareTokenException.php b/lib/public/Share/Exceptions/ShareTokenException.php new file mode 100644 index 00000000000..027d00640e9 --- /dev/null +++ b/lib/public/Share/Exceptions/ShareTokenException.php @@ -0,0 +1,16 @@ +<?php + +/** + * SPDX-FileCopyrightText: 2024 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later + */ + +namespace OCP\Share\Exceptions; + +use Exception; + +/** + * @since 31.0.0 + */ +class ShareTokenException extends Exception { +} diff --git a/lib/public/Share/IAttributes.php b/lib/public/Share/IAttributes.php new file mode 100644 index 00000000000..9ddd8275dd6 --- /dev/null +++ b/lib/public/Share/IAttributes.php @@ -0,0 +1,54 @@ +<?php + +/** + * SPDX-FileCopyrightText: 2019 ownCloud GmbH + * SPDX-License-Identifier: AGPL-3.0-only + */ +namespace OCP\Share; + +/** + * Interface IAttributes + * + * @package OCP\Share + * @since 25.0.0 + */ +interface IAttributes { + /** + * Sets an attribute. If the key did not exist before it will be created. + * + * @param string $scope scope + * @param string $key key + * @param bool|string|array|null $value value + * @return IAttributes The modified object + * @since 25.0.0 + */ + public function setAttribute(string $scope, string $key, mixed $value): IAttributes; + + /** + * Returns the attribute for given scope id and key. + * If attribute does not exist, returns null + * + * @param string $scope scope + * @param string $key key + * @return bool|string|array|null + * @since 25.0.0 + */ + public function getAttribute(string $scope, string $key): mixed; + + /** + * Formats the IAttributes object to array with the following format: + * [ + * 0 => [ + * "scope" => <string>, + * "key" => <string>, + * "value" => <bool|string|array|null>, + * ], + * ... + * ] + * + * @return array formatted IAttributes + * @since 25.0.0 + * @since 30.0.0, `enabled` was renamed to `value` + */ + public function toArray(): array; +} 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; } diff --git a/lib/public/Share/IProviderFactory.php b/lib/public/Share/IProviderFactory.php index 71d95203007..9107274c8c1 100644 --- a/lib/public/Share/IProviderFactory.php +++ b/lib/public/Share/IProviderFactory.php @@ -1,25 +1,9 @@ <?php + /** - * @copyright Copyright (c) 2016, ownCloud, Inc. - * - * @author Julius Härtl <jus@bitgrid.net> - * @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; @@ -31,7 +15,6 @@ use OC\Share20\Exception\ProviderException; * @since 9.0.0 */ interface IProviderFactory { - /** * @param string $id * @return IShareProvider @@ -56,7 +39,8 @@ interface IProviderFactory { /** * @since 21.0.0 - * @param string $shareProvier + * @since 32.0.0 Fix typo in parameter name + * @param string $shareProviderClass */ - public function registerProvider(string $shareProvier): void; + public function registerProvider(string $shareProviderClass): void; } diff --git a/lib/public/Share/IPublicShareTemplateFactory.php b/lib/public/Share/IPublicShareTemplateFactory.php new file mode 100644 index 00000000000..1825c0c7dc6 --- /dev/null +++ b/lib/public/Share/IPublicShareTemplateFactory.php @@ -0,0 +1,19 @@ +<?php + +declare(strict_types=1); +/** + * SPDX-FileCopyrightText: 2023 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later + */ +namespace OCP\Share; + +/** + * @since 26.0.0 + */ +interface IPublicShareTemplateFactory { + /** + * Returns a provider that is willing to respond for given share. + * @since 26.0.0 + */ + public function getProvider(IShare $share): IPublicShareTemplateProvider; +} diff --git a/lib/public/Share/IPublicShareTemplateProvider.php b/lib/public/Share/IPublicShareTemplateProvider.php new file mode 100644 index 00000000000..46812a65814 --- /dev/null +++ b/lib/public/Share/IPublicShareTemplateProvider.php @@ -0,0 +1,27 @@ +<?php + +declare(strict_types=1); +/** + * SPDX-FileCopyrightText: 2023 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later + */ + +namespace OCP\Share; + +use OCP\AppFramework\Http\TemplateResponse; + +/** + * @since 26.0.0 + */ +interface IPublicShareTemplateProvider { + /** + * Returns whether the provider can respond for the given share. + * @since 26.0.0 + */ + public function shouldRespond(IShare $share): bool; + /** + * Returns the a template for a given share. + * @since 26.0.0 + */ + public function renderPage(IShare $share, string $token, string $path): TemplateResponse; +} diff --git a/lib/public/Share/IShare.php b/lib/public/Share/IShare.php index 1d3cf9bbbdf..a1bdb01fcd2 100644 --- a/lib/public/Share/IShare.php +++ b/lib/public/Share/IShare.php @@ -1,30 +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 Maxence Lange <maxence@nextcloud.com> - * @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; @@ -36,12 +15,13 @@ use OCP\Files\NotFoundException; use OCP\Share\Exceptions\IllegalIDChangeException; /** - * Interface IShare + * This interface allows to represent a share object. + * + * This interface must not be implemented in your application. * * @since 9.0.0 */ interface IShare { - /** * @since 17.0.0 */ @@ -117,6 +97,11 @@ interface IShare { public const TYPE_DECK_USER = 13; /** + * @since 26.0.0 + */ + public const TYPE_SCIENCEMESH = 15; + + /** * @since 18.0.0 */ public const STATUS_PENDING = 0; @@ -207,7 +192,7 @@ interface IShare { * @since 9.0.0 * @throws NotFoundException */ - public function getNodeId(); + public function getNodeId(): int; /** * Set the type of node (file/folder) @@ -300,7 +285,7 @@ interface IShare { * See \OCP\Constants::PERMISSION_* * * @param int $permissions - * @return \OCP\Share\IShare The modified object + * @return IShare The modified object * @since 9.0.0 */ public function setPermissions($permissions); @@ -315,6 +300,31 @@ interface IShare { public function getPermissions(); /** + * Create share attributes object + * + * @since 25.0.0 + * @return IAttributes + */ + public function newAttributes(): IAttributes; + + /** + * Set share attributes + * + * @param ?IAttributes $attributes + * @since 25.0.0 + * @return IShare The modified object + */ + public function setAttributes(?IAttributes $attributes); + + /** + * Get share attributes + * + * @since 25.0.0 + * @return ?IAttributes + */ + public function getAttributes(): ?IAttributes; + + /** * Set the accepted status * See self::STATUS_* * @@ -354,21 +364,39 @@ interface IShare { /** * Set the expiration date * - * @param null|\DateTime $expireDate + * @param \DateTime|null $expireDate * @return \OCP\Share\IShare The modified object * @since 9.0.0 */ - public function setExpirationDate($expireDate); + public function setExpirationDate(?\DateTime $expireDate); /** * Get the expiration date * - * @return \DateTime + * @return \DateTime|null * @since 9.0.0 */ public function getExpirationDate(); /** + * Set overwrite flag for falsy expiry date values + * + * @param bool $noExpirationDate + * @return \OCP\Share\IShare The modified object + * @since 30.0.0 + */ + public function setNoExpirationDate(bool $noExpirationDate); + + + /** + * Get value of overwrite falsy expiry date flag + * + * @return bool + * @since 30.0.0 + */ + public function getNoExpirationDate(); + + /** * Is the share expired ? * * @return boolean @@ -443,7 +471,7 @@ interface IShare { * If this share is obtained via a shareprovider the password is * hashed. * - * @return string + * @return string|null * @since 9.0.0 */ public function getPassword(); @@ -502,6 +530,20 @@ interface IShare { public function getToken(); /** + * Set the parent of this share + * + * @since 9.0.0 + */ + public function setParent(int $parent): self; + + /** + * Get the parent of this share. + * + * @since 9.0.0 + */ + public function getParent(): ?int; + + /** * Set the target path of this share relative to the recipients user folder. * * @param string $target @@ -536,7 +578,7 @@ interface IShare { public function getShareTime(); /** - * Set if the recipient is informed by mail about the share. + * Set if the recipient should be informed by mail about the share. * * @param bool $mailSend * @return \OCP\Share\IShare The modified object @@ -545,7 +587,7 @@ interface IShare { public function setMailSend($mailSend); /** - * Get if the recipient informed by mail about the share. + * Get if the recipient should be informed by mail about the share. * * @return bool * @since 9.0.0 @@ -556,6 +598,7 @@ interface IShare { * Set the cache entry for the shared node * * @param ICacheEntry $entry + * @return void * @since 11.0.0 */ public function setNodeCacheEntry(ICacheEntry $entry); @@ -588,4 +631,27 @@ interface IShare { * @since 15.0.0 */ public function getHideDownload(): bool; + + /** + * Sets a flag that stores whether a reminder via email has been sent + * + * @return self The modified object + * @since 31.0.0 + */ + public function setReminderSent(bool $reminderSent): IShare; + + /** + * Gets a flag that stores whether a reminder via email has been sent + * + * @return bool + * @since 31.0.0 + */ + public function getReminderSent(): bool; + + /** + * Check if the current user can see this share files contents. + * This will check the download permissions as well as the global + * admin setting to allow viewing files without downloading. + */ + public function canSeeContent(): bool; } diff --git a/lib/public/Share/IShareHelper.php b/lib/public/Share/IShareHelper.php index 8bb08de07d6..152fc99a446 100644 --- a/lib/public/Share/IShareHelper.php +++ b/lib/public/Share/IShareHelper.php @@ -1,25 +1,8 @@ <?php + /** - * @copyright 2017, Roeland Jago Douma <roeland@famdouma.nl> - * - * @author Joas Schilling <coding@schilljs.com> - * @author Roeland Jago Douma <roeland@famdouma.nl> - * - * @license GNU AGPL version 3 or any later version - * - * This program is free software: you can redistribute it and/or modify - * it under the terms of the GNU Affero General Public License as - * published by the Free Software Foundation, either version 3 of the - * License, or (at your option) any later version. - * - * 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 - * along with this program. If not, see <http://www.gnu.org/licenses/>. - * + * SPDX-FileCopyrightText: 2017 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later */ namespace OCP\Share; @@ -31,7 +14,6 @@ use OCP\Files\Node; * @since 12 */ interface IShareHelper { - /** * @param Node $node * @return array [ users => [Mapping $uid => $pathForUser], remotes => [Mapping $cloudId => $pathToMountRoot]] diff --git a/lib/public/Share/IShareProvider.php b/lib/public/Share/IShareProvider.php index 6af513360fe..23187ca833e 100644 --- a/lib/public/Share/IShareProvider.php +++ b/lib/public/Share/IShareProvider.php @@ -1,27 +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 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; @@ -36,7 +18,6 @@ use OCP\Share\Exceptions\ShareNotFound; * @since 9.0.0 */ interface IShareProvider { - /** * Return the identifier of this provider. * @@ -64,16 +45,6 @@ interface IShareProvider { public function update(\OCP\Share\IShare $share); /** - * Accept a share. - * - * @param IShare $share - * @param string $recipient - * @return IShare The share object - * @since 17.0.0 - */ -// public function acceptShare(IShare $share, string $recipient): IShare; - - /** * Delete a share * * @param \OCP\Share\IShare $share @@ -123,10 +94,11 @@ interface IShareProvider { * @param string $userId * @param Folder $node * @param bool $reshares Also get the shares where $user is the owner instead of just the shares where $user is the initiator + * @param bool $shallow Whether the method should stop at the first level, or look into sub-folders. * @return \OCP\Share\IShare[][] * @since 11.0.0 */ - public function getSharesInFolder($userId, Folder $node, $reshares); + public function getSharesInFolder($userId, Folder $node, $reshares, $shallow = true); /** * Get all shares by the given user @@ -236,4 +208,12 @@ interface IShareProvider { * @since 18.0.0 */ public function getAllShares(): iterable; + + /** + * Get all children of this share + * + * @return IShare[] + * @since 9.0.0 + */ + public function getChildren(IShare $parent); } diff --git a/lib/public/Share/IShareProviderSupportsAccept.php b/lib/public/Share/IShareProviderSupportsAccept.php new file mode 100644 index 00000000000..c3a0c2d0218 --- /dev/null +++ b/lib/public/Share/IShareProviderSupportsAccept.php @@ -0,0 +1,27 @@ +<?php + +/** + * SPDX-FileCopyrightText: 2024 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later + */ +namespace OCP\Share; + +/** + * Interface IShareProviderSupportsAccept + * + * This interface allows to define IShareProvider that can handle the `acceptShare` method, + * which is available since Nextcloud 17. + * + * @since 30.0.0 + */ +interface IShareProviderSupportsAccept extends IShareProvider { + /** + * Accept a share. + * + * @param IShare $share + * @param string $recipient + * @return IShare The share object + * @since 30.0.0 + */ + public function acceptShare(IShare $share, string $recipient): IShare; +} diff --git a/lib/public/Share/IShareProviderSupportsAllSharesInFolder.php b/lib/public/Share/IShareProviderSupportsAllSharesInFolder.php new file mode 100644 index 00000000000..e27da7682ce --- /dev/null +++ b/lib/public/Share/IShareProviderSupportsAllSharesInFolder.php @@ -0,0 +1,24 @@ +<?php + +/** + * SPDX-FileCopyrightText: 2025 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later + */ +namespace OCP\Share; + +use OCP\Files\Folder; + +/** + * Allows defining a IShareProvider with support for the getAllSharesInFolder method. + * + * @since 32.0.0 + */ +interface IShareProviderSupportsAllSharesInFolder extends IShareProvider { + /** + * Get all shares in a folder. + * + * @return array<int, list<IShare>> + * @since 32.0.0 + */ + public function getAllSharesInFolder(Folder $node): array; +} diff --git a/lib/public/Share/IShareProviderWithNotification.php b/lib/public/Share/IShareProviderWithNotification.php new file mode 100644 index 00000000000..c2ba8118175 --- /dev/null +++ b/lib/public/Share/IShareProviderWithNotification.php @@ -0,0 +1,23 @@ +<?php + +/** + * SPDX-FileCopyrightText: 2024 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later + */ +namespace OCP\Share; + +/** + * Interface IShareProvider + * + * @since 30.0.0 + */ +interface IShareProviderWithNotification extends IShareProvider { + /** + * Send a mail notification to the recipient of a share + * @param IShare $share + * @return bool True if the mail was sent successfully + * @throws \Exception If the mail could not be sent + * @since 30.0.0 + */ + public function sendMailNotification(IShare $share): bool; +} |