You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
230 lines
5.8 KiB
230 lines
5.8 KiB
<?php |
|
/** |
|
* @copyright Copyright (c) 2016, ownCloud, Inc. |
|
* |
|
* @author Bernhard Reiter <ockham@raz.or.at> |
|
* @author Morris Jobke <hey@morrisjobke.de> |
|
* @author Thomas Tanghus <thomas@tanghus.net> |
|
* @author Vincent Petry <pvince81@owncloud.com> |
|
* |
|
* @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/> |
|
* |
|
*/ |
|
|
|
/** |
|
* Public interface of ownCloud for apps to use. |
|
* Tags interface |
|
* |
|
*/ |
|
|
|
// use OCP namespace for all classes that are considered public. |
|
// This means that they should be used by apps instead of the internal ownCloud classes |
|
namespace OCP; |
|
|
|
use OC\Tags; |
|
|
|
// FIXME: Where should I put this? Or should it be implemented as a Listener? |
|
\OC_Hook::connect('OC_User', 'post_deleteUser', Tags::class, 'post_deleteUser'); |
|
|
|
/** |
|
* Class for easily tagging objects by their id |
|
* |
|
* A tag can be e.g. 'Family', 'Work', 'Chore', 'Special Occation' or |
|
* anything else that is either parsed from a vobject or that the user chooses |
|
* to add. |
|
* Tag names are not case-sensitive, but will be saved with the case they |
|
* are entered in. If a user already has a tag 'family' for a type, and |
|
* tries to add a tag named 'Family' it will be silently ignored. |
|
* @since 6.0.0 |
|
*/ |
|
|
|
interface ITags { |
|
|
|
/** |
|
* Check if any tags are saved for this type and user. |
|
* |
|
* @return boolean |
|
* @since 6.0.0 |
|
*/ |
|
public function isEmpty(); |
|
|
|
/** |
|
* Returns an array mapping a given tag's properties to its values: |
|
* ['id' => 0, 'name' = 'Tag', 'owner' = 'User', 'type' => 'tagtype'] |
|
* |
|
* @param string $id The ID of the tag that is going to be mapped |
|
* @return array|false |
|
* @since 8.0.0 |
|
*/ |
|
public function getTag($id); |
|
|
|
/** |
|
* Get the tags for a specific user. |
|
* |
|
* This returns an array with id/name maps: |
|
* [ |
|
* ['id' => 0, 'name' = 'First tag'], |
|
* ['id' => 1, 'name' = 'Second tag'], |
|
* ] |
|
* |
|
* @return array |
|
* @since 6.0.0 |
|
*/ |
|
public function getTags(); |
|
|
|
/** |
|
* Get a list of tags for the given item ids. |
|
* |
|
* This returns an array with object id / tag names: |
|
* [ |
|
* 1 => array('First tag', 'Second tag'), |
|
* 2 => array('Second tag'), |
|
* 3 => array('Second tag', 'Third tag'), |
|
* ] |
|
* |
|
* @param array $objIds item ids |
|
* @return array|boolean with object id as key and an array |
|
* of tag names as value or false if an error occurred |
|
* @since 8.0.0 |
|
*/ |
|
public function getTagsForObjects(array $objIds); |
|
|
|
/** |
|
* Get a list of items tagged with $tag. |
|
* |
|
* Throws an exception if the tag could not be found. |
|
* |
|
* @param string|integer $tag Tag id or name. |
|
* @return array|false An array of object ids or false on error. |
|
* @since 6.0.0 |
|
*/ |
|
public function getIdsForTag($tag); |
|
|
|
/** |
|
* Checks whether a tag is already saved. |
|
* |
|
* @param string $name The name to check for. |
|
* @return bool |
|
* @since 6.0.0 |
|
*/ |
|
public function hasTag($name); |
|
|
|
/** |
|
* Checks whether a tag is saved for the given user, |
|
* disregarding the ones shared with him or her. |
|
* |
|
* @param string $name The tag name to check for. |
|
* @param string $user The user whose tags are to be checked. |
|
* @return bool |
|
* @since 8.0.0 |
|
*/ |
|
public function userHasTag($name, $user); |
|
|
|
/** |
|
* Add a new tag. |
|
* |
|
* @param string $name A string with a name of the tag |
|
* @return int|false the id of the added tag or false if it already exists. |
|
* @since 6.0.0 |
|
*/ |
|
public function add($name); |
|
|
|
/** |
|
* Rename tag. |
|
* |
|
* @param string|integer $from The name or ID of the existing tag |
|
* @param string $to The new name of the tag. |
|
* @return bool |
|
* @since 6.0.0 |
|
*/ |
|
public function rename($from, $to); |
|
|
|
/** |
|
* Add a list of new tags. |
|
* |
|
* @param string[] $names A string with a name or an array of strings containing |
|
* the name(s) of the to add. |
|
* @param bool $sync When true, save the tags |
|
* @param int|null $id int Optional object id to add to this|these tag(s) |
|
* @return bool Returns false on error. |
|
* @since 6.0.0 |
|
*/ |
|
public function addMultiple($names, $sync=false, $id = null); |
|
|
|
/** |
|
* Delete tag/object relations from the db |
|
* |
|
* @param array $ids The ids of the objects |
|
* @return boolean Returns false on error. |
|
* @since 6.0.0 |
|
*/ |
|
public function purgeObjects(array $ids); |
|
|
|
/** |
|
* Get favorites for an object type |
|
* |
|
* @return array|false An array of object ids. |
|
* @since 6.0.0 |
|
*/ |
|
public function getFavorites(); |
|
|
|
/** |
|
* Add an object to favorites |
|
* |
|
* @param int $objid The id of the object |
|
* @return boolean |
|
* @since 6.0.0 |
|
*/ |
|
public function addToFavorites($objid); |
|
|
|
/** |
|
* Remove an object from favorites |
|
* |
|
* @param int $objid The id of the object |
|
* @return boolean |
|
* @since 6.0.0 |
|
*/ |
|
public function removeFromFavorites($objid); |
|
|
|
/** |
|
* Creates a tag/object relation. |
|
* |
|
* @param int $objid The id of the object |
|
* @param string $tag The id or name of the tag |
|
* @return boolean Returns false on database error. |
|
* @since 6.0.0 |
|
*/ |
|
public function tagAs($objid, $tag); |
|
|
|
/** |
|
* Delete single tag/object relation from the db |
|
* |
|
* @param int $objid The id of the object |
|
* @param string $tag The id or name of the tag |
|
* @return boolean |
|
* @since 6.0.0 |
|
*/ |
|
public function unTag($objid, $tag); |
|
|
|
/** |
|
* Delete tags from the database |
|
* |
|
* @param string[]|integer[] $names An array of tags (names or IDs) to delete |
|
* @return bool Returns false on error |
|
* @since 6.0.0 |
|
*/ |
|
public function delete($names); |
|
|
|
}
|
|
|