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\Files\File;
25use OCP\Files\Folder;
26use OCP\Files\Node;
27use OCP\Files\NotFoundException;
28use OCP\Share\Exceptions\IllegalIDChangeException;
29
30/**
31 * Interface IShare
32 *
33 * @package OCP\Share
34 * @since 9.0.0
35 */
36interface IShare {
37
38	/**
39	 * Set the internal id of the share
40	 * It is only allowed to set the internal id of a share once.
41	 * Attempts to override the internal id will result in an IllegalIDChangeException
42	 *
43	 * @param string $id
44	 * @return \OCP\Share\IShare
45	 * @throws IllegalIDChangeException
46	 * @throws \InvalidArgumentException
47	 * @since 9.1.0
48	 */
49	public function setId($id);
50
51	/**
52	 * Get the internal id of the share.
53	 *
54	 * @return string
55	 * @since 9.0.0
56	 */
57	public function getId();
58
59	/**
60	 * Get the full share id. This is the <providerid>:<internalid>.
61	 * The full id is unique in the system.
62	 *
63	 * @return string
64	 * @since 9.0.0
65	 * @throws \UnexpectedValueException If the fullId could not be constructed
66	 */
67	public function getFullId();
68
69	/**
70	 * Set the provider id of the share
71	 * It is only allowed to set the provider id of a share once.
72	 * Attempts to override the provider id will result in an IllegalIDChangeException
73	 *
74	 * @param string $id
75	 * @return \OCP\Share\IShare
76	 * @throws IllegalIDChangeException
77	 * @throws \InvalidArgumentException
78	 * @since 9.1.0
79	 */
80	public function setProviderId($id);
81
82	/**
83	 * Set the node of the file/folder that is shared
84	 *
85	 * @param Node $node
86	 * @return \OCP\Share\IShare The modified object
87	 * @since 9.0.0
88	 */
89	public function setNode(Node $node);
90
91	/**
92	 * Get the node of the file/folder that is shared
93	 *
94	 * @return File|Folder
95	 * @since 9.0.0
96	 * @throws NotFoundException
97	 */
98	public function getNode();
99
100	/**
101	 * Set file id for lazy evaluation of the node
102	 * @param int $fileId
103	 * @return \OCP\Share\IShare The modified object
104	 * @since 9.0.0
105	 */
106	public function setNodeId($fileId);
107
108	/**
109	 * Get the fileid of the node of this share
110	 * @return int
111	 * @since 9.0.0
112	 * @throws NotFoundException
113	 */
114	public function getNodeId();
115
116	/**
117	 * Set the type of node (file/folder)
118	 *
119	 * @param string $type
120	 * @return \OCP\Share\IShare The modified object
121	 * @since 9.0.0
122	 */
123	public function setNodeType($type);
124
125	/**
126	 * Get the type of node (file/folder)
127	 *
128	 * @return string
129	 * @since 9.0.0
130	 * @throws NotFoundException
131	 */
132	public function getNodeType();
133
134	/**
135	 * Set the shareType
136	 *
137	 * @param int $shareType
138	 * @return \OCP\Share\IShare The modified object
139	 * @since 9.0.0
140	 */
141	public function setShareType($shareType);
142
143	/**
144	 * Get the shareType
145	 *
146	 * @return int
147	 * @since 9.0.0
148	 */
149	public function getShareType();
150
151	/**
152	 * Set the receiver of this share.
153	 *
154	 * @param string $sharedWith
155	 * @return \OCP\Share\IShare The modified object
156	 * @since 9.0.0
157	 */
158	public function setSharedWith($sharedWith);
159
160	/**
161	 * Get the receiver of this share.
162	 *
163	 * @return string
164	 * @since 9.0.0
165	 */
166	public function getSharedWith();
167
168	/**
169	 * Set the permissions.
170	 * See \OCP\Constants::PERMISSION_*
171	 *
172	 * @param int $permissions
173	 * @return IShare The modified object
174	 * @since 9.0.0
175	 */
176	public function setPermissions($permissions);
177
178	/**
179	 * Get the share permissions
180	 * See \OCP\Constants::PERMISSION_*
181	 *
182	 * @return int
183	 * @since 9.0.0
184	 */
185	public function getPermissions();
186
187	/**
188	 * Create share attributes object
189	 *
190	 * @since 10.2.0
191	 * @return IAttributes;
192	 */
193	public function newAttributes();
194
195	/**
196	 * Set share attributes
197	 *
198	 * @param IAttributes $attributes
199	 * @since 10.2.0
200	 * @return IShare The modified object
201	 */
202	public function setAttributes(IAttributes $attributes);
203
204	/**
205	 * Get share attributes
206	 *
207	 * @since 10.2.0
208	 * @return IAttributes
209	 */
210	public function getAttributes();
211
212	/**
213	 * Set the expiration date
214	 *
215	 * @param \DateTime $expireDate
216	 * @return \OCP\Share\IShare The modified object
217	 * @since 9.0.0
218	 */
219	public function setExpirationDate($expireDate);
220
221	/**
222	 * Get the expiration date or null if no expiration date has been set
223	 *
224	 * @return \DateTime|null
225	 * @since 9.0.0
226	 */
227	public function getExpirationDate();
228
229	/**
230	 * Set the sharer of the path.
231	 *
232	 * @param string $sharedBy
233	 * @return \OCP\Share\IShare The modified object
234	 * @since 9.0.0
235	 */
236	public function setSharedBy($sharedBy);
237
238	/**
239	 * Get share sharer
240	 *
241	 * @return string
242	 * @since 9.0.0
243	 */
244	public function getSharedBy();
245
246	/**
247	 * Set the original share owner (who owns the path that is shared)
248	 *
249	 * @param string $shareOwner
250	 * @return \OCP\Share\IShare The modified object
251	 * @since 9.0.0
252	 */
253	public function setShareOwner($shareOwner);
254
255	/**
256	 * Get the original share owner (who owns the path that is shared)
257	 *
258	 * @return string
259	 * @since 9.0.0
260	 */
261	public function getShareOwner();
262
263	/**
264	 * Set the password for this share.
265	 * When the share is passed to the share manager to be created
266	 * or updated the password will be hashed.
267	 *
268	 * @param string $password
269	 * @return \OCP\Share\IShare The modified object
270	 * @since 9.0.0
271	 */
272	public function setPassword($password);
273
274	/**
275	 * Get the password of this share or null if no password has been set.
276	 * If this share is obtained via a shareprovider the password is
277	 * hashed.
278	 *
279	 * @return string|null
280	 * @since 9.0.0
281	 */
282	public function getPassword();
283
284	/**
285	 * Set the public link token.
286	 *
287	 * @param string $token
288	 * @return \OCP\Share\IShare The modified object
289	 * @since 9.0.0
290	 */
291	public function setToken($token);
292
293	/**
294	 * Get the public link token.
295	 *
296	 * @return string
297	 * @since 9.0.0
298	 */
299	public function getToken();
300
301	/**
302	 * Set the target path of this share relative to the recipients user folder.
303	 *
304	 * @param string $target
305	 * @return \OCP\Share\IShare The modified object
306	 * @since 9.0.0
307	 */
308	public function setTarget($target);
309
310	/**
311	 * Get the target path of this share relative to the recipients user folder.
312	 *
313	 * @return string
314	 * @since 9.0.0
315	 */
316	public function getTarget();
317
318	/**
319	 * Set the time this share was created
320	 *
321	 * @param \DateTime $shareTime
322	 * @return \OCP\Share\IShare The modified object
323	 * @since 9.0.0
324	 */
325	public function setShareTime(\DateTime $shareTime);
326
327	/**
328	 * Get the timestamp this share was created
329	 *
330	 * @return \DateTime
331	 * @since 9.0.0
332	 */
333	public function getShareTime();
334
335	/**
336	 * Set if the recipient is informed by mail about the share.
337	 *
338	 * @param bool $mailSend
339	 * @return \OCP\Share\IShare The modified object
340	 * @since 9.0.0
341	 */
342	public function setMailSend($mailSend);
343
344	/**
345	 * Get if the recipient informed by mail about the share.
346	 *
347	 * @return bool
348	 * @since 9.0.0
349	 */
350	public function getMailSend();
351
352	/**
353	 * Set a user-defined name for this share
354	 *
355	 * @param string $name
356	 * @since 10.0.0
357	 */
358	public function setName($name);
359
360	/**
361	 * Get user-defined name for this share
362	 *
363	 * @return string $name
364	 * @since 10.0.0
365	 */
366	public function getName();
367
368	/**
369	 * Set share accepted state
370	 *
371	 * @param int $state
372	 * @since 10.0.9
373	 */
374	public function setState($state);
375
376	/**
377	 * Get share accepted state
378	 *
379	 * @return int state
380	 * @since 10.0.9
381	 */
382	public function getState();
383
384	/**
385	 * @return bool shouldHashPassword
386	 * @since 10.0.10
387	 */
388	public function getShouldHashPassword();
389
390	/**
391	 * @param $status
392	 * @return void
393	 * @since 10.0.10
394	 */
395	public function setShouldHashPassword($status);
396}
397