1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
|
<?php
namespace OCP\Comments;
/**
* Interface ICommentsManager
*
* This class manages the access to comments
*
* @package OCP\Comments
* @since 9.0.0
*/
interface ICommentsManager {
/**
* returns a comment instance
*
* @param string $id the ID of the comment
* @return IComment
* @throws NotFoundException
* @since 9.0.0
*/
public function get($id);
/**
* returns the comment specified by the id and all it's child comments
*
* @param string $id
* @param int $limit max number of entries to return, 0 returns all
* @param int $offset the start entry
* @return []
* @since 9.0.0
*
* The return array looks like this
* [
* 'comment' => IComment, // root comment
* 'replies' =>
* [
* 0 =>
* [
* 'comment' => IComment,
* 'replies' =>
* [
* 0 =>
* [
* 'comment' => IComment,
* 'replies' => [ … ]
* ],
* …
* ]
* ]
* 1 =>
* [
* 'comment' => IComment,
* 'replies'=> [ … ]
* ],
* …
* ]
* ]
*/
public function getTree($id, $limit = 0, $offset = 0);
/**
* returns comments for a specific object (e.g. a file).
*
* The sort order is always newest to oldest.
*
* @param string $objectType the object type, e.g. 'files'
* @param string $objectId the id of the object
* @param int $limit optional, number of maximum comments to be returned. if
* not specified, all comments are returned.
* @param int $offset optional, starting point
* @param \DateTime $notOlderThan optional, timestamp of the oldest comments
* that may be returned
* @return IComment[]
* @throws NotFoundException in case the requested type or id is not present
* @since 9.0.0
*/
public function getForObject(
$objectType,
$objectId,
$limit = 0,
$offset = 0,
\DateTime $notOlderThan = null
);
/**
* @param $objectType string the object type, e.g. 'files'
* @param $objectId string the id of the object
* @return Int
* @throws NotFoundException in case the requested type or id is not present
* @since 9.0.0
*/
public function getNumberOfCommentsForObject($objectType, $objectId);
/**
* creates a new comment and returns it. At this point of time, it is not
* saved in the used data storage. Use save() after setting other fields
* of the comment (e.g. message or verb).
*
* @param string $actorType the actor type (e.g. 'user')
* @param string $actorId a user id
* @param string $objectType the object type the comment is attached to
* @param string $objectId the object id the comment is attached to
* @return IComment
* @since 9.0.0
*/
public function create($actorType, $actorId, $objectType, $objectId);
/**
* permanently deletes the comment specified by the ID
*
* When the comment has child comments, their parent ID will be changed to
* the parent ID of the item that is to be deleted.
*
* @param string $id
* @return bool
* @since 9.0.0
*/
public function delete($id);
/**
* saves the comment permanently and returns it
*
* if the supplied comment has an empty ID, a new entry comment will be
* saved and the instance updated with the new ID.
*
* Otherwise, an existing comment will be updated.
*
* Throws NotFoundException when a comment that is to be updated does not
* exist anymore at this point of time.
*
* @param IComment
* @return bool
* @throws NotFoundException
* @since 9.0.0
*/
public function save(&$comment);
/**
* removes references to specific actor (e.g. on user delete) of a comment.
* The comment itself must not get lost/deleted.
*
* @param string $actorType the actor type (e.g. 'user')
* @param string $actorId a user id
* @return boolean
* @since 9.0.0
*/
public function deleteReferencesOfActor($actorType, $actorId);
/**
* deletes all comments made of a specific object (e.g. on file delete)
*
* @param string $objectType the object type (e.g. 'file')
* @param string $objectId e.g. the file id
* @return boolean
* @since 9.0.0
*/
public function deleteCommentsAtObject($objectType, $objectId);
}
|
