ruma_client_api/relations/
get_relating_events.rs

1//! `GET /_matrix/client/*/rooms/{roomId}/relations/{eventId}`
2//!
3//! Get the child events for a given parent event.
4
5pub mod v1 {
6    //! `/v1/` ([spec])
7    //!
8    //! [spec]: https://spec.matrix.org/latest/client-server-api/#get_matrixclientv1roomsroomidrelationseventid
9
10    use js_int::UInt;
11    use ruma_common::{
12        api::{request, response, Direction, Metadata},
13        metadata,
14        serde::Raw,
15        OwnedEventId, OwnedRoomId,
16    };
17    use ruma_events::AnyMessageLikeEvent;
18
19    const METADATA: Metadata = metadata! {
20        method: GET,
21        rate_limited: false,
22        authentication: AccessToken,
23        history: {
24            unstable => "/_matrix/client/unstable/rooms/:room_id/relations/:event_id",
25            1.3 => "/_matrix/client/v1/rooms/:room_id/relations/:event_id",
26        }
27    };
28
29    /// Request type for the `get_relating_events` endpoint.
30    #[request(error = crate::Error)]
31    pub struct Request {
32        /// The ID of the room containing the parent event.
33        #[ruma_api(path)]
34        pub room_id: OwnedRoomId,
35
36        /// The ID of the parent event whose child events are to be returned.
37        #[ruma_api(path)]
38        pub event_id: OwnedEventId,
39
40        /// The pagination token to start returning results from.
41        ///
42        /// If `None`, results start at the most recent topological event known to the server.
43        ///
44        /// Can be a `next_batch` or `prev_batch` token from a previous call, or a returned
45        /// `start` token from `/messages` or a `next_batch` token from `/sync`.
46        ///
47        /// Note that when paginating the `from` token should be "after" the `to` token in
48        /// terms of topological ordering, because it is only possible to paginate "backwards"
49        /// through events, starting at `from`.
50        #[serde(skip_serializing_if = "Option::is_none")]
51        #[ruma_api(query)]
52        pub from: Option<String>,
53
54        /// The direction to return events from.
55        ///
56        /// Defaults to [`Direction::Backward`].
57        #[serde(default, skip_serializing_if = "ruma_common::serde::is_default")]
58        #[ruma_api(query)]
59        pub dir: Direction,
60
61        /// The pagination token to stop returning results at.
62        ///
63        /// If `None`, results continue up to `limit` or until there are no more events.
64        ///
65        /// Like `from`, this can be a previous token from a prior call to this endpoint
66        /// or from `/messages` or `/sync`.
67        #[serde(skip_serializing_if = "Option::is_none")]
68        #[ruma_api(query)]
69        pub to: Option<String>,
70
71        /// The maximum number of results to return in a single `chunk`.
72        ///
73        /// The server can and should apply a maximum value to this parameter to avoid large
74        /// responses.
75        ///
76        /// Similarly, the server should apply a default value when not supplied.
77        #[serde(skip_serializing_if = "Option::is_none")]
78        #[ruma_api(query)]
79        pub limit: Option<UInt>,
80
81        /// Whether to include events which relate indirectly to the given event.
82        ///
83        /// These are events related to the given event via two or more direct relationships.
84        ///
85        /// It is recommended that homeservers traverse at least 3 levels of relationships.
86        /// Implementations may perform more but should be careful to not infinitely recurse.
87        ///
88        /// Default to `false`.
89        #[serde(default, skip_serializing_if = "ruma_common::serde::is_default")]
90        #[ruma_api(query)]
91        pub recurse: bool,
92    }
93
94    /// Response type for the `get_relating_events` endpoint.
95    #[response(error = crate::Error)]
96    pub struct Response {
97        /// The paginated child events which point to the parent.
98        ///
99        /// The events returned are ordered topologically, most-recent first.
100        ///
101        /// If no events are related to the parent or the pagination yields no results, an
102        /// empty `chunk` is returned.
103        pub chunk: Vec<Raw<AnyMessageLikeEvent>>,
104
105        /// An opaque string representing a pagination token.
106        ///
107        /// If this is `None`, there are no more results to fetch and the client should stop
108        /// paginating.
109        #[serde(skip_serializing_if = "Option::is_none")]
110        pub next_batch: Option<String>,
111
112        /// An opaque string representing a pagination token.
113        ///
114        /// If this is `None`, this is the start of the result set, i.e. this is the first
115        /// batch/page.
116        #[serde(skip_serializing_if = "Option::is_none")]
117        pub prev_batch: Option<String>,
118
119        /// If `recurse` was set on the request, the depth to which the server recursed.
120        ///
121        /// If `recurse` was not set, this field must be absent.
122        #[serde(skip_serializing_if = "Option::is_none")]
123        pub recursion_depth: Option<UInt>,
124    }
125
126    impl Request {
127        /// Creates a new `Request` with the given room ID and parent event ID.
128        pub fn new(room_id: OwnedRoomId, event_id: OwnedEventId) -> Self {
129            Self {
130                room_id,
131                event_id,
132                dir: Direction::default(),
133                from: None,
134                to: None,
135                limit: None,
136                recurse: false,
137            }
138        }
139    }
140
141    impl Response {
142        /// Creates a new `Response` with the given chunk.
143        pub fn new(chunk: Vec<Raw<AnyMessageLikeEvent>>) -> Self {
144            Self { chunk, next_batch: None, prev_batch: None, recursion_depth: None }
145        }
146    }
147}
ruma_client_api/relations/get_relating_events.rs

ruma_client_api/relations/
get_relating_events.rs
