enable the user to set a primary (notification) email address (backend)

- specific getters and setters on IUser and implementation
- new notify_email field in provisioning API

Signed-off-by: Arthur Schiwon <blizzz@arthur-schiwon.de>

1 files changed, 62 insertions, 1 deletions

diff --git a/lib/public/IUser.php b/lib/public/IUser.php
index 7e75704ed5b..1a1d1e44d8a 100644
--- a/lib/public/IUser.php
+++ b/lib/public/IUser.php
@@ -27,6 +27,8 @@
  */
 namespace OCP;
 
+use InvalidArgumentException;
+
 /**
  * Interface IUser
  *
@@ -157,7 +159,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
@@ -165,6 +167,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
@@ -184,13 +215,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.