1<?php 2/** 3 * @author Bernhard Reiter <ockham@raz.or.at> 4 * @author Morris Jobke <hey@morrisjobke.de> 5 * @author Thomas Tanghus <thomas@tanghus.net> 6 * @author Vincent Petry <pvince81@owncloud.com> 7 * 8 * @copyright Copyright (c) 2018, ownCloud GmbH 9 * @license AGPL-3.0 10 * 11 * This code is free software: you can redistribute it and/or modify 12 * it under the terms of the GNU Affero General Public License, version 3, 13 * as published by the Free Software Foundation. 14 * 15 * This program is distributed in the hope that it will be useful, 16 * but WITHOUT ANY WARRANTY; without even the implied warranty of 17 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 18 * GNU Affero General Public License for more details. 19 * 20 * You should have received a copy of the GNU Affero General Public License, version 3, 21 * along with this program. If not, see <http://www.gnu.org/licenses/> 22 * 23 */ 24 25/** 26 * Public interface of ownCloud for apps to use. 27 * Tags interface 28 * 29 */ 30 31// use OCP namespace for all classes that are considered public. 32// This means that they should be used by apps instead of the internal ownCloud classes 33namespace OCP; 34 35// FIXME: Where should I put this? Or should it be implemented as a Listener? 36\OC_Hook::connect('OC_User', 'post_deleteUser', 'OC\Tags', 'post_deleteUser'); 37 38/** 39 * Class for easily tagging objects by their id 40 * 41 * A tag can be e.g. 'Family', 'Work', 'Chore', 'Special Occation' or 42 * anything else that is either parsed from a vobject or that the user chooses 43 * to add. 44 * Tag names are not case-sensitive, but will be saved with the case they 45 * are entered in. If a user already has a tag 'family' for a type, and 46 * tries to add a tag named 'Family' it will be silently ignored. 47 * @since 6.0.0 48 */ 49 50interface ITags { 51 52 /** 53 * Check if any tags are saved for this type and user. 54 * 55 * @return boolean 56 * @since 6.0.0 57 */ 58 public function isEmpty(); 59 60 /** 61 * Returns an array mapping a given tag's properties to its values: 62 * ['id' => 0, 'name' = 'Tag', 'owner' = 'User', 'type' => 'tagtype'] 63 * 64 * @param string $id The ID of the tag that is going to be mapped 65 * @return array|false 66 * @since 8.0.0 67 */ 68 public function getTag($id); 69 70 /** 71 * Get the tags for a specific user. 72 * 73 * This returns an array with id/name maps: 74 * [ 75 * ['id' => 0, 'name' = 'First tag'], 76 * ['id' => 1, 'name' = 'Second tag'], 77 * ] 78 * 79 * @return array 80 * @since 6.0.0 81 */ 82 public function getTags(); 83 84 /** 85 * Get a list of tags for the given item ids. 86 * 87 * This returns an array with object id / tag names: 88 * [ 89 * 1 => array('First tag', 'Second tag'), 90 * 2 => array('Second tag'), 91 * 3 => array('Second tag', 'Third tag'), 92 * ] 93 * 94 * @param array $objIds item ids 95 * @return array|boolean with object id as key and an array 96 * of tag names as value or false if an error occurred 97 * @since 8.0.0 98 */ 99 public function getTagsForObjects(array $objIds); 100 101 /** 102 * Get a list of items tagged with $tag. 103 * 104 * Throws an exception if the tag could not be found. 105 * 106 * @param string|integer $tag Tag id or name. 107 * @return array|false An array of object ids or false on error. 108 * @since 6.0.0 109 */ 110 public function getIdsForTag($tag); 111 112 /** 113 * Checks whether a tag is already saved. 114 * 115 * @param string $name The name to check for. 116 * @return bool 117 * @since 6.0.0 118 */ 119 public function hasTag($name); 120 121 /** 122 * Checks whether a tag is saved for the given user, 123 * disregarding the ones shared with him or her. 124 * 125 * @param string $name The tag name to check for. 126 * @param string $user The user whose tags are to be checked. 127 * @return bool 128 * @since 8.0.0 129 */ 130 public function userHasTag($name, $user); 131 132 /** 133 * Add a new tag. 134 * 135 * @param string $name A string with a name of the tag 136 * @return int|false the id of the added tag or false if it already exists. 137 * @since 6.0.0 138 */ 139 public function add($name); 140 141 /** 142 * Rename tag. 143 * 144 * @param string|integer $from The name or ID of the existing tag 145 * @param string $to The new name of the tag. 146 * @return bool 147 * @since 6.0.0 148 */ 149 public function rename($from, $to); 150 151 /** 152 * Add a list of new tags. 153 * 154 * @param string[] $names A string with a name or an array of strings containing 155 * the name(s) of the to add. 156 * @param bool $sync When true, save the tags 157 * @param int|null $id int Optional object id to add to this|these tag(s) 158 * @return bool Returns false on error. 159 * @since 6.0.0 160 */ 161 public function addMultiple($names, $sync=false, $id = null); 162 163 /** 164 * Delete tag/object relations from the db 165 * 166 * @param array $ids The ids of the objects 167 * @return boolean Returns false on error. 168 * @since 6.0.0 169 */ 170 public function purgeObjects(array $ids); 171 172 /** 173 * Get favorites for an object type 174 * 175 * @return array|false An array of object ids. 176 * @since 6.0.0 177 */ 178 public function getFavorites(); 179 180 /** 181 * Add an object to favorites 182 * 183 * @param int $objid The id of the object 184 * @return boolean 185 * @since 6.0.0 186 */ 187 public function addToFavorites($objid); 188 189 /** 190 * Remove an object from favorites 191 * 192 * @param int $objid The id of the object 193 * @return boolean 194 * @since 6.0.0 195 */ 196 public function removeFromFavorites($objid); 197 198 /** 199 * Creates a tag/object relation. 200 * 201 * @param int $objid The id of the object 202 * @param string $tag The id or name of the tag 203 * @return boolean Returns false on database error. 204 * @since 6.0.0 205 */ 206 public function tagAs($objid, $tag); 207 208 /** 209 * Delete single tag/object relation from the db 210 * 211 * @param int $objid The id of the object 212 * @param string $tag The id or name of the tag 213 * @return boolean 214 * @since 6.0.0 215 */ 216 public function unTag($objid, $tag); 217 218 /** 219 * Delete tags from the database 220 * 221 * @param string[]|integer[] $names An array of tags (names or IDs) to delete 222 * @return bool Returns false on error 223 * @since 6.0.0 224 */ 225 public function delete($names); 226} 227