2013-09-18 02:37:00 +04:00
|
|
|
<?php
|
|
|
|
/**
|
2016-07-21 18:07:57 +03:00
|
|
|
* @copyright Copyright (c) 2016, ownCloud, Inc.
|
|
|
|
*
|
2015-03-26 13:44:34 +03:00
|
|
|
* @author Bernhard Reiter <ockham@raz.or.at>
|
2020-03-31 11:49:10 +03:00
|
|
|
* @author Daniel Kesselberg <mail@danielkesselberg.de>
|
2015-03-26 13:44:34 +03:00
|
|
|
* @author Morris Jobke <hey@morrisjobke.de>
|
2019-12-03 21:57:53 +03:00
|
|
|
* @author Roeland Jago Douma <roeland@famdouma.nl>
|
2015-03-26 13:44:34 +03:00
|
|
|
* @author Thomas Tanghus <thomas@tanghus.net>
|
|
|
|
* @author Vincent Petry <pvince81@owncloud.com>
|
2013-11-03 16:51:39 +04:00
|
|
|
*
|
2015-03-26 13:44:34 +03:00
|
|
|
* @license AGPL-3.0
|
2013-11-03 16:51:39 +04:00
|
|
|
*
|
2015-03-26 13:44:34 +03:00
|
|
|
* 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.
|
2013-11-03 16:51:39 +04:00
|
|
|
*
|
2015-03-26 13:44:34 +03:00
|
|
|
* This program is distributed in the hope that it will be useful,
|
2013-11-03 16:51:39 +04:00
|
|
|
* but WITHOUT ANY WARRANTY; without even the implied warranty of
|
2015-03-26 13:44:34 +03:00
|
|
|
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
|
|
|
* GNU Affero General Public License for more details.
|
2013-11-03 16:51:39 +04:00
|
|
|
*
|
2015-03-26 13:44:34 +03:00
|
|
|
* 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/>
|
2013-11-03 16:51:39 +04:00
|
|
|
*
|
|
|
|
*/
|
2015-02-26 13:37:37 +03:00
|
|
|
|
|
|
|
/**
|
|
|
|
* Public interface of ownCloud for apps to use.
|
|
|
|
* Tags interface
|
|
|
|
*
|
|
|
|
*/
|
|
|
|
|
2013-11-03 16:38:25 +04:00
|
|
|
// 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
|
2019-11-22 22:52:10 +03:00
|
|
|
|
2013-09-18 02:37:00 +04:00
|
|
|
namespace OCP;
|
|
|
|
|
2018-01-26 01:16:13 +03:00
|
|
|
use OC\Tags;
|
|
|
|
|
2013-09-18 02:37:00 +04:00
|
|
|
// FIXME: Where should I put this? Or should it be implemented as a Listener?
|
2018-01-26 01:16:13 +03:00
|
|
|
\OC_Hook::connect('OC_User', 'post_deleteUser', Tags::class, 'post_deleteUser');
|
2013-09-18 02:37:00 +04:00
|
|
|
|
|
|
|
/**
|
|
|
|
* 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.
|
2015-04-16 18:00:08 +03:00
|
|
|
* @since 6.0.0
|
2013-09-18 02:37:00 +04:00
|
|
|
*/
|
|
|
|
|
|
|
|
interface ITags {
|
2020-02-11 23:40:01 +03:00
|
|
|
/**
|
|
|
|
* @since 19.0.0
|
|
|
|
*/
|
|
|
|
public const TAG_FAVORITE = '_$!<Favorite>!$_';
|
2013-09-18 02:37:00 +04:00
|
|
|
|
|
|
|
/**
|
2015-04-16 18:00:08 +03:00
|
|
|
* Check if any tags are saved for this type and user.
|
|
|
|
*
|
|
|
|
* @return boolean
|
|
|
|
* @since 6.0.0
|
|
|
|
*/
|
2013-09-18 02:37:00 +04:00
|
|
|
public function isEmpty();
|
|
|
|
|
2014-10-14 00:30:36 +04:00
|
|
|
/**
|
2015-04-16 18:00:08 +03:00
|
|
|
* 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
|
|
|
|
*/
|
2014-10-14 00:30:36 +04:00
|
|
|
public function getTag($id);
|
|
|
|
|
2013-09-18 02:37:00 +04:00
|
|
|
/**
|
2015-04-16 18:00:08 +03:00
|
|
|
* 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
|
|
|
|
*/
|
2013-09-19 13:27:13 +04:00
|
|
|
public function getTags();
|
2013-09-18 02:37:00 +04:00
|
|
|
|
|
|
|
/**
|
2014-11-24 23:51:45 +03:00
|
|
|
* 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
|
2015-04-16 18:00:08 +03:00
|
|
|
* @since 8.0.0
|
2014-11-24 23:51:45 +03:00
|
|
|
*/
|
|
|
|
public function getTagsForObjects(array $objIds);
|
|
|
|
|
|
|
|
/**
|
2015-04-16 18:00:08 +03:00
|
|
|
* 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
|
|
|
|
*/
|
2013-09-19 13:27:13 +04:00
|
|
|
public function getIdsForTag($tag);
|
2013-09-18 02:37:00 +04:00
|
|
|
|
|
|
|
/**
|
2015-04-16 18:00:08 +03:00
|
|
|
* Checks whether a tag is already saved.
|
|
|
|
*
|
|
|
|
* @param string $name The name to check for.
|
|
|
|
* @return bool
|
|
|
|
* @since 6.0.0
|
|
|
|
*/
|
2013-09-18 02:37:00 +04:00
|
|
|
public function hasTag($name);
|
|
|
|
|
2014-09-16 02:20:52 +04:00
|
|
|
/**
|
2015-04-16 18:00:08 +03:00
|
|
|
* 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
|
|
|
|
*/
|
2014-09-16 02:20:52 +04:00
|
|
|
public function userHasTag($name, $user);
|
|
|
|
|
2013-09-18 02:37:00 +04:00
|
|
|
/**
|
2015-04-16 18:00:08 +03:00
|
|
|
* 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
|
|
|
|
*/
|
2013-09-18 02:37:00 +04:00
|
|
|
public function add($name);
|
|
|
|
|
|
|
|
/**
|
2015-04-16 18:00:08 +03:00
|
|
|
* 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
|
|
|
|
*/
|
2013-09-18 02:37:00 +04:00
|
|
|
public function rename($from, $to);
|
|
|
|
|
|
|
|
/**
|
2015-04-16 18:00:08 +03:00
|
|
|
* 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
|
|
|
|
*/
|
2013-09-19 13:27:13 +04:00
|
|
|
public function addMultiple($names, $sync=false, $id = null);
|
2013-09-18 02:37:00 +04:00
|
|
|
|
|
|
|
/**
|
2015-04-16 18:00:08 +03:00
|
|
|
* 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
|
|
|
|
*/
|
2013-09-18 02:37:00 +04:00
|
|
|
public function purgeObjects(array $ids);
|
|
|
|
|
|
|
|
/**
|
2015-04-16 18:00:08 +03:00
|
|
|
* Get favorites for an object type
|
|
|
|
*
|
|
|
|
* @return array|false An array of object ids.
|
|
|
|
* @since 6.0.0
|
|
|
|
*/
|
2013-09-18 02:37:00 +04:00
|
|
|
public function getFavorites();
|
|
|
|
|
|
|
|
/**
|
2015-04-16 18:00:08 +03:00
|
|
|
* Add an object to favorites
|
|
|
|
*
|
|
|
|
* @param int $objid The id of the object
|
|
|
|
* @return boolean
|
|
|
|
* @since 6.0.0
|
|
|
|
*/
|
2013-09-18 02:37:00 +04:00
|
|
|
public function addToFavorites($objid);
|
|
|
|
|
|
|
|
/**
|
2015-04-16 18:00:08 +03:00
|
|
|
* Remove an object from favorites
|
|
|
|
*
|
|
|
|
* @param int $objid The id of the object
|
|
|
|
* @return boolean
|
|
|
|
* @since 6.0.0
|
|
|
|
*/
|
2013-09-18 02:37:00 +04:00
|
|
|
public function removeFromFavorites($objid);
|
|
|
|
|
|
|
|
/**
|
2015-04-16 18:00:08 +03:00
|
|
|
* 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
|
|
|
|
*/
|
2013-09-18 02:37:00 +04:00
|
|
|
public function tagAs($objid, $tag);
|
|
|
|
|
|
|
|
/**
|
2015-04-16 18:00:08 +03:00
|
|
|
* 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
|
|
|
|
*/
|
2013-09-18 02:37:00 +04:00
|
|
|
public function unTag($objid, $tag);
|
|
|
|
|
|
|
|
/**
|
2015-04-16 18:00:08 +03:00
|
|
|
* 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
|
|
|
|
*/
|
2013-09-18 02:37:00 +04:00
|
|
|
public function delete($names);
|
2014-09-09 01:38:46 +04:00
|
|
|
}
|