← Back to branch summary

~pvigo/+junk/owncloud-14.04

« back to all changes in this revision

Viewing changes to share/owncloud/lib/public/itags.php

  • Committer: Pablo Vigo
  • Date: 2014-12-15 13:36:46 UTC
  • Revision ID: pvigo@xtec.cat-20141215133646-7d6it90e1dbsijc2
2

Show diffs side-by-side

added added

removed removed

Lines of Context:
share/owncloud/lib/public/itags.php
 
1
<?php
 
2
/**
 
3
 * ownCloud
 
4
 *
 
5
 * @author Thomas Tanghus
 
6
 * @copyright 2013 Thomas Tanghus <thomas@tanghus.net>
 
7
 *
 
8
 * This library is free software; you can redistribute it and/or
 
9
 * modify it under the terms of the GNU AFFERO GENERAL PUBLIC LICENSE
 
10
 * License as published by the Free Software Foundation; either
 
11
 * version 3 of the License, or any later version.
 
12
 *
 
13
 * This library 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
 
19
 * License along with this library.  If not, see <http://www.gnu.org/licenses/>.
 
20
 *
 
21
 */
 
22
 
 
23
/**
 
24
 * Public interface of ownCloud for apps to use.
 
25
 * Tags interface
 
26
 *
 
27
 */
 
28
 
 
29
// use OCP namespace for all classes that are considered public.
 
30
// This means that they should be used by apps instead of the internal ownCloud classes
 
31
namespace OCP;
 
32
 
 
33
// FIXME: Where should I put this? Or should it be implemented as a Listener?
 
34
\OC_Hook::connect('OC_User', 'post_deleteUser', 'OC\Tags', 'post_deleteUser');
 
35
 
 
36
/**
 
37
 * Class for easily tagging objects by their id
 
38
 *
 
39
 * A tag can be e.g. 'Family', 'Work', 'Chore', 'Special Occation' or
 
40
 * anything else that is either parsed from a vobject or that the user chooses
 
41
 * to add.
 
42
 * Tag names are not case-sensitive, but will be saved with the case they
 
43
 * are entered in. If a user already has a tag 'family' for a type, and
 
44
 * tries to add a tag named 'Family' it will be silently ignored.
 
45
 */
 
46
 
 
47
interface ITags {
 
48
 
 
49
        /**
 
50
        * Check if any tags are saved for this type and user.
 
51
        *
 
52
        * @return boolean.
 
53
        */
 
54
        public function isEmpty();
 
55
 
 
56
        /**
 
57
        * Get the tags for a specific user.
 
58
        *
 
59
        * This returns an array with id/name maps:
 
60
        * [
 
61
        *       ['id' => 0, 'name' = 'First tag'],
 
62
        *       ['id' => 1, 'name' = 'Second tag'],
 
63
        * ]
 
64
        *
 
65
        * @returns array
 
66
        */
 
67
        public function getTags();
 
68
 
 
69
        /**
 
70
        * Get the a list if items tagged with $tag.
 
71
        *
 
72
        * Throws an exception if the tag could not be found.
 
73
        *
 
74
        * @param string|integer $tag Tag id or name.
 
75
        * @return array An array of object ids or false on error.
 
76
        */
 
77
        public function getIdsForTag($tag);
 
78
 
 
79
        /**
 
80
        * Checks whether a tag is already saved.
 
81
        *
 
82
        * @param string $name The name to check for.
 
83
        * @return bool
 
84
        */
 
85
        public function hasTag($name);
 
86
 
 
87
        /**
 
88
        * Add a new tag.
 
89
        *
 
90
        * @param string $name A string with a name of the tag
 
91
        * @return int the id of the added tag or false if it already exists.
 
92
        */
 
93
        public function add($name);
 
94
 
 
95
        /**
 
96
        * Rename tag.
 
97
        *
 
98
        * @param string $from The name of the existing tag
 
99
        * @param string $to The new name of the tag.
 
100
        * @return bool
 
101
        */
 
102
        public function rename($from, $to);
 
103
 
 
104
        /**
 
105
        * Add a list of new tags.
 
106
        *
 
107
        * @param string[] $names A string with a name or an array of strings containing
 
108
        * the name(s) of the to add.
 
109
        * @param bool $sync When true, save the tags
 
110
        * @param int|null $id int Optional object id to add to this|these tag(s)
 
111
        * @return bool Returns false on error.
 
112
        */
 
113
        public function addMultiple($names, $sync=false, $id = null);
 
114
 
 
115
        /**
 
116
        * Delete tag/object relations from the db
 
117
        *
 
118
        * @param array $ids The ids of the objects
 
119
        * @return boolean Returns false on error.
 
120
        */
 
121
        public function purgeObjects(array $ids);
 
122
 
 
123
        /**
 
124
        * Get favorites for an object type
 
125
        *
 
126
        * @return array An array of object ids.
 
127
        */
 
128
        public function getFavorites();
 
129
 
 
130
        /**
 
131
        * Add an object to favorites
 
132
        *
 
133
        * @param int $objid The id of the object
 
134
        * @return boolean
 
135
        */
 
136
        public function addToFavorites($objid);
 
137
 
 
138
        /**
 
139
        * Remove an object from favorites
 
140
        *
 
141
        * @param int $objid The id of the object
 
142
        * @return boolean
 
143
        */
 
144
        public function removeFromFavorites($objid);
 
145
 
 
146
        /**
 
147
        * Creates a tag/object relation.
 
148
        *
 
149
        * @param int $objid The id of the object
 
150
        * @param int|string $tag The id or name of the tag
 
151
        * @return boolean Returns false on database error.
 
152
        */
 
153
        public function tagAs($objid, $tag);
 
154
 
 
155
        /**
 
156
        * Delete single tag/object relation from the db
 
157
        *
 
158
        * @param int $objid The id of the object
 
159
        * @param int|string $tag The id or name of the tag
 
160
        * @return boolean
 
161
        */
 
162
        public function unTag($objid, $tag);
 
163
 
 
164
        /**
 
165
        * Delete tags from the
 
166
        *
 
167
        * @param string[] $names An array of tags to delete
 
168
        * @return bool Returns false on error
 
169
        */
 
170
        public function delete($names);
 
171
 
 
172
}
 
 
b'\\ No newline at end of file'