Struct SpaceService 

pub struct SpaceService { /* private fields */ }

The main entry point into the Spaces facilities.

The spaces service is responsible for retrieving one’s joined rooms, building a graph out of their m.space.parent and m.space.child state events, and providing access to the top-level spaces and their children.

Examples

use futures_util::StreamExt;
use matrix_sdk::Client;
use matrix_sdk_ui::spaces::SpaceService;
use ruma::owned_room_id;

let space_service = SpaceService::new(client.clone()).await;

// Get a list of all the joined spaces
let joined_spaces = space_service.top_level_joined_spaces().await;

// And subscribe to changes on them
// `initial_values` is equal to `top_level_joined_spaces` if nothing changed meanwhile
let (initial_values, stream) =
    space_service.subscribe_to_top_level_joined_spaces().await;

while let Some(diffs) = stream.next().await {
    println!("Received joined spaces updates: {diffs:?}");
}

// Get a list of all the rooms in a particular space
let room_list = space_service
    .space_room_list(owned_room_id!("!some_space:example.org"))
    .await;

// Which can be used to retrieve information about the children rooms
let children = room_list.rooms().await;

Implementations

impl SpaceService

pub async fn new(client: Client) -> Self

Creates a new SpaceService instance.

pub async fn subscribe_to_top_level_joined_spaces( &self, ) -> (Vector<SpaceRoom>, VectorSubscriberBatchedStream<SpaceRoom>)

Subscribes to updates on the joined spaces list. If space rooms are joined or left, the stream will yield diffs that reflect the changes.

pub async fn top_level_joined_spaces(&self) -> Vec<SpaceRoom>

Returns a list of all the top-level joined spaces. It will eagerly compute the latest version and also notify subscribers if there were any changes.

pub async fn space_filters(&self) -> Vec<SpaceFilter>

Space filters provide access to a custom subset of the space graph that can be used in tandem with the crate::RoomListService to narrow down the presented rooms. A crate::room_list_service::RoomList’s crate::room_list_service::RoomListDynamicEntriesController can take a filter, which in this case can be a crate::room_list_service::filters::new_filter_identifiers pointing to the space descendants retrieved from the filters.

They are limited to the first 2 levels of the graph, with the first level only containing direct descendants while the second holds the rest of them recursively.

Examples

use futures_util::StreamExt;
use matrix_sdk::Client;
use matrix_sdk_ui::{
    room_list_service::{RoomListService, filters},
    spaces::SpaceService,
};
use ruma::owned_room_id;

let space_service = SpaceService::new(client.clone()).await;
let room_list_service = RoomListService::new(client.clone()).await?;

// Get the list of filters derived from the space hierarchy.
let space_filters = space_service.space_filters().await;
// Pick a filter/space
let space_filter = space_filters.first().unwrap();

// Create a room list stream and a controller that accepts filters.
let all_rooms = room_list_service.all_rooms().await?;
let (_, controller) = all_rooms.entries_with_dynamic_adapters(25);

// Apply an identifiers filter built from the space filter descendants.
controller.set_filter(Box::new(filters::new_filter_identifiers(
    space_filter.descendants.clone(),
)));

pub async fn subscribe_to_space_filters( &self, ) -> (Vector<SpaceFilter>, VectorSubscriberBatchedStream<SpaceFilter>)

Subscribe to changes or updates to the space filters.

pub async fn editable_spaces(&self) -> Vec<SpaceRoom>

Returns a flattened list containing all the spaces where the user has permission to send m.space.child state events.

Note: Unlike Self::top_level_joined_spaces(), this method does not recompute graph, nor does it notify subscribers about changes.

pub async fn space_room_list(&self, space_id: OwnedRoomId) -> SpaceRoomList

Returns a SpaceRoomList for the given space ID.

pub async fn joined_parents_of_child(&self, child_id: &RoomId) -> Vec<SpaceRoom>

Returns all known direct-parents of a given space room ID.

pub async fn joined_parent_ids_of_child( &self, child_id: &RoomId, ) -> Vec<OwnedRoomId>

Returns the room IDs of all known direct parents of the given child space or room.

This is a much cheaper version of Self::joined_parents_of_child() that doesn’t build any SpaceRoom instances, it only reads the existing space graph.

The returned IDs are always joined spaces, as that’s all the space graph includes. Note that an empty result either means that the child is a top-level space (which has no direct parents) or the child isn’t part of the space graph at all. See Self::top_level_ancestors_of() if you need that particular level of detail.

Note: Unlike Self::top_level_joined_spaces(), this method does not recompute the space graph nor notify subscribers about changes.

pub async fn top_level_ancestors_of( &self, child_id: &RoomId, ) -> HashSet<OwnedRoomId>

Returns the room IDs of the top-level joined space(s) that the given child room/space descends from, by walking the space graph upwards.

A room/space can be the child of multiple spaces, so this might return multiple top-level spaces (in no order).

A top-level space is its own only ancestor, so a returned set holding just child_id is a cheap top-level space check.

Returns an empty set if the room isn’t part of the graph, which is notably the case for a room that was joined too recently for the graph to have been rebuilt.

Note: Unlike Self::top_level_joined_spaces(), this method does not recompute the space graph nor notify subscribers about changes.

pub async fn get_space_room(&self, room_id: &RoomId) -> Option<SpaceRoom>

Returns the corresponding SpaceRoom for the given room ID, or None if it isn’t known.

pub async fn add_child_to_space( &self, child_id: OwnedRoomId, space_id: OwnedRoomId, ) -> Result<(), Error>

pub async fn remove_child_from_space( &self, child_id: OwnedRoomId, space_id: OwnedRoomId, ) -> Result<(), Error>

pub async fn leave_space( &self, space_id: &RoomId, ) -> Result<LeaveSpaceHandle, Error>

Start a space leave process returning a LeaveSpaceHandle from which rooms can be retrieved in reversed BFS order starting from the requested space_id graph node. If the room is unknown then an error will be returned.

Once the rooms to be left are chosen the handle can be used to leave them.