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