1<?php
2/**
3 * @copyright Copyright (c) 2016, ownCloud, Inc.
4 *
5 * @author Bjoern Schiessle <bjoern@schiessle.org>
6 * @author Daniel Calviño Sánchez <danxuliu@gmail.com>
7 * @author Joas Schilling <coding@schilljs.com>
8 * @author Robin Appelman <robin@icewind.nl>
9 * @author Roeland Jago Douma <roeland@famdouma.nl>
10 *
11 * @license AGPL-3.0
12 *
13 * This code is free software: you can redistribute it and/or modify
14 * it under the terms of the GNU Affero General Public License, version 3,
15 * as published by the Free Software Foundation.
16 *
17 * This program is distributed in the hope that it will be useful,
18 * but WITHOUT ANY WARRANTY; without even the implied warranty of
19 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
20 * GNU Affero General Public License for more details.
21 *
22 * You should have received a copy of the GNU Affero General Public License, version 3,
23 * along with this program. If not, see <http://www.gnu.org/licenses/>
24 *
25 */
26namespace OCP\Share;
27
28use OCP\Files\Folder;
29use OCP\Files\Node;
30use OCP\Share\Exceptions\GenericShareException;
31use OCP\Share\Exceptions\ShareNotFound;
32
33/**
34 * Interface IShareProvider
35 *
36 * @since 9.0.0
37 */
38interface IShareProvider {
39
40	/**
41	 * Return the identifier of this provider.
42	 *
43	 * @return string Containing only [a-zA-Z0-9]
44	 * @since 9.0.0
45	 */
46	public function identifier();
47
48	/**
49	 * Create a share
50	 *
51	 * @param \OCP\Share\IShare $share
52	 * @return \OCP\Share\IShare The share object
53	 * @since 9.0.0
54	 */
55	public function create(\OCP\Share\IShare $share);
56
57	/**
58	 * Update a share
59	 *
60	 * @param \OCP\Share\IShare $share
61	 * @return \OCP\Share\IShare The share object
62	 * @since 9.0.0
63	 */
64	public function update(\OCP\Share\IShare $share);
65
66	/**
67	 * Accept a share.
68	 *
69	 * @param IShare $share
70	 * @param string $recipient
71	 * @return IShare The share object
72	 * @since 17.0.0
73	 */
74//	public function acceptShare(IShare $share, string $recipient): IShare;
75
76	/**
77	 * Delete a share
78	 *
79	 * @param \OCP\Share\IShare $share
80	 * @since 9.0.0
81	 */
82	public function delete(\OCP\Share\IShare $share);
83
84	/**
85	 * Unshare a file from self as recipient.
86	 * This may require special handling. If a user unshares a group
87	 * share from their self then the original group share should still exist.
88	 *
89	 * @param \OCP\Share\IShare $share
90	 * @param string $recipient UserId of the recipient
91	 * @since 9.0.0
92	 */
93	public function deleteFromSelf(\OCP\Share\IShare $share, $recipient);
94
95	/**
96	 * Restore a share for a given recipient. The implementation could be provider independant.
97	 *
98	 * @param IShare $share
99	 * @param string $recipient
100	 * @return IShare The restored share object
101	 *
102	 * @since 14.0.0
103	 * @throws GenericShareException In case the share could not be restored
104	 */
105	public function restore(IShare $share, string $recipient): IShare;
106
107	/**
108	 * Move a share as a recipient.
109	 * This is updating the share target. Thus the mount point of the recipient.
110	 * This may require special handling. If a user moves a group share
111	 * the target should only be changed for them.
112	 *
113	 * @param \OCP\Share\IShare $share
114	 * @param string $recipient userId of recipient
115	 * @return \OCP\Share\IShare
116	 * @since 9.0.0
117	 */
118	public function move(\OCP\Share\IShare $share, $recipient);
119
120	/**
121	 * Get all shares by the given user in a folder
122	 *
123	 * @param string $userId
124	 * @param Folder $node
125	 * @param bool $reshares Also get the shares where $user is the owner instead of just the shares where $user is the initiator
126	 * @return \OCP\Share\IShare[][]
127	 * @since 11.0.0
128	 */
129	public function getSharesInFolder($userId, Folder $node, $reshares);
130
131	/**
132	 * Get all shares by the given user
133	 *
134	 * @param string $userId
135	 * @param int $shareType
136	 * @param Node|null $node
137	 * @param bool $reshares Also get the shares where $user is the owner instead of just the shares where $user is the initiator
138	 * @param int $limit The maximum number of shares to be returned, -1 for all shares
139	 * @param int $offset
140	 * @return \OCP\Share\IShare[]
141	 * @since 9.0.0
142	 */
143	public function getSharesBy($userId, $shareType, $node, $reshares, $limit, $offset);
144
145	/**
146	 * Get share by id
147	 *
148	 * @param int $id
149	 * @param string|null $recipientId
150	 * @return \OCP\Share\IShare
151	 * @throws ShareNotFound
152	 * @since 9.0.0
153	 */
154	public function getShareById($id, $recipientId = null);
155
156	/**
157	 * Get shares for a given path
158	 *
159	 * @param Node $path
160	 * @return \OCP\Share\IShare[]
161	 * @since 9.0.0
162	 */
163	public function getSharesByPath(Node $path);
164
165	/**
166	 * Get shared with the given user
167	 *
168	 * @param string $userId get shares where this user is the recipient
169	 * @param int $shareType
170	 * @param Node|null $node
171	 * @param int $limit The max number of entries returned, -1 for all
172	 * @param int $offset
173	 * @return \OCP\Share\IShare[]
174	 * @since 9.0.0
175	 */
176	public function getSharedWith($userId, $shareType, $node, $limit, $offset);
177
178	/**
179	 * Get a share by token
180	 *
181	 * @param string $token
182	 * @return \OCP\Share\IShare
183	 * @throws ShareNotFound
184	 * @since 9.0.0
185	 */
186	public function getShareByToken($token);
187
188	/**
189	 * A user is deleted from the system
190	 * So clean up the relevant shares.
191	 *
192	 * @param string $uid
193	 * @param int $shareType
194	 * @since 9.1.0
195	 */
196	public function userDeleted($uid, $shareType);
197
198	/**
199	 * A group is deleted from the system.
200	 * We have to clean up all shares to this group.
201	 * Providers not handling group shares should just return
202	 *
203	 * @param string $gid
204	 * @since 9.1.0
205	 */
206	public function groupDeleted($gid);
207
208	/**
209	 * A user is deleted from a group
210	 * We have to clean up all the related user specific group shares
211	 * Providers not handling group shares should just return
212	 *
213	 * @param string $uid
214	 * @param string $gid
215	 * @since 9.1.0
216	 */
217	public function userDeletedFromGroup($uid, $gid);
218
219	/**
220	 * Get the access list to the array of provided nodes.
221	 *
222	 * @see IManager::getAccessList() for sample docs
223	 *
224	 * @param Node[] $nodes The list of nodes to get access for
225	 * @param bool $currentAccess If current access is required (like for removed shares that might get revived later)
226	 * @return array
227	 * @since 12
228	 */
229	public function getAccessList($nodes, $currentAccess);
230
231	/**
232	 * Get all the shares in this provider returned as iterable to reduce memory
233	 * overhead
234	 *
235	 * @return iterable
236	 * @since 18.0.0
237	 */
238	public function getAllShares(): iterable;
239}
240