From 3c51f0cb1e2d04dbb27f1bbc3db0b31a2d1365ba Mon Sep 17 00:00:00 2001
From: Carl Schwan <carl@carlschwan.eu>
Date: Wed, 1 Dec 2021 23:10:16 +0100
Subject: [PATCH] Document user status API

Signed-off-by: Carl Schwan <carl@carlschwan.eu>
---
 developer_manual/digging_deeper/dashboard.rst |  1 +
 developer_manual/digging_deeper/index.rst     |  1 +
 developer_manual/digging_deeper/status.rst    | 95 +++++++++++++++++++
 3 files changed, 97 insertions(+)
 create mode 100644 developer_manual/digging_deeper/status.rst

diff --git a/developer_manual/digging_deeper/dashboard.rst b/developer_manual/digging_deeper/dashboard.rst
index 20fba022f..cfb035f97 100644
--- a/developer_manual/digging_deeper/dashboard.rst
+++ b/developer_manual/digging_deeper/dashboard.rst
@@ -129,6 +129,7 @@ need to support older versions where the new app boostrap flow is not available,
 however this method is deprecated and will be removed once Nextcloud 19 is EOL.
 
 .. code-block:: php
+
     <?php
 
     use OCP\Dashboard\RegisterWidgetEvent;
diff --git a/developer_manual/digging_deeper/index.rst b/developer_manual/digging_deeper/index.rst
index 0c1112f22..83aaf92ce 100644
--- a/developer_manual/digging_deeper/index.rst
+++ b/developer_manual/digging_deeper/index.rst
@@ -26,3 +26,4 @@ Digging deeper
    dashboard
    groupware/index
    web_host_metadata
+   status
diff --git a/developer_manual/digging_deeper/status.rst b/developer_manual/digging_deeper/status.rst
new file mode 100644
index 000000000..ec6e68e9a
--- /dev/null
+++ b/developer_manual/digging_deeper/status.rst
@@ -0,0 +1,95 @@
+===========
+User Status
+===========
+
+Nextcloud allows user to publish their current status. The status is then
+available in various part of the user interface (e.g. participants list in
+a Talk room).
+
+Query Status
+------------
+
+Using the `OCP\\UserStatus\\IManager` interface, it is possible to query
+the user status, for a group of users.
+
+.. code-block:: php
+
+    <?php
+
+    namespace OCA\MyGreatApp\Service;
+
+    use OCP\UserStatus\IManager as IStatusManager;
+    use OCP\UserStatus\IUserStatus;
+
+    class MyService {
+        /** @var IStatusManager $statusManager */
+        public $statusManager;
+
+        public function __construct(IStatusManager $statusManager) {
+            $this->statusManager = $statusManager;
+        }
+
+        /**
+         * @param string[] $userIds
+         * @return IUserStatus[]
+         */
+        public function queryStatusForUsers(array $userIds): array {
+            return $this->statusManager->getUserStatuses($userIds);
+        }
+    }
+
+Updating the status programmatically
+------------------------------------
+
+A Nextcloud application can change the user status programmatically. This feature
+`setUserStatus` from the `OCP\\UserStatus\\IManager` interface when for example an
+user execute an action in the UI.
+
+If the status is supposed to be reverted with an upcoming action from the
+user, `setUserStatus` will require to be called with `$createBackup = true`.
+
+This then can be reverted with a call to `revertUserStatus` with the same
+`$messageId` and `$status`.
+
+.. code-block:: php
+
+    <?php
+
+    namespace OCA\MyGreatApp\Status;
+
+    use OCA\MyGreatApp\MyEvents;
+    use OCA\MyGreatApp\CoolStartEvent;
+    use OCA\MyGreatApp\CoolEndEvent;
+    use OCP\UserStatus\IManager as IStatusManager;
+    use OCP\UserStatus\IUserStatus;
+
+    class Listener {
+        /** @var IStatusManager $statusManager */
+        public $statusManager;
+
+        public function __construct(IStatusManager $statusManager) {
+            $this->statusManager = $statusManager;
+        }
+
+        public static function register(IEventDispatcher $dispatcher): void {
+            $dispatcher->addListener(MyEvents::COOL_EVENT_STARTED, static function (CoolStartEvent $event) {
+                /** @var self $listener */
+                $listener = \OC::$server->get(self::class);
+                $listener->setUserStatus($event);
+            });
+
+            $dispatcher->addListener(MyEvents::COOL_EVENT_FINISHED, static function (CoolEndEvent $event) {
+                /** @var self $listener */
+                $listener = \OC::$server->get(self::class);
+                $listener->revertUserStatus($event);
+            });
+        }
+
+        public function setUserStatus(ModifyParticipantEvent $event): void {
+            $this->statusManager->setUserStatus($event->getUserId(), 'meeting', IUserStatus::AWAY, true);
+        }
+
+        public function revertUserStatus(ModifyParticipantEvent $event): void {
+            $this->statusManager->revertUserStatus($event->getUserId(), 'meeting', IUserStatus::AWAY);
+        }
+