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 Robin Appelman <robin@icewind.nl> 9 * @author Roeland Jago Douma <roeland@famdouma.nl> 10 * 11 * @license AGPL-3.0 12 * 13 * This code is free software: you can redistribute it and/or modify 14 * it under the terms of the GNU Affero General Public License, version 3, 15 * as published by the Free Software Foundation. 16 * 17 * This program is distributed in the hope that it will be useful, 18 * but WITHOUT ANY WARRANTY; without even the implied warranty of 19 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 20 * GNU Affero General Public License for more details. 21 * 22 * You should have received a copy of the GNU Affero General Public License, version 3, 23 * along with this program. If not, see <http://www.gnu.org/licenses/> 24 * 25 */ 26namespace OCP\Share; 27 28use OCP\Files\Folder; 29use OCP\Files\Node; 30use OCP\Share\Exceptions\GenericShareException; 31use OCP\Share\Exceptions\ShareNotFound; 32 33/** 34 * Interface IShareProvider 35 * 36 * @since 9.0.0 37 */ 38interface IShareProvider { 39 40 /** 41 * Return the identifier of this provider. 42 * 43 * @return string Containing only [a-zA-Z0-9] 44 * @since 9.0.0 45 */ 46 public function identifier(); 47 48 /** 49 * Create a share 50 * 51 * @param \OCP\Share\IShare $share 52 * @return \OCP\Share\IShare The share object 53 * @since 9.0.0 54 */ 55 public function create(\OCP\Share\IShare $share); 56 57 /** 58 * Update a share 59 * 60 * @param \OCP\Share\IShare $share 61 * @return \OCP\Share\IShare The share object 62 * @since 9.0.0 63 */ 64 public function update(\OCP\Share\IShare $share); 65 66 /** 67 * Accept a share. 68 * 69 * @param IShare $share 70 * @param string $recipient 71 * @return IShare The share object 72 * @since 17.0.0 73 */ 74// public function acceptShare(IShare $share, string $recipient): IShare; 75 76 /** 77 * Delete a share 78 * 79 * @param \OCP\Share\IShare $share 80 * @since 9.0.0 81 */ 82 public function delete(\OCP\Share\IShare $share); 83 84 /** 85 * Unshare a file from self as recipient. 86 * This may require special handling. If a user unshares a group 87 * share from their self then the original group share should still exist. 88 * 89 * @param \OCP\Share\IShare $share 90 * @param string $recipient UserId of the recipient 91 * @since 9.0.0 92 */ 93 public function deleteFromSelf(\OCP\Share\IShare $share, $recipient); 94 95 /** 96 * Restore a share for a given recipient. The implementation could be provider independant. 97 * 98 * @param IShare $share 99 * @param string $recipient 100 * @return IShare The restored share object 101 * 102 * @since 14.0.0 103 * @throws GenericShareException In case the share could not be restored 104 */ 105 public function restore(IShare $share, string $recipient): IShare; 106 107 /** 108 * Move a share as a recipient. 109 * This is updating the share target. Thus the mount point of the recipient. 110 * This may require special handling. If a user moves a group share 111 * the target should only be changed for them. 112 * 113 * @param \OCP\Share\IShare $share 114 * @param string $recipient userId of recipient 115 * @return \OCP\Share\IShare 116 * @since 9.0.0 117 */ 118 public function move(\OCP\Share\IShare $share, $recipient); 119 120 /** 121 * Get all shares by the given user in a folder 122 * 123 * @param string $userId 124 * @param Folder $node 125 * @param bool $reshares Also get the shares where $user is the owner instead of just the shares where $user is the initiator 126 * @return \OCP\Share\IShare[][] 127 * @since 11.0.0 128 */ 129 public function getSharesInFolder($userId, Folder $node, $reshares); 130 131 /** 132 * Get all shares by the given user 133 * 134 * @param string $userId 135 * @param int $shareType 136 * @param Node|null $node 137 * @param bool $reshares Also get the shares where $user is the owner instead of just the shares where $user is the initiator 138 * @param int $limit The maximum number of shares to be returned, -1 for all shares 139 * @param int $offset 140 * @return \OCP\Share\IShare[] 141 * @since 9.0.0 142 */ 143 public function getSharesBy($userId, $shareType, $node, $reshares, $limit, $offset); 144 145 /** 146 * Get share by id 147 * 148 * @param int $id 149 * @param string|null $recipientId 150 * @return \OCP\Share\IShare 151 * @throws ShareNotFound 152 * @since 9.0.0 153 */ 154 public function getShareById($id, $recipientId = null); 155 156 /** 157 * Get shares for a given path 158 * 159 * @param Node $path 160 * @return \OCP\Share\IShare[] 161 * @since 9.0.0 162 */ 163 public function getSharesByPath(Node $path); 164 165 /** 166 * Get shared with the given user 167 * 168 * @param string $userId get shares where this user is the recipient 169 * @param int $shareType 170 * @param Node|null $node 171 * @param int $limit The max number of entries returned, -1 for all 172 * @param int $offset 173 * @return \OCP\Share\IShare[] 174 * @since 9.0.0 175 */ 176 public function getSharedWith($userId, $shareType, $node, $limit, $offset); 177 178 /** 179 * Get a share by token 180 * 181 * @param string $token 182 * @return \OCP\Share\IShare 183 * @throws ShareNotFound 184 * @since 9.0.0 185 */ 186 public function getShareByToken($token); 187 188 /** 189 * A user is deleted from the system 190 * So clean up the relevant shares. 191 * 192 * @param string $uid 193 * @param int $shareType 194 * @since 9.1.0 195 */ 196 public function userDeleted($uid, $shareType); 197 198 /** 199 * A group is deleted from the system. 200 * We have to clean up all shares to this group. 201 * Providers not handling group shares should just return 202 * 203 * @param string $gid 204 * @since 9.1.0 205 */ 206 public function groupDeleted($gid); 207 208 /** 209 * A user is deleted from a group 210 * We have to clean up all the related user specific group shares 211 * Providers not handling group shares should just return 212 * 213 * @param string $uid 214 * @param string $gid 215 * @since 9.1.0 216 */ 217 public function userDeletedFromGroup($uid, $gid); 218 219 /** 220 * Get the access list to the array of provided nodes. 221 * 222 * @see IManager::getAccessList() for sample docs 223 * 224 * @param Node[] $nodes The list of nodes to get access for 225 * @param bool $currentAccess If current access is required (like for removed shares that might get revived later) 226 * @return array 227 * @since 12 228 */ 229 public function getAccessList($nodes, $currentAccess); 230 231 /** 232 * Get all the shares in this provider returned as iterable to reduce memory 233 * overhead 234 * 235 * @return iterable 236 * @since 18.0.0 237 */ 238 public function getAllShares(): iterable; 239} 240