From fd91555f1af0becf41f6ecc7a276de6114aefc04 Mon Sep 17 00:00:00 2001 From: Azrenbeth Date: Tue, 7 Sep 2021 16:19:34 +0000 Subject: deploy: e7b78dcc4a6bf8fdb71782640932da8dff7cc5ed --- latest/modules.html | 36 +++++++++++++++++++++++++++++++++++- 1 file changed, 35 insertions(+), 1 deletion(-) (limited to 'latest/modules.html') diff --git a/latest/modules.html b/latest/modules.html index 25afe46716..4efb19d991 100644 --- a/latest/modules.html +++ b/latest/modules.html @@ -99,7 +99,7 @@ @@ -386,6 +386,40 @@ for a list of possible parameters), and a boolean indicating whether the user pe the request is a server admin.

Modules can modify the request_content (by e.g. adding events to its initial_state), or deny the room's creation by raising a module_api.errors.SynapseError.

+

Presence router callbacks

+

Presence router callbacks allow module developers to specify additional users (local or remote) +to receive certain presence updates from local users. Presence router callbacks can be +registered using the module API's register_presence_router_callbacks method.

+

The available presence router callbacks are:

+
async def get_users_for_states(
+    self,
+    state_updates: Iterable["synapse.api.UserPresenceState"],
+) -> Dict[str, Set["synapse.api.UserPresenceState"]]:
+
+

Requires get_interested_users to also be registered

+

Called when processing updates to the presence state of one or more users. This callback can +be used to instruct the server to forward that presence state to specific users. The module +must return a dictionary that maps from Matrix user IDs (which can be local or remote) to the +UserPresenceState changes that they should be forwarded.

+

Synapse will then attempt to send the specified presence updates to each user when possible.

+
async def get_interested_users(
+        self, 
+        user_id: str
+) -> Union[Set[str], "synapse.module_api.PRESENCE_ALL_USERS"]
+
+

Requires get_users_for_states to also be registered

+

Called when determining which users someone should be able to see the presence state of. This +callback should return complementary results to get_users_for_state or the presence information +may not be properly forwarded.

+

The callback is given the Matrix user ID for a local user that is requesting presence data and +should return the Matrix user IDs of the users whose presence state they are allowed to +query. The returned users can be local or remote.

+

Alternatively the callback can return synapse.module_api.PRESENCE_ALL_USERS +to indicate that the user should receive updates from all known users.

+

For example, if the user @alice:example.org is passed to this method, and the Set +{"@bob:example.com", "@charlie:somewhere.org"} is returned, this signifies that Alice +should receive presence updates sent by Bob and Charlie, regardless of whether these users +share a room.

Porting an existing module that uses the old interface

In order to port a module that uses Synapse's old module interface, its author needs to: