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