ruma_client_api/space/
get_hierarchy.rs

1//! `GET /_matrix/client/*/rooms/{roomId}/hierarchy`
2//!
3//! Paginates over the space tree in a depth-first manner to locate child rooms of a given space.
4
5pub mod v1 {
6    //! `/v1/` ([spec])
7    //!
8    //! [spec]: https://spec.matrix.org/latest/client-server-api/#get_matrixclientv1roomsroomidhierarchy
9
10    use js_int::UInt;
11    use ruma_common::{
12        api::{request, response, Metadata},
13        metadata, OwnedRoomId,
14    };
15
16    use crate::space::SpaceHierarchyRoomsChunk;
17
18    const METADATA: Metadata = metadata! {
19        method: GET,
20        rate_limited: true,
21        authentication: AccessToken,
22        history: {
23            unstable => "/_matrix/client/unstable/org.matrix.msc2946/rooms/:room_id/hierarchy",
24            1.2 => "/_matrix/client/v1/rooms/:room_id/hierarchy",
25        }
26    };
27
28    /// Request type for the `hierarchy` endpoint.
29    #[request(error = crate::Error)]
30    pub struct Request {
31        /// The room ID of the space to get a hierarchy for.
32        #[ruma_api(path)]
33        pub room_id: OwnedRoomId,
34
35        /// A pagination token from a previous result.
36        ///
37        /// If specified, `max_depth` and `suggested_only` cannot be changed from the first
38        /// request.
39        #[ruma_api(query)]
40        pub from: Option<String>,
41
42        /// The maximum number of rooms to include per response.
43        #[ruma_api(query)]
44        pub limit: Option<UInt>,
45
46        /// How far to go into the space.
47        ///
48        /// When reached, no further child rooms will be returned.
49        #[ruma_api(query)]
50        pub max_depth: Option<UInt>,
51
52        /// Whether or not the server should only consider suggested rooms.
53        ///
54        /// Suggested rooms are annotated in their `m.space.child` event contents.
55        ///
56        /// Defaults to `false`.
57        #[ruma_api(query)]
58        #[serde(default, skip_serializing_if = "ruma_common::serde::is_default")]
59        pub suggested_only: bool,
60    }
61
62    /// Response type for the `hierarchy` endpoint.
63    #[response(error = crate::Error)]
64    #[derive(Default)]
65    pub struct Response {
66        /// A token to supply to from to keep paginating the responses.
67        ///
68        /// Not present when there are no further results.
69        #[serde(skip_serializing_if = "Option::is_none")]
70        pub next_batch: Option<String>,
71
72        /// A paginated chunk of the space children.
73        pub rooms: Vec<SpaceHierarchyRoomsChunk>,
74    }
75
76    impl Request {
77        /// Creates a new `Request` with the given room ID.
78        pub fn new(room_id: OwnedRoomId) -> Self {
79            Self { room_id, from: None, limit: None, max_depth: None, suggested_only: false }
80        }
81    }
82
83    impl Response {
84        /// Creates an empty `Response`.
85        pub fn new() -> Self {
86            Default::default()
87        }
88    }
89}
ruma_client_api/space/get_hierarchy.rs

ruma_client_api/space/
get_hierarchy.rs
