2015-11-17 19:01:53 +03:00
|
|
|
<?php
|
2019-12-03 21:57:53 +03:00
|
|
|
|
2018-02-21 23:56:00 +03:00
|
|
|
declare(strict_types=1);
|
2019-12-03 21:57:53 +03:00
|
|
|
|
2015-11-17 19:01:53 +03:00
|
|
|
/**
|
2016-07-21 18:07:57 +03:00
|
|
|
* @copyright Copyright (c) 2016, ownCloud, Inc.
|
|
|
|
*
|
|
|
|
* @author Joas Schilling <coding@schilljs.com>
|
2019-12-03 21:57:53 +03:00
|
|
|
* @author Roeland Jago Douma <roeland@famdouma.nl>
|
2020-12-16 16:54:15 +03:00
|
|
|
* @author Vincent Petry <vincent@nextcloud.com>
|
2015-11-17 19:01:53 +03:00
|
|
|
*
|
|
|
|
* @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,
|
2019-12-03 21:57:53 +03:00
|
|
|
* along with this program. If not, see <http://www.gnu.org/licenses/>
|
2015-11-17 19:01:53 +03:00
|
|
|
*
|
|
|
|
*/
|
|
|
|
|
|
|
|
namespace OCP\SystemTag;
|
|
|
|
|
2016-04-27 16:24:28 +03:00
|
|
|
use OCP\IUser;
|
|
|
|
|
2015-11-17 19:01:53 +03:00
|
|
|
/**
|
|
|
|
* Public interface to access and manage system-wide tags.
|
|
|
|
*
|
|
|
|
* @since 9.0.0
|
|
|
|
*/
|
|
|
|
interface ISystemTagManager {
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Returns the tag objects matching the given tag ids.
|
|
|
|
*
|
2015-11-26 17:49:14 +03:00
|
|
|
* @param array|string $tagIds id or array of unique ids of the tag to retrieve
|
2015-11-17 19:01:53 +03:00
|
|
|
*
|
2018-02-21 23:56:00 +03:00
|
|
|
* @return ISystemTag[] array of system tags with tag id as key
|
2015-11-26 17:49:14 +03:00
|
|
|
*
|
2015-12-01 14:32:50 +03:00
|
|
|
* @throws \InvalidArgumentException if at least one given tag ids is invalid (string instead of integer, etc.)
|
2018-02-21 23:56:00 +03:00
|
|
|
* @throws TagNotFoundException if at least one given tag ids did no exist
|
2015-12-01 14:32:50 +03:00
|
|
|
* The message contains a json_encoded array of the ids that could not be found
|
2015-11-17 19:01:53 +03:00
|
|
|
*
|
|
|
|
* @since 9.0.0
|
|
|
|
*/
|
2018-02-21 23:56:00 +03:00
|
|
|
public function getTagsByIds($tagIds): array;
|
2015-11-17 19:01:53 +03:00
|
|
|
|
|
|
|
/**
|
|
|
|
* Returns the tag object matching the given attributes.
|
|
|
|
*
|
|
|
|
* @param string $tagName tag name
|
|
|
|
* @param bool $userVisible whether the tag is visible by users
|
|
|
|
* @param bool $userAssignable whether the tag is assignable by users
|
|
|
|
*
|
2018-02-21 23:56:00 +03:00
|
|
|
* @return ISystemTag system tag
|
2015-11-17 19:01:53 +03:00
|
|
|
*
|
2018-02-21 23:56:00 +03:00
|
|
|
* @throws TagNotFoundException if tag does not exist
|
2015-11-17 19:01:53 +03:00
|
|
|
*
|
|
|
|
* @since 9.0.0
|
|
|
|
*/
|
2018-02-21 23:56:00 +03:00
|
|
|
public function getTag(string $tagName, bool $userVisible, bool $userAssignable): ISystemTag;
|
2015-11-17 19:01:53 +03:00
|
|
|
|
|
|
|
/**
|
|
|
|
* Creates the tag object using the given attributes.
|
|
|
|
*
|
|
|
|
* @param string $tagName tag name
|
|
|
|
* @param bool $userVisible whether the tag is visible by users
|
|
|
|
* @param bool $userAssignable whether the tag is assignable by users
|
|
|
|
*
|
2018-02-21 23:56:00 +03:00
|
|
|
* @return ISystemTag system tag
|
2015-11-17 19:01:53 +03:00
|
|
|
*
|
2018-02-21 23:56:00 +03:00
|
|
|
* @throws TagAlreadyExistsException if tag already exists
|
2015-11-17 19:01:53 +03:00
|
|
|
*
|
|
|
|
* @since 9.0.0
|
|
|
|
*/
|
2018-02-21 23:56:00 +03:00
|
|
|
public function createTag(string $tagName, bool $userVisible, bool $userAssignable): ISystemTag;
|
2015-11-17 19:01:53 +03:00
|
|
|
|
|
|
|
/**
|
|
|
|
* Returns all known tags, optionally filtered by visibility.
|
|
|
|
*
|
2015-11-26 17:49:14 +03:00
|
|
|
* @param bool|null $visibilityFilter filter by visibility if non-null
|
2015-11-17 19:01:53 +03:00
|
|
|
* @param string $nameSearchPattern optional search pattern for the tag name
|
|
|
|
*
|
2018-02-21 23:56:00 +03:00
|
|
|
* @return ISystemTag[] array of system tags or empty array if none found
|
2015-11-17 19:01:53 +03:00
|
|
|
*
|
|
|
|
* @since 9.0.0
|
|
|
|
*/
|
2018-02-21 23:56:00 +03:00
|
|
|
public function getAllTags($visibilityFilter = null, $nameSearchPattern = null): array;
|
2015-11-17 19:01:53 +03:00
|
|
|
|
|
|
|
/**
|
|
|
|
* Updates the given tag
|
|
|
|
*
|
|
|
|
* @param string $tagId tag id
|
|
|
|
* @param string $newName the new tag name
|
|
|
|
* @param bool $userVisible whether the tag is visible by users
|
|
|
|
* @param bool $userAssignable whether the tag is assignable by users
|
|
|
|
*
|
2018-02-21 23:56:00 +03:00
|
|
|
* @throws TagNotFoundException if tag with the given id does not exist
|
|
|
|
* @throws TagAlreadyExistsException if there is already another tag
|
2015-11-17 19:01:53 +03:00
|
|
|
* with the same attributes
|
|
|
|
*
|
|
|
|
* @since 9.0.0
|
|
|
|
*/
|
2018-02-21 23:56:00 +03:00
|
|
|
public function updateTag(string $tagId, string $newName, bool $userVisible, bool $userAssignable);
|
2015-11-17 19:01:53 +03:00
|
|
|
|
|
|
|
/**
|
|
|
|
* Delete the given tags from the database and all their relationships.
|
|
|
|
*
|
|
|
|
* @param string|array $tagIds array of tag ids
|
|
|
|
*
|
2018-02-21 23:56:00 +03:00
|
|
|
* @throws TagNotFoundException if at least one tag did not exist
|
2015-11-17 19:01:53 +03:00
|
|
|
*
|
|
|
|
* @since 9.0.0
|
|
|
|
*/
|
|
|
|
public function deleteTags($tagIds);
|
|
|
|
|
2016-04-27 13:47:04 +03:00
|
|
|
/**
|
|
|
|
* Checks whether the given user is allowed to assign/unassign the tag with the
|
|
|
|
* given id.
|
|
|
|
*
|
2016-04-27 16:24:28 +03:00
|
|
|
* @param ISystemTag $tag tag to check permission for
|
|
|
|
* @param IUser $user user to check permission for
|
2016-04-27 13:47:04 +03:00
|
|
|
*
|
|
|
|
* @return true if the user is allowed to assign/unassign the tag, false otherwise
|
|
|
|
*
|
|
|
|
* @since 9.1.0
|
|
|
|
*/
|
2018-02-21 23:56:00 +03:00
|
|
|
public function canUserAssignTag(ISystemTag $tag, IUser $user): bool;
|
2016-04-27 13:47:04 +03:00
|
|
|
|
|
|
|
/**
|
|
|
|
* Checks whether the given user is allowed to see the tag with the given id.
|
|
|
|
*
|
2016-04-27 16:24:28 +03:00
|
|
|
* @param ISystemTag $tag tag to check permission for
|
|
|
|
* @param IUser $user user to check permission for
|
2016-04-27 13:47:04 +03:00
|
|
|
*
|
2016-05-18 12:31:41 +03:00
|
|
|
* @return true if the user can see the tag, false otherwise
|
2016-04-27 13:47:04 +03:00
|
|
|
*
|
|
|
|
* @since 9.1.0
|
|
|
|
*/
|
2018-02-21 23:56:00 +03:00
|
|
|
public function canUserSeeTag(ISystemTag $tag, IUser $user): bool;
|
2016-04-27 13:47:04 +03:00
|
|
|
|
2016-05-11 13:25:09 +03:00
|
|
|
/**
|
|
|
|
* Set groups that can assign a given tag.
|
|
|
|
*
|
|
|
|
* @param ISystemTag $tag tag for group assignment
|
|
|
|
* @param string[] $groupIds group ids of groups that can assign/unassign the tag
|
|
|
|
*
|
|
|
|
* @since 9.1.0
|
|
|
|
*/
|
2018-02-21 23:56:00 +03:00
|
|
|
public function setTagGroups(ISystemTag $tag, array $groupIds);
|
2016-05-11 13:25:09 +03:00
|
|
|
|
|
|
|
/**
|
|
|
|
* Get groups that can assign a given tag.
|
|
|
|
*
|
|
|
|
* @param ISystemTag $tag tag for group assignment
|
|
|
|
*
|
|
|
|
* @return string[] group ids of groups that can assign/unassign the tag
|
|
|
|
*
|
|
|
|
* @since 9.1.0
|
|
|
|
*/
|
2018-02-21 23:56:00 +03:00
|
|
|
public function getTagGroups(ISystemTag $tag): array;
|
2015-11-17 19:01:53 +03:00
|
|
|
}
|