IShare.php 11 KB

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