1<?php
2/**
3 * @author Joas Schilling <coding@schilljs.com>
4 * @author Vincent Petry <pvince81@owncloud.com>
5 *
6 * @copyright Copyright (c) 2018, ownCloud GmbH
7 * @license AGPL-3.0
8 *
9 * This code is free software: you can redistribute it and/or modify
10 * it under the terms of the GNU Affero General Public License, version 3,
11 * as published by the Free Software Foundation.
12 *
13 * This program is distributed in the hope that it will be useful,
14 * but WITHOUT ANY WARRANTY; without even the implied warranty of
15 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16 * GNU Affero General Public License for more details.
17 *
18 * You should have received a copy of the GNU Affero General Public License, version 3,
19 * along with this program.  If not, see <http://www.gnu.org/licenses/>
20 *
21 */
22
23namespace OCP\SystemTag;
24
25use OCP\IUser;
26
27/**
28 * Public interface to access and manage system-wide tags.
29 *
30 * @since 9.0.0
31 */
32interface ISystemTagManager {
33
34	/**
35	 * Returns the tag objects matching the given tag ids.
36	 *
37	 * @param array|string $tagIds id or array of unique ids of the tag to retrieve
38	 *
39	 * @return \OCP\SystemTag\ISystemTag[] array of system tags with tag id as key
40	 *
41	 * @throws \InvalidArgumentException if at least one given tag ids is invalid (string instead of integer, etc.)
42	 * @throws \OCP\SystemTag\TagNotFoundException if at least one given tag ids did no exist
43	 * 			The message contains a json_encoded array of the ids that could not be found
44	 *
45	 * @since 9.0.0
46	 */
47	public function getTagsByIds($tagIds);
48
49	/**
50	 * Returns the tag object matching the given attributes.
51	 *
52	 * @param string $tagName tag name
53	 * @param bool $userVisible whether the tag is visible by users
54	 * @param null|bool $userAssignable whether the tag is assignable by users
55	 *
56	 * @return \OCP\SystemTag\ISystemTag system tag
57	 *
58	 * @throws \OCP\SystemTag\TagNotFoundException if tag does not exist
59	 *
60	 * @since 9.0.0
61	 */
62	public function getTag($tagName, $userVisible, $userAssignable, $userEditable = null);
63
64	/**
65	 * Creates the tag object using the given attributes.
66	 *
67	 * @param string $tagName tag name
68	 * @param bool $userVisible whether the tag is visible by users
69	 * @param bool $userAssignable whether the tag is assignable by users
70	 * @param null|bool $userEditable whether the tag is editable by users
71	 *
72	 * @return \OCP\SystemTag\ISystemTag system tag
73	 *
74	 * @throws \OCP\SystemTag\TagAlreadyExistsException if tag already exists
75	 *
76	 * @since 9.0.0
77	 */
78	public function createTag($tagName, $userVisible, $userAssignable, $userEditable = null);
79
80	/**
81	 * Returns all known tags, optionally filtered by visibility.
82	 *
83	 * @param bool|null $visibilityFilter filter by visibility if non-null
84	 * @param string $nameSearchPattern optional search pattern for the tag name
85	 *
86	 * @return \OCP\SystemTag\ISystemTag[] array of system tags or empty array if none found
87	 *
88	 * @since 9.0.0
89	 */
90	public function getAllTags($visibilityFilter = null, $nameSearchPattern = null);
91
92	/**
93	 * Updates the given tag
94	 *
95	 * @param string $tagId tag id
96	 * @param string $newName the new tag name
97	 * @param bool $userVisible whether the tag is visible by users
98	 * @param bool $userAssignable whether the tag is assignable by users
99	 * @param null|bool $userEditable whether the tag is assignable by users
100	 *
101	 * @throws \OCP\SystemTag\TagNotFoundException if tag with the given id does not exist
102	 * @throws \OCP\SystemTag\TagAlreadyExistsException if there is already another tag
103	 * with the same attributes
104	 *
105	 * @since 9.0.0
106	 */
107	public function updateTag($tagId, $newName, $userVisible, $userAssignable, $userEditable = null);
108
109	/**
110	 * Delete the given tags from the database and all their relationships.
111	 *
112	 * @param string|array $tagIds array of tag ids
113	 *
114	 * @throws \OCP\SystemTag\TagNotFoundException if at least one tag did not exist
115	 *
116	 * @since 9.0.0
117	 */
118	public function deleteTags($tagIds);
119
120	/**
121	 * Checks whether the given user is allowed to assign/unassign the tag with the
122	 * given id.
123	 *
124	 * @param ISystemTag $tag tag to check permission for
125	 * @param IUser $user user to check permission for
126	 *
127	 * @return true if the user is allowed to assign/unassign the tag, false otherwise
128	 *
129	 * @since 9.1.0
130	 */
131	public function canUserAssignTag(ISystemTag $tag, IUser $user);
132
133	/**
134	 * Checks whether the given user is allowed to see the tag with the given id.
135	 *
136	 * @param ISystemTag $tag tag to check permission for
137	 * @param IUser $user user to check permission for
138	 *
139	 * @return true if the user can see the tag, false otherwise
140	 *
141	 * @since 9.1.0
142	 */
143	public function canUserSeeTag(ISystemTag $tag, IUser $userId);
144
145	/**
146	 * Set groups that can assign a given tag.
147	 *
148	 * @param ISystemTag $tag tag for group assignment
149	 * @param string[] $groupIds group ids of groups that can assign/unassign the tag
150	 *
151	 * @since 9.1.0
152	 */
153	public function setTagGroups(ISystemTag $tag, $groupIds);
154
155	/**
156	 * Get groups that can assign a given tag.
157	 *
158	 * @param ISystemTag $tag tag for group assignment
159	 *
160	 * @return string[] group ids of groups that can assign/unassign the tag
161	 *
162	 * @since 9.1.0
163	 */
164	public function getTagGroups(ISystemTag $tag);
165
166	/**
167	 * Verify if users of group can use static tags
168	 *
169	 * @param ISystemTag $tag
170	 * @param IUser $user
171	 * @return bool, true if user of group can use staic tags, else false
172	 * @since 10.0.11
173	 */
174	public function canUserUseStaticTagInGroup(ISystemTag $tag, Iuser $user);
175}
176