diff options
Diffstat (limited to 'lib/public/Share')
| -rw-r--r-- | lib/public/Share/Exceptions/ShareTokenException.php | 16 | ||||
| -rw-r--r-- | lib/public/Share/IAttributes.php | 18 | ||||
| -rw-r--r-- | lib/public/Share/IManager.php | 40 | ||||
| -rw-r--r-- | lib/public/Share/IProviderFactory.php | 5 | ||||
| -rw-r--r-- | lib/public/Share/IShare.php | 45 | ||||
| -rw-r--r-- | lib/public/Share/IShareHelper.php | 1 | ||||
| -rw-r--r-- | lib/public/Share/IShareProvider.php | 18 | ||||
| -rw-r--r-- | lib/public/Share/IShareProviderSupportsAccept.php | 27 | ||||
| -rw-r--r-- | lib/public/Share/IShareProviderSupportsAllSharesInFolder.php | 24 | ||||
| -rw-r--r-- | lib/public/Share/IShareProviderWithNotification.php | 23 |
10 files changed, 186 insertions, 31 deletions
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 index af7277c39c0..9ddd8275dd6 100644 --- a/lib/public/Share/IAttributes.php +++ b/lib/public/Share/IAttributes.php @@ -1,4 +1,5 @@ <?php + /** * SPDX-FileCopyrightText: 2019 ownCloud GmbH * SPDX-License-Identifier: AGPL-3.0-only @@ -13,26 +14,26 @@ namespace OCP\Share; */ interface IAttributes { /** - * Sets an attribute enabled/disabled. If the key did not exist before it will be created. + * Sets an attribute. If the key did not exist before it will be created. * * @param string $scope scope * @param string $key key - * @param bool $enabled enabled + * @param bool|string|array|null $value value * @return IAttributes The modified object * @since 25.0.0 */ - public function setAttribute($scope, $key, $enabled); + public function setAttribute(string $scope, string $key, mixed $value): IAttributes; /** - * Returns if attribute is enabled/disabled for given scope id and key. + * 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|null + * @return bool|string|array|null * @since 25.0.0 */ - public function getAttribute($scope, $key); + public function getAttribute(string $scope, string $key): mixed; /** * Formats the IAttributes object to array with the following format: @@ -40,13 +41,14 @@ interface IAttributes { * 0 => [ * "scope" => <string>, * "key" => <string>, - * "enabled" => <bool> + * "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(); + public function toArray(): array; } diff --git a/lib/public/Share/IManager.php b/lib/public/Share/IManager.php index 063e776e68a..35915ad9d90 100644 --- a/lib/public/Share/IManager.php +++ b/lib/public/Share/IManager.php @@ -13,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. @@ -41,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. @@ -127,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. @@ -168,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 @@ -300,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 @@ -460,6 +464,22 @@ interface IManager { */ 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 * @@ -473,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 @@ -519,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 34656af2d8c..9107274c8c1 100644 --- a/lib/public/Share/IProviderFactory.php +++ b/lib/public/Share/IProviderFactory.php @@ -39,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/IShare.php b/lib/public/Share/IShare.php index 91eebd3afa9..a1bdb01fcd2 100644 --- a/lib/public/Share/IShare.php +++ b/lib/public/Share/IShare.php @@ -368,7 +368,7 @@ interface IShare { * @return \OCP\Share\IShare The modified object * @since 9.0.0 */ - public function setExpirationDate(\DateTime|null $expireDate); + public function setExpirationDate(?\DateTime $expireDate); /** * Get the expiration date @@ -379,7 +379,7 @@ interface IShare { public function getExpirationDate(); /** - * Set overwrite flag for falsy expiry date vavlues + * Set overwrite flag for falsy expiry date values * * @param bool $noExpirationDate * @return \OCP\Share\IShare The modified object @@ -530,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 @@ -564,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 @@ -573,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 @@ -617,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 c4a33e717f9..152fc99a446 100644 --- a/lib/public/Share/IShareHelper.php +++ b/lib/public/Share/IShareHelper.php @@ -1,4 +1,5 @@ <?php + /** * SPDX-FileCopyrightText: 2017 Nextcloud GmbH and Nextcloud contributors * SPDX-License-Identifier: AGPL-3.0-or-later diff --git a/lib/public/Share/IShareProvider.php b/lib/public/Share/IShareProvider.php index c51bad8f9ef..23187ca833e 100644 --- a/lib/public/Share/IShareProvider.php +++ b/lib/public/Share/IShareProvider.php @@ -45,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 @@ -218,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; +} |