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 John Molakvoæ <skjnldsv@protonmail.com>
9 * @author Julius Härtl <jus@bitgrid.net>
10 * @author Maxence Lange <maxence@nextcloud.com>
11 * @author Robin Appelman <robin@icewind.nl>
12 * @author Roeland Jago Douma <roeland@famdouma.nl>
13 *
14 * @license AGPL-3.0
15 *
16 * This code is free software: you can redistribute it and/or modify
17 * it under the terms of the GNU Affero General Public License, version 3,
18 * as published by the Free Software Foundation.
19 *
20 * This program is distributed in the hope that it will be useful,
21 * but WITHOUT ANY WARRANTY; without even the implied warranty of
22 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
23 * GNU Affero General Public License for more details.
24 *
25 * You should have received a copy of the GNU Affero General Public License, version 3,
26 * along with this program. If not, see <http://www.gnu.org/licenses/>
27 *
28 */
29namespace OCP\Share;
30
31use OCP\Files\Cache\ICacheEntry;
32use OCP\Files\File;
33use OCP\Files\Folder;
34use OCP\Files\Node;
35use OCP\Files\NotFoundException;
36use OCP\Share\Exceptions\IllegalIDChangeException;
37
38/**
39 * Interface IShare
40 *
41 * @since 9.0.0
42 */
43interface IShare {
44
45	/**
46	 * @since 17.0.0
47	 */
48	public const TYPE_USER = 0;
49
50	/**
51	 * @since 17.0.0
52	 */
53	public const TYPE_GROUP = 1;
54
55	/**
56	 * @internal
57	 * @since 18.0.0
58	 */
59	public const TYPE_USERGROUP = 2;
60
61	/**
62	 * @since 17.0.0
63	 */
64	public const TYPE_LINK = 3;
65
66	/**
67	 * @since 17.0.0
68	 */
69	public const TYPE_EMAIL = 4;
70
71	/**
72	 * ToDo Check if it is still in use otherwise remove it
73	 * @since 17.0.0
74	 */
75	// public const TYPE_CONTACT = 5;
76
77	/**
78	 * @since 17.0.0
79	 */
80	public const TYPE_REMOTE = 6;
81
82	/**
83	 * @since 17.0.0
84	 */
85	public const TYPE_CIRCLE = 7;
86
87	/**
88	 * @since 17.0.0
89	 */
90	public const TYPE_GUEST = 8;
91
92	/**
93	 * @since 17.0.0
94	 */
95	public const TYPE_REMOTE_GROUP = 9;
96
97	/**
98	 * @since 17.0.0
99	 */
100	public const TYPE_ROOM = 10;
101
102	/**
103	 * Internal type used by RoomShareProvider
104	 * @since 17.0.0
105	 */
106	// const TYPE_USERROOM = 11;
107
108	/**
109	 * @since 21.0.0
110	 */
111	public const TYPE_DECK = 12;
112
113	/**
114	 * @internal
115	 * @since 21.0.0
116	 */
117	public const TYPE_DECK_USER = 13;
118
119	/**
120	 * @since 18.0.0
121	 */
122	public const STATUS_PENDING = 0;
123
124	/**
125	 * @since 18.0.0
126	 */
127	public const STATUS_ACCEPTED = 1;
128
129	/**
130	 * @since 18.0.0
131	 */
132	public const STATUS_REJECTED = 2;
133
134	/**
135	 * Set the internal id of the share
136	 * It is only allowed to set the internal id of a share once.
137	 * Attempts to override the internal id will result in an IllegalIDChangeException
138	 *
139	 * @param string $id
140	 * @return \OCP\Share\IShare
141	 * @throws IllegalIDChangeException
142	 * @throws \InvalidArgumentException
143	 * @since 9.1.0
144	 */
145	public function setId($id);
146
147	/**
148	 * Get the internal id of the share.
149	 *
150	 * @return string
151	 * @since 9.0.0
152	 */
153	public function getId();
154
155	/**
156	 * Get the full share id. This is the <providerid>:<internalid>.
157	 * The full id is unique in the system.
158	 *
159	 * @return string
160	 * @since 9.0.0
161	 * @throws \UnexpectedValueException If the fullId could not be constructed
162	 */
163	public function getFullId();
164
165	/**
166	 * Set the provider id of the share
167	 * It is only allowed to set the provider id of a share once.
168	 * Attempts to override the provider id will result in an IllegalIDChangeException
169	 *
170	 * @param string $id
171	 * @return \OCP\Share\IShare
172	 * @throws IllegalIDChangeException
173	 * @throws \InvalidArgumentException
174	 * @since 9.1.0
175	 */
176	public function setProviderId($id);
177
178	/**
179	 * Set the node of the file/folder that is shared
180	 *
181	 * @param Node $node
182	 * @return \OCP\Share\IShare The modified object
183	 * @since 9.0.0
184	 */
185	public function setNode(Node $node);
186
187	/**
188	 * Get the node of the file/folder that is shared
189	 *
190	 * @return File|Folder
191	 * @since 9.0.0
192	 * @throws NotFoundException
193	 */
194	public function getNode();
195
196	/**
197	 * Set file id for lazy evaluation of the node
198	 * @param int $fileId
199	 * @return \OCP\Share\IShare The modified object
200	 * @since 9.0.0
201	 */
202	public function setNodeId($fileId);
203
204	/**
205	 * Get the fileid of the node of this share
206	 * @return int
207	 * @since 9.0.0
208	 * @throws NotFoundException
209	 */
210	public function getNodeId();
211
212	/**
213	 * Set the type of node (file/folder)
214	 *
215	 * @param string $type
216	 * @return \OCP\Share\IShare The modified object
217	 * @since 9.0.0
218	 */
219	public function setNodeType($type);
220
221	/**
222	 * Get the type of node (file/folder)
223	 *
224	 * @return string
225	 * @since 9.0.0
226	 * @throws NotFoundException
227	 */
228	public function getNodeType();
229
230	/**
231	 * Set the shareType
232	 *
233	 * @param int $shareType
234	 * @return \OCP\Share\IShare The modified object
235	 * @since 9.0.0
236	 */
237	public function setShareType($shareType);
238
239	/**
240	 * Get the shareType
241	 *
242	 * @return int
243	 * @since 9.0.0
244	 */
245	public function getShareType();
246
247	/**
248	 * Set the receiver of this share.
249	 *
250	 * @param string $sharedWith
251	 * @return \OCP\Share\IShare The modified object
252	 * @since 9.0.0
253	 */
254	public function setSharedWith($sharedWith);
255
256	/**
257	 * Get the receiver of this share.
258	 *
259	 * @return string
260	 * @since 9.0.0
261	 */
262	public function getSharedWith();
263
264	/**
265	 * Set the display name of the receiver of this share.
266	 *
267	 * @param string $displayName
268	 * @return \OCP\Share\IShare The modified object
269	 * @since 14.0.0
270	 */
271	public function setSharedWithDisplayName($displayName);
272
273	/**
274	 * Get the display name of the receiver of this share.
275	 *
276	 * @return string
277	 * @since 14.0.0
278	 */
279	public function getSharedWithDisplayName();
280
281	/**
282	 * Set the avatar of the receiver of this share.
283	 *
284	 * @param string $src
285	 * @return \OCP\Share\IShare The modified object
286	 * @since 14.0.0
287	 */
288	public function setSharedWithAvatar($src);
289
290	/**
291	 * Get the avatar of the receiver of this share.
292	 *
293	 * @return string
294	 * @since 14.0.0
295	 */
296	public function getSharedWithAvatar();
297
298	/**
299	 * Set the permissions.
300	 * See \OCP\Constants::PERMISSION_*
301	 *
302	 * @param int $permissions
303	 * @return \OCP\Share\IShare The modified object
304	 * @since 9.0.0
305	 */
306	public function setPermissions($permissions);
307
308	/**
309	 * Get the share permissions
310	 * See \OCP\Constants::PERMISSION_*
311	 *
312	 * @return int
313	 * @since 9.0.0
314	 */
315	public function getPermissions();
316
317	/**
318	 * Set the accepted status
319	 * See self::STATUS_*
320	 *
321	 * @param int $status
322	 * @return IShare The modified object
323	 * @since 18.0.0
324	 */
325	public function setStatus(int $status): IShare;
326
327	/**
328	 * Get the accepted status
329	 * See self::STATUS_*
330	 *
331	 * @return int
332	 * @since 18.0.0
333	 */
334	public function getStatus(): int;
335
336	/**
337	 * Attach a note to a share
338	 *
339	 * @param string $note
340	 * @return \OCP\Share\IShare The modified object
341	 * @since 14.0.0
342	 */
343	public function setNote($note);
344
345	/**
346	 * Get note attached to a share
347	 *
348	 * @return string
349	 * @since 14.0.0
350	 */
351	public function getNote();
352
353
354	/**
355	 * Set the expiration date
356	 *
357	 * @param null|\DateTime $expireDate
358	 * @return \OCP\Share\IShare The modified object
359	 * @since 9.0.0
360	 */
361	public function setExpirationDate($expireDate);
362
363	/**
364	 * Get the expiration date
365	 *
366	 * @return \DateTime
367	 * @since 9.0.0
368	 */
369	public function getExpirationDate();
370
371	/**
372	 * Is the share expired ?
373	 *
374	 * @return boolean
375	 * @since 18.0.0
376	 */
377	public function isExpired();
378
379	/**
380	 * set a label for a share, some shares, e.g. public links can have a label
381	 *
382	 * @param string $label
383	 * @return \OCP\Share\IShare The modified object
384	 * @since 15.0.0
385	 */
386	public function setLabel($label);
387
388	/**
389	 * get label for the share, some shares, e.g. public links can have a label
390	 *
391	 * @return string
392	 * @since 15.0.0
393	 */
394	public function getLabel();
395
396	/**
397	 * Set the sharer of the path.
398	 *
399	 * @param string $sharedBy
400	 * @return \OCP\Share\IShare The modified object
401	 * @since 9.0.0
402	 */
403	public function setSharedBy($sharedBy);
404
405	/**
406	 * Get share sharer
407	 *
408	 * @return string
409	 * @since 9.0.0
410	 */
411	public function getSharedBy();
412
413	/**
414	 * Set the original share owner (who owns the path that is shared)
415	 *
416	 * @param string $shareOwner
417	 * @return \OCP\Share\IShare The modified object
418	 * @since 9.0.0
419	 */
420	public function setShareOwner($shareOwner);
421
422	/**
423	 * Get the original share owner (who owns the path that is shared)
424	 *
425	 * @return string
426	 * @since 9.0.0
427	 */
428	public function getShareOwner();
429
430	/**
431	 * Set the password for this share.
432	 * When the share is passed to the share manager to be created
433	 * or updated the password will be hashed.
434	 *
435	 * @param string|null $password
436	 * @return \OCP\Share\IShare The modified object
437	 * @since 9.0.0
438	 */
439	public function setPassword($password);
440
441	/**
442	 * Get the password of this share.
443	 * If this share is obtained via a shareprovider the password is
444	 * hashed.
445	 *
446	 * @return string
447	 * @since 9.0.0
448	 */
449	public function getPassword();
450
451
452	/**
453	 * Set if the recipient can start a conversation with the owner to get the
454	 * password using Nextcloud Talk.
455	 *
456	 * @param bool $sendPasswordByTalk
457	 * @return \OCP\Share\IShare The modified object
458	 * @since 14.0.0
459	 */
460	public function setSendPasswordByTalk(bool $sendPasswordByTalk);
461
462	/**
463	 * Get if the recipient can start a conversation with the owner to get the
464	 * password using Nextcloud Talk.
465	 * The returned value does not take into account other factors, like Talk
466	 * being enabled for the owner of the share or not; it just cover whether
467	 * the option is enabled for the share itself or not.
468	 *
469	 * @return bool
470	 * @since 14.0.0
471	 */
472	public function getSendPasswordByTalk(): bool;
473
474	/**
475	 * Set the public link token.
476	 *
477	 * @param string $token
478	 * @return \OCP\Share\IShare The modified object
479	 * @since 9.0.0
480	 */
481	public function setToken($token);
482
483	/**
484	 * Get the public link token.
485	 *
486	 * @return string
487	 * @since 9.0.0
488	 */
489	public function getToken();
490
491	/**
492	 * Set the target path of this share relative to the recipients user folder.
493	 *
494	 * @param string $target
495	 * @return \OCP\Share\IShare The modified object
496	 * @since 9.0.0
497	 */
498	public function setTarget($target);
499
500	/**
501	 * Get the target path of this share relative to the recipients user folder.
502	 *
503	 * @return string
504	 * @since 9.0.0
505	 */
506	public function getTarget();
507
508	/**
509	 * Set the time this share was created
510	 *
511	 * @param \DateTime $shareTime
512	 * @return \OCP\Share\IShare The modified object
513	 * @since 9.0.0
514	 */
515	public function setShareTime(\DateTime $shareTime);
516
517	/**
518	 * Get the timestamp this share was created
519	 *
520	 * @return \DateTime
521	 * @since 9.0.0
522	 */
523	public function getShareTime();
524
525	/**
526	 * Set if the recipient is informed by mail about the share.
527	 *
528	 * @param bool $mailSend
529	 * @return \OCP\Share\IShare The modified object
530	 * @since 9.0.0
531	 */
532	public function setMailSend($mailSend);
533
534	/**
535	 * Get if the recipient informed by mail about the share.
536	 *
537	 * @return bool
538	 * @since 9.0.0
539	 */
540	public function getMailSend();
541
542	/**
543	 * Set the cache entry for the shared node
544	 *
545	 * @param ICacheEntry $entry
546	 * @since 11.0.0
547	 */
548	public function setNodeCacheEntry(ICacheEntry $entry);
549
550	/**
551	 * Get the cache entry for the shared node
552	 *
553	 * @return null|ICacheEntry
554	 * @since 11.0.0
555	 */
556	public function getNodeCacheEntry();
557
558	/**
559	 * Sets a shares hide download state
560	 * This is mainly for public shares. It will signal that the share page should
561	 * hide download buttons etc.
562	 *
563	 * @param bool $hide
564	 * @return IShare
565	 * @since 15.0.0
566	 */
567	public function setHideDownload(bool $hide): IShare;
568
569	/**
570	 * Gets a shares hide download state
571	 * This is mainly for public shares. It will signal that the share page should
572	 * hide download buttons etc.
573	 *
574	 * @return bool
575	 * @since 15.0.0
576	 */
577	public function getHideDownload(): bool;
578}
579