diff options
Diffstat (limited to 'lib/public/UserStatus')
| -rw-r--r-- | lib/public/UserStatus/IManager.php | 65 | ||||
| -rw-r--r-- | lib/public/UserStatus/IProvider.php | 25 | ||||
| -rw-r--r-- | lib/public/UserStatus/IUserStatus.php | 134 |
3 files changed, 224 insertions, 0 deletions
diff --git a/lib/public/UserStatus/IManager.php b/lib/public/UserStatus/IManager.php new file mode 100644 index 00000000000..d291ee0a540 --- /dev/null +++ b/lib/public/UserStatus/IManager.php @@ -0,0 +1,65 @@ +<?php + +declare(strict_types=1); + +/** + * SPDX-FileCopyrightText: 2020 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later + */ +namespace OCP\UserStatus; + +/** + * This interface allows to manage the user status. + * + * This interface must not be implemented in your application but + * instead should be used as a service and injected in your code with + * dependency injection. + * + * @since 20.0.0 + */ +interface IManager { + /** + * Gets the statuses for all users in $users + * + * @param string[] $userIds + * @return array<string, IUserStatus> array key being the userid, users without a status will not be in the returned array + * @since 20.0.0 + */ + public function getUserStatuses(array $userIds): array; + + + /** + * Set a new status for the selected user. + * + * @param string $userId The user for which we want to update the status. + * @param string $messageId The id of the predefined message. + * @param string $status The status to assign + * @param bool $createBackup If true, this will store the old status so that it is possible to revert it later (e.g. after a call). + * @param string|null $customMessage + * @since 23.0.0 + * @since 28.0.0 Optional parameter $customMessage was added + */ + public function setUserStatus(string $userId, string $messageId, string $status, bool $createBackup = false, ?string $customMessage = null): void; + + /** + * Revert an automatically set user status. For example after leaving a call, + * change back to the previously set status. + * + * @param string $userId The user for which we want to update the status. + * @param string $messageId The expected current messageId. If the user has already updated their status, this method does nothing. + * @param string $status The expected current status. If the user has already updated their status, this method does nothing. + * @since 23.0.0 + */ + public function revertUserStatus(string $userId, string $messageId, string $status): void; + + /** + * Revert an automatically set user status. For example after leaving a call, + * change back to the previously set status. + * + * @param string[] $userIds The user for which we want to update the status. + * @param string $messageId The expected current messageId. If the user has already updated their status, this method does nothing. + * @param string $status The expected current status. If the user has already updated their status, this method does nothing. + * @since 23.0.0 + */ + public function revertMultipleUserStatus(array $userIds, string $messageId, string $status): void; +} diff --git a/lib/public/UserStatus/IProvider.php b/lib/public/UserStatus/IProvider.php new file mode 100644 index 00000000000..ef0dc831085 --- /dev/null +++ b/lib/public/UserStatus/IProvider.php @@ -0,0 +1,25 @@ +<?php + +declare(strict_types=1); + +/** + * SPDX-FileCopyrightText: 2020 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later + */ +namespace OCP\UserStatus; + +/** + * Interface IProvider + * + * @since 20.0.0 + */ +interface IProvider { + /** + * Gets the statuses for all users in $users + * + * @param string[] $userIds + * @return array<string, IUserStatus> array key being the userid, users without a status will not be in the returned array + * @since 20.0.0 + */ + public function getUserStatuses(array $userIds):array; +} diff --git a/lib/public/UserStatus/IUserStatus.php b/lib/public/UserStatus/IUserStatus.php new file mode 100644 index 00000000000..48eecfec24a --- /dev/null +++ b/lib/public/UserStatus/IUserStatus.php @@ -0,0 +1,134 @@ +<?php + +declare(strict_types=1); + +/** + * SPDX-FileCopyrightText: 2020 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later + */ +namespace OCP\UserStatus; + +use DateTimeImmutable; + +/** + * Interface IUserStatus + * + * @since 20.0.0 + */ +interface IUserStatus { + /** + * @var string + * @since 20.0.0 + */ + public const ONLINE = 'online'; + + /** + * @var string + * @since 20.0.0 + */ + public const AWAY = 'away'; + + /** + * @var string + * @since 20.0.0 + */ + public const DND = 'dnd'; + + /** + * @var string + * @since 28.0.0 + */ + public const BUSY = 'busy'; + + /** + * @var string + * @since 20.0.0 + */ + public const OFFLINE = 'offline'; + + /** + * @var string + * @since 20.0.0 + */ + public const INVISIBLE = 'invisible'; + + /** + * @var string + * @since 25.0.0 + */ + public const MESSAGE_CALL = 'call'; + + /** + * @var string + * @since 25.0.0 + */ + public const MESSAGE_AVAILABILITY = 'availability'; + + /** + * @var string + * @since 28.0.1 + */ + public const MESSAGE_OUT_OF_OFFICE = 'out-of-office'; + + /** + * @var string + * @since 28.0.0 + */ + public const MESSAGE_VACATION = 'vacationing'; + + /** + * @var string + * @since 28.0.0 + */ + public const MESSAGE_CALENDAR_BUSY = 'meeting'; + + /** + * @var string + * @since 28.0.0 + */ + public const MESSAGE_CALENDAR_BUSY_TENTATIVE = 'busy-tentative'; + + /** + * Get the user this status is connected to + * + * @return string + * @since 20.0.0 + */ + public function getUserId():string; + + /** + * Get the status + * + * It will return one of the constants defined above. + * It will never return invisible. In case a user marked + * themselves as invisible, it will return offline. + * + * @return string See IUserStatus constants + * @since 20.0.0 + */ + public function getStatus():string; + + /** + * Get a custom message provided by the user + * + * @return string|null + * @since 20.0.0 + */ + public function getMessage():?string; + + /** + * Get a custom icon provided by the user + * + * @return string|null + * @since 20.0.0 + */ + public function getIcon():?string; + + /** + * Gets the time that the custom status will be cleared at + * + * @return DateTimeImmutable|null + * @since 20.0.0 + */ + public function getClearAt():?DateTimeImmutable; +} |