1<?php
2/**
3 * @author Roeland Jago Douma <rullzer@owncloud.com>
4 *
5 * @copyright Copyright (c) 2018, ownCloud GmbH
6 * @license AGPL-3.0
7 *
8 * This code is free software: you can redistribute it and/or modify
9 * it under the terms of the GNU Affero General Public License, version 3,
10 * as published by the Free Software Foundation.
11 *
12 * This program is distributed in the hope that it will be useful,
13 * but WITHOUT ANY WARRANTY; without even the implied warranty of
14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15 * GNU Affero General Public License for more details.
16 *
17 * You should have received a copy of the GNU Affero General Public License, version 3,
18 * along with this program.  If not, see <http://www.gnu.org/licenses/>
19 *
20 */
21
22namespace OCP\Share;
23
24use OCP\Share\Exceptions\ShareNotFound;
25use OCP\Files\Node;
26
27/**
28 * Interface IShareProvider
29 *
30 * @package OCP\Share
31 * @since 9.0.0
32 */
33interface IShareProvider {
34	/**
35	 * The capabilities below refer mainly to storing capabilities allowed
36	 * by the implementing share provider. Validation or enforcement rules
37	 * (for passwords for example) aren't expected to be handled as capabilities
38	 * here because those rules will be checked at API level, not here.
39	 * If a share provider doesn't support any of these capabilities, it should
40	 * either store the value as null or don't store it, and return a null value
41	 * as value when the share is gotten.
42	 */
43	/**
44	 * Store when the share expires. An expired share needs to be automatically
45	 * deleted. If a share won't expire, a "null" value will be used
46	 */
47	public const CAPABILITY_STORE_EXPIRATION = 'shareExpiration';
48	/**
49	 * Store the (hashed) password to protect the share. A value of null means
50	 * that the share isn't protected by a password.
51	 */
52	public const CAPABILITY_STORE_PASSWORD = 'passwordProtected';
53
54	/**
55	 * Return the identifier of this provider.
56	 *
57	 * @return string Containing only [a-zA-Z0-9]
58	 * @since 9.0.0
59	 */
60	public function identifier();
61
62	/**
63	 * Create a share
64	 *
65	 * @param \OCP\Share\IShare $share
66	 * @return \OCP\Share\IShare The share object
67	 * @since 9.0.0
68	 */
69	public function create(\OCP\Share\IShare $share);
70
71	/**
72	 * Update a share
73	 *
74	 * @param \OCP\Share\IShare $share
75	 * @return \OCP\Share\IShare The share object
76	 * @since 9.0.0
77	 */
78	public function update(\OCP\Share\IShare $share);
79
80	/**
81	 * Delete a share
82	 *
83	 * @param \OCP\Share\IShare $share
84	 * @since 9.0.0
85	 */
86	public function delete(\OCP\Share\IShare $share);
87
88	/**
89	 * Unshare a file from self as recipient.
90	 * This may require special handling. If a user unshares a group
91	 * share from their self then the original group share should still exist.
92	 *
93	 * @param \OCP\Share\IShare $share
94	 * @param string $recipient UserId of the recipient
95	 * @since 9.0.0
96	 */
97	public function deleteFromSelf(\OCP\Share\IShare $share, $recipient);
98
99	/**
100	 * Move a share as a recipient.
101	 * This is updating the share target. Thus the mount point of the recipient.
102	 * This may require special handling. If a user moves a group share
103	 * the target should only be changed for them.
104	 *
105	 * @param \OCP\Share\IShare $share
106	 * @param string $recipient userId of recipient
107	 * @return \OCP\Share\IShare
108	 * @since 9.0.0
109	 * @deprecated 10.0.9 use updateForRecipient() instead
110	 */
111	public function move(\OCP\Share\IShare $share, $recipient);
112
113	/**
114	 * Get all shares by the given user
115	 *
116	 * @param string $userId
117	 * @param int $shareType
118	 * @param Node|null $node
119	 * @param bool $reshares Also get the shares where $user is the owner instead of just the shares where $user is the initiator
120	 * @param int $limit The maximum number of shares to be returned, -1 for all shares
121	 * @param int $offset
122	 * @return \OCP\Share\IShare[]
123	 * @since 9.0.0
124	 */
125	public function getSharesBy($userId, $shareType, $node, $reshares, $limit, $offset);
126
127	/**
128	 * Get all shares by the given user for specified shareTypes array (ref. \OC\Share\Constants)
129	 *
130	 * @param string $userId
131	 * @param int[] $shareTypes
132	 * @param Node[] $nodeIDs
133	 * @param bool $reshares - Also get the shares where $user is the owner instead of just the shares where $user is the initiator
134	 * @return \OCP\Share\IShare[]
135	 * @since 10.0.0
136	 */
137	public function getAllSharesBy($userId, $shareTypes, $nodeIDs, $reshares);
138
139	/**
140	 * Get share by id
141	 *
142	 * @param string $id
143	 * @param string|null $recipientId
144	 * @return \OCP\Share\IShare
145	 * @throws ShareNotFound
146	 * @throws ProviderException
147	 * @since 9.0.0
148	 */
149	public function getShareById($id, $recipientId = null);
150
151	/**
152	 * Get shares for a given path
153	 *
154	 * @param Node $path
155	 * @return \OCP\Share\IShare[]
156	 * @since 9.0.0
157	 */
158	public function getSharesByPath(Node $path);
159
160	/**
161	 * Get shared with the given user for shares of all supported share types for this share provider,
162	 * with file_source predicate specified ($node is Node) or
163	 * without ($node is null and scan over file_source is performed).
164	 *
165	 * @param string $userId get shares where this user is the recipient
166	 * @param Node|null $node
167	 * @return \OCP\Share\IShare[]
168	 * @since 10.0.0
169	 */
170	public function getAllSharedWith($userId, $node);
171
172	/**
173	 * Get shared with the given user specifying share type predicate for this specific share provider
174	 *
175	 * @param string $userId get shares where this user is the recipient
176	 * @param int $shareType
177	 * @param Node|null $node
178	 * @param int $limit The max number of entries returned, -1 for all
179	 * @param int $offset
180	 * @return \OCP\Share\IShare[]
181	 * @since 9.0.0
182	 */
183	public function getSharedWith($userId, $shareType, $node, $limit, $offset);
184
185	/**
186	 * Get a share by token
187	 *
188	 * @param string $token
189	 * @return \OCP\Share\IShare
190	 * @throws ShareNotFound
191	 * @since 9.0.0
192	 */
193	public function getShareByToken($token);
194
195	/**
196	 * Get the shares which are associated with an invalid or missing fileid.
197	 * This means that the share isn't valid any longer because the source file
198	 * has been deleted.
199	 *
200	 * @param int $limit limit the number of results, -1 to get all results without limit
201	 * @return \OCP\Share\IShare[]
202	 * @since 10.7.0
203	 */
204	public function getSharesWithInvalidFileid(int $limit);
205
206	/**
207	 * A user is deleted from the system
208	 * So clean up the relevant shares.
209	 *
210	 * @param string $uid
211	 * @param int $shareType
212	 * @since 9.1.0
213	 */
214	public function userDeleted($uid, $shareType);
215
216	/**
217	 * A group is deleted from the system.
218	 * We have to clean up all shares to this group.
219	 * Providers not handling group shares should just return
220	 *
221	 * @param string $gid
222	 * @since 9.1.0
223	 */
224	public function groupDeleted($gid);
225
226	/**
227	 * A user is deleted from a group
228	 * We have to clean up all the related user specific group shares
229	 * Providers not handling group shares should just return
230	 *
231	 * @param string $uid
232	 * @param string $gid
233	 * @since 9.1.0
234	 */
235	public function userDeletedFromGroup($uid, $gid);
236
237	/**
238	 * Updates the share entry of the given recipient
239	 *
240	 * For group shares, only the state for the given recipient is changed,
241	 * not for the whole group share.
242	 *
243	 * @param \OCP\Share\IShare $share
244	 * @param string $recipient userId of recipient
245	 * @param int $state state to set
246	 * @return \OCP\Share\IShare
247	 * @since 10.0.9
248	 */
249	public function updateForRecipient(\OCP\Share\IShare $share, $recipient);
250
251	/**
252	 * Get the share provider's capabilities. It will return a map with the supported
253	 * share type with the list of capabilities for that share type:
254	 * [
255	 *   \OCP\Share::CONVERT_SHARE_TYPE_TO_STRING[\OCP\Share::SHARE_TYPE_USER] => [
256	 *     IShareProvider::CAPABILITY_STORE_EXPIRATION
257	 *   ],
258	 *   \OCP\Share::CONVERT_SHARE_TYPE_TO_STRING[\OCP\Share::SHARE_TYPE_LINK] => [
259	 *     IShareProvider::CAPABILITY_STORE_EXPIRATION,
260	 *     IShareProvider::CAPABILITY_STORE_PASSWORD
261	 *   ],
262	 *   \OCP\Share::CONVERT_SHARE_TYPE_TO_STRING[\OCP\Share::SHARE_TYPE_GROUP] => []
263	 * ]
264	 * Supported share types by this provider should have the corresponding entry even if
265	 * it doesn't support extra capabilities
266	 *
267	 * @return array
268	 * @since 10.3.2
269	 */
270	public function getProviderCapabilities();
271}
272