1<?php 2/** 3 * @author Roeland Jago Douma <rullzer@owncloud.com> 4 * 5 * @copyright Copyright (c) 2018, ownCloud GmbH 6 * @license AGPL-3.0 7 * 8 * This code is free software: you can redistribute it and/or modify 9 * it under the terms of the GNU Affero General Public License, version 3, 10 * as published by the Free Software Foundation. 11 * 12 * This program is distributed in the hope that it will be useful, 13 * but WITHOUT ANY WARRANTY; without even the implied warranty of 14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 15 * GNU Affero General Public License for more details. 16 * 17 * You should have received a copy of the GNU Affero General Public License, version 3, 18 * along with this program. If not, see <http://www.gnu.org/licenses/> 19 * 20 */ 21 22namespace OCP\Share; 23 24use OCP\Share\Exceptions\ShareNotFound; 25use OCP\Files\Node; 26 27/** 28 * Interface IShareProvider 29 * 30 * @package OCP\Share 31 * @since 9.0.0 32 */ 33interface IShareProvider { 34 /** 35 * The capabilities below refer mainly to storing capabilities allowed 36 * by the implementing share provider. Validation or enforcement rules 37 * (for passwords for example) aren't expected to be handled as capabilities 38 * here because those rules will be checked at API level, not here. 39 * If a share provider doesn't support any of these capabilities, it should 40 * either store the value as null or don't store it, and return a null value 41 * as value when the share is gotten. 42 */ 43 /** 44 * Store when the share expires. An expired share needs to be automatically 45 * deleted. If a share won't expire, a "null" value will be used 46 */ 47 public const CAPABILITY_STORE_EXPIRATION = 'shareExpiration'; 48 /** 49 * Store the (hashed) password to protect the share. A value of null means 50 * that the share isn't protected by a password. 51 */ 52 public const CAPABILITY_STORE_PASSWORD = 'passwordProtected'; 53 54 /** 55 * Return the identifier of this provider. 56 * 57 * @return string Containing only [a-zA-Z0-9] 58 * @since 9.0.0 59 */ 60 public function identifier(); 61 62 /** 63 * Create a share 64 * 65 * @param \OCP\Share\IShare $share 66 * @return \OCP\Share\IShare The share object 67 * @since 9.0.0 68 */ 69 public function create(\OCP\Share\IShare $share); 70 71 /** 72 * Update a share 73 * 74 * @param \OCP\Share\IShare $share 75 * @return \OCP\Share\IShare The share object 76 * @since 9.0.0 77 */ 78 public function update(\OCP\Share\IShare $share); 79 80 /** 81 * Delete a share 82 * 83 * @param \OCP\Share\IShare $share 84 * @since 9.0.0 85 */ 86 public function delete(\OCP\Share\IShare $share); 87 88 /** 89 * Unshare a file from self as recipient. 90 * This may require special handling. If a user unshares a group 91 * share from their self then the original group share should still exist. 92 * 93 * @param \OCP\Share\IShare $share 94 * @param string $recipient UserId of the recipient 95 * @since 9.0.0 96 */ 97 public function deleteFromSelf(\OCP\Share\IShare $share, $recipient); 98 99 /** 100 * Move a share as a recipient. 101 * This is updating the share target. Thus the mount point of the recipient. 102 * This may require special handling. If a user moves a group share 103 * the target should only be changed for them. 104 * 105 * @param \OCP\Share\IShare $share 106 * @param string $recipient userId of recipient 107 * @return \OCP\Share\IShare 108 * @since 9.0.0 109 * @deprecated 10.0.9 use updateForRecipient() instead 110 */ 111 public function move(\OCP\Share\IShare $share, $recipient); 112 113 /** 114 * Get all shares by the given user 115 * 116 * @param string $userId 117 * @param int $shareType 118 * @param Node|null $node 119 * @param bool $reshares Also get the shares where $user is the owner instead of just the shares where $user is the initiator 120 * @param int $limit The maximum number of shares to be returned, -1 for all shares 121 * @param int $offset 122 * @return \OCP\Share\IShare[] 123 * @since 9.0.0 124 */ 125 public function getSharesBy($userId, $shareType, $node, $reshares, $limit, $offset); 126 127 /** 128 * Get all shares by the given user for specified shareTypes array (ref. \OC\Share\Constants) 129 * 130 * @param string $userId 131 * @param int[] $shareTypes 132 * @param Node[] $nodeIDs 133 * @param bool $reshares - Also get the shares where $user is the owner instead of just the shares where $user is the initiator 134 * @return \OCP\Share\IShare[] 135 * @since 10.0.0 136 */ 137 public function getAllSharesBy($userId, $shareTypes, $nodeIDs, $reshares); 138 139 /** 140 * Get share by id 141 * 142 * @param string $id 143 * @param string|null $recipientId 144 * @return \OCP\Share\IShare 145 * @throws ShareNotFound 146 * @throws ProviderException 147 * @since 9.0.0 148 */ 149 public function getShareById($id, $recipientId = null); 150 151 /** 152 * Get shares for a given path 153 * 154 * @param Node $path 155 * @return \OCP\Share\IShare[] 156 * @since 9.0.0 157 */ 158 public function getSharesByPath(Node $path); 159 160 /** 161 * Get shared with the given user for shares of all supported share types for this share provider, 162 * with file_source predicate specified ($node is Node) or 163 * without ($node is null and scan over file_source is performed). 164 * 165 * @param string $userId get shares where this user is the recipient 166 * @param Node|null $node 167 * @return \OCP\Share\IShare[] 168 * @since 10.0.0 169 */ 170 public function getAllSharedWith($userId, $node); 171 172 /** 173 * Get shared with the given user specifying share type predicate for this specific share provider 174 * 175 * @param string $userId get shares where this user is the recipient 176 * @param int $shareType 177 * @param Node|null $node 178 * @param int $limit The max number of entries returned, -1 for all 179 * @param int $offset 180 * @return \OCP\Share\IShare[] 181 * @since 9.0.0 182 */ 183 public function getSharedWith($userId, $shareType, $node, $limit, $offset); 184 185 /** 186 * Get a share by token 187 * 188 * @param string $token 189 * @return \OCP\Share\IShare 190 * @throws ShareNotFound 191 * @since 9.0.0 192 */ 193 public function getShareByToken($token); 194 195 /** 196 * Get the shares which are associated with an invalid or missing fileid. 197 * This means that the share isn't valid any longer because the source file 198 * has been deleted. 199 * 200 * @param int $limit limit the number of results, -1 to get all results without limit 201 * @return \OCP\Share\IShare[] 202 * @since 10.7.0 203 */ 204 public function getSharesWithInvalidFileid(int $limit); 205 206 /** 207 * A user is deleted from the system 208 * So clean up the relevant shares. 209 * 210 * @param string $uid 211 * @param int $shareType 212 * @since 9.1.0 213 */ 214 public function userDeleted($uid, $shareType); 215 216 /** 217 * A group is deleted from the system. 218 * We have to clean up all shares to this group. 219 * Providers not handling group shares should just return 220 * 221 * @param string $gid 222 * @since 9.1.0 223 */ 224 public function groupDeleted($gid); 225 226 /** 227 * A user is deleted from a group 228 * We have to clean up all the related user specific group shares 229 * Providers not handling group shares should just return 230 * 231 * @param string $uid 232 * @param string $gid 233 * @since 9.1.0 234 */ 235 public function userDeletedFromGroup($uid, $gid); 236 237 /** 238 * Updates the share entry of the given recipient 239 * 240 * For group shares, only the state for the given recipient is changed, 241 * not for the whole group share. 242 * 243 * @param \OCP\Share\IShare $share 244 * @param string $recipient userId of recipient 245 * @param int $state state to set 246 * @return \OCP\Share\IShare 247 * @since 10.0.9 248 */ 249 public function updateForRecipient(\OCP\Share\IShare $share, $recipient); 250 251 /** 252 * Get the share provider's capabilities. It will return a map with the supported 253 * share type with the list of capabilities for that share type: 254 * [ 255 * \OCP\Share::CONVERT_SHARE_TYPE_TO_STRING[\OCP\Share::SHARE_TYPE_USER] => [ 256 * IShareProvider::CAPABILITY_STORE_EXPIRATION 257 * ], 258 * \OCP\Share::CONVERT_SHARE_TYPE_TO_STRING[\OCP\Share::SHARE_TYPE_LINK] => [ 259 * IShareProvider::CAPABILITY_STORE_EXPIRATION, 260 * IShareProvider::CAPABILITY_STORE_PASSWORD 261 * ], 262 * \OCP\Share::CONVERT_SHARE_TYPE_TO_STRING[\OCP\Share::SHARE_TYPE_GROUP] => [] 263 * ] 264 * Supported share types by this provider should have the corresponding entry even if 265 * it doesn't support extra capabilities 266 * 267 * @return array 268 * @since 10.3.2 269 */ 270 public function getProviderCapabilities(); 271} 272