IShare.php 13 KB

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