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