diff options
Diffstat (limited to 'lib/public/IUser.php')
| -rw-r--r-- | lib/public/IUser.php | 169 |
1 files changed, 137 insertions, 32 deletions
diff --git a/lib/public/IUser.php b/lib/public/IUser.php index feb876176bf..945e7e1602a 100644 --- a/lib/public/IUser.php +++ b/lib/public/IUser.php @@ -1,39 +1,24 @@ <?php + /** - * @copyright Copyright (c) 2016, ownCloud, Inc. - * - * @author Arthur Schiwon <blizzz@arthur-schiwon.de> - * @author John Molakvoæ (skjnldsv) <skjnldsv@protonmail.com> - * @author Lukas Reschke <lukas@statuscode.ch> - * @author Morris Jobke <hey@morrisjobke.de> - * @author Robin Appelman <robin@icewind.nl> - * @author Roeland Jago Douma <roeland@famdouma.nl> - * @author Thomas Müller <thomas.mueller@tmit.eu> - * - * @license AGPL-3.0 - * - * This code is free software: you can redistribute it and/or modify - * it under the terms of the GNU Affero General Public License, version 3, - * as published by the Free Software Foundation. - * - * This program is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU Affero General Public License for more details. - * - * You should have received a copy of the GNU Affero General Public License, version 3, - * along with this program. If not, see <http://www.gnu.org/licenses/> - * + * SPDX-FileCopyrightText: 2016-2024 Nextcloud GmbH and Nextcloud contributors + * SPDX-FileCopyrightText: 2016 ownCloud, Inc. + * SPDX-License-Identifier: AGPL-3.0-only */ - namespace OCP; +use InvalidArgumentException; + /** * Interface IUser * * @since 8.0.0 */ interface IUser { + /** + * @since 32.0.0 + */ + public const MAX_USERID_LENGTH = 64; /** * get the user id @@ -57,6 +42,9 @@ interface IUser { * @param string $displayName * @return bool * @since 8.0.0 + * + * @since 25.0.0 Throw InvalidArgumentException + * @throws \InvalidArgumentException */ public function setDisplayName($displayName); @@ -67,13 +55,22 @@ interface IUser { * @return int * @since 8.0.0 */ - public function getLastLogin(); + public function getLastLogin(): int; /** - * updates the timestamp of the most recent login of this user + * Returns the timestamp of the user's first login, 0 if the user did never login, or -1 if the data is unknown (first login was on an older version) + * + * @since 31.0.0 + */ + public function getFirstLogin(): int; + + /** + * Updates the timestamp of the most recent login of this user (and first login if needed) + * + * @return bool whether this is the first login * @since 8.0.0 */ - public function updateLastLoginTimestamp(); + public function updateLastLoginTimestamp(): bool; /** * Delete the user @@ -94,6 +91,23 @@ interface IUser { public function setPassword($password, $recoveryPassword = null); /** + * Get the password hash of the user + * + * @return ?string the password hash hashed by `\OCP\Security\IHasher::hash()` + * @since 30.0.0 + */ + public function getPasswordHash(): ?string; + + /** + * Set the password hash of the user + * + * @param string $passwordHash the password hash hashed by `\OCP\Security\IHasher::hash()` + * @throws InvalidArgumentException when `$passwordHash` is not a valid hash + * @since 30.0.0 + */ + public function setPasswordHash(string $passwordHash): bool; + + /** * get the users home folder to mount * * @return string @@ -111,14 +125,13 @@ interface IUser { /** * Get the backend for the current user object - * - * @return UserInterface + * @return ?UserInterface * @since 15.0.0 */ public function getBackend(); /** - * check if the backend allows the user to change his avatar on Personal page + * check if the backend allows the user to change their avatar on Personal page * * @return bool * @since 8.0.0 @@ -142,6 +155,13 @@ interface IUser { public function canChangeDisplayName(); /** + * Check if the backend supports changing email + * + * @since 32.0.0 + */ + public function canChangeEmail(): bool; + + /** * check if the user is enabled * * @return bool @@ -158,7 +178,7 @@ interface IUser { public function setEnabled(bool $enabled = true); /** - * get the users email address + * get the user's email address * * @return string|null * @since 9.0.0 @@ -166,6 +186,35 @@ interface IUser { public function getEMailAddress(); /** + * get the user's system email address + * + * The system mail address may be read only and may be set from different + * sources like LDAP, SAML or simply the admin. + * + * Use this getter only when the system address is needed. For picking the + * proper address to e.g. send a mail to, use getEMailAddress(). + * + * @return string|null + * @since 23.0.0 + */ + public function getSystemEMailAddress(): ?string; + + /** + * get the user's preferred email address + * + * The primary mail address may be set be the user to specify a different + * email address where mails by Nextcloud are sent to. It is not necessarily + * set. + * + * Use this getter only when the primary address is needed. For picking the + * proper address to e.g. send a mail to, use getEMailAddress(). + * + * @return string|null + * @since 23.0.0 + */ + public function getPrimaryEMailAddress(): ?string; + + /** * get the avatar image if it exists * * @param int $size @@ -185,13 +234,43 @@ interface IUser { /** * set the email address of the user * + * It is an alias to setSystemEMailAddress() + * * @param string|null $mailAddress * @return void * @since 9.0.0 + * @deprecated 23.0.0 use setSystemEMailAddress() or setPrimaryEMailAddress() */ public function setEMailAddress($mailAddress); /** + * Set the system email address of the user + * + * This is supposed to be used when the email is set from different sources + * (i.e. other user backends, admin). + * + * @since 23.0.0 + */ + public function setSystemEMailAddress(string $mailAddress): void; + + /** + * Set the primary email address of the user. + * + * This method should be typically called when the user is changing their + * own primary address and is not allowed to change their system email. + * + * The mail address provided here must be already registered as an + * additional mail in the user account and also be verified locally. Also + * an empty string is allowed to delete this preference. + * + * @throws InvalidArgumentException when the provided email address does not + * satisfy constraints. + * + * @since 23.0.0 + */ + public function setPrimaryEMailAddress(string $mailAddress): void; + + /** * get the users' quota in human readable form. If a specific quota is not * set for the user, the default value is returned. If a default setting * was not set otherwise, it is return as 'none', i.e. quota is not limited. @@ -202,6 +281,15 @@ interface IUser { public function getQuota(); /** + * Get the users' quota in machine readable form. If a specific quota is set + * for the user, then the quota is returned in bytes. Otherwise the default value is returned. + * If a default setting was not set, it is return as `\OCP\Files\FileInfo::SPACE_UNLIMITED`, i.e. quota is not limited. + * + * @since 32.0.0 + */ + public function getQuotaBytes(): int|float; + + /** * set the users' quota * * @param string $quota @@ -209,4 +297,21 @@ interface IUser { * @since 9.0.0 */ public function setQuota($quota); + + /** + * Get the user's manager UIDs + * + * @since 27.0.0 + * @return string[] + */ + public function getManagerUids(): array; + + /** + * Set the user's manager UIDs + * + * @param string[] $uids UIDs of all managers + * @return void + * @since 27.0.0 + */ + public function setManagerUids(array $uids): void; } |