ruma_client_api/peeking/
listen_to_new_events.rs

1//! `GET /_matrix/client/*/events`
2//!
3//! Listen for new events related to a particular room.
4
5pub mod v3 {
6    //! `/v3/` ([spec])
7    //!
8    //! [spec]: https://spec.matrix.org/v1.19/client-server-api/#peeking_get_matrixclientv3events
9
10    use std::time::Duration;
11
12    use ruma_common::{
13        OwnedRoomId,
14        api::{auth_scheme::AccessToken, request, response},
15        metadata,
16        serde::Raw,
17    };
18    use ruma_events::AnyTimelineEvent;
19
20    metadata! {
21        method: GET,
22        rate_limited: false,
23        authentication: AccessToken,
24        history: {
25            1.0 => "/_matrix/client/r0/events",
26            1.1 => "/_matrix/client/v3/events",
27        }
28    }
29
30    /// Request type for the `listen_to_new_events` endpoint.
31    #[request]
32    pub struct Request {
33        /// The token to stream from.
34        ///
35        /// This token is either from a previous request to this API or from the initial sync API.
36        #[ruma_api(query)]
37        #[serde(skip_serializing_if = "Option::is_none")]
38        pub from: Option<String>,
39
40        /// The room ID for which events should be returned.
41        #[ruma_api(query)]
42        pub room_id: OwnedRoomId,
43
44        /// The maximum time to wait for an event.
45        #[ruma_api(query)]
46        #[serde(
47            with = "ruma_common::serde::duration::opt_ms",
48            default,
49            skip_serializing_if = "Option::is_none"
50        )]
51        pub timeout: Option<Duration>,
52    }
53
54    impl Request {
55        /// Creates a `Request` for the given room.
56        pub fn new(room_id: OwnedRoomId) -> Self {
57            Self { from: None, room_id, timeout: None }
58        }
59    }
60
61    /// Response type for the `listen_to_new_events` endpoint.
62    #[response]
63    #[derive(Default)]
64    pub struct Response {
65        /// An array of new events.
66        #[serde(default, skip_serializing_if = "Vec::is_empty")]
67        pub chunk: Vec<Raw<AnyTimelineEvent>>,
68
69        /// A token which correlates to the last value in `chunk`.
70        ///
71        /// This token should be used in the next request to this endpoint.
72        #[serde(skip_serializing_if = "Option::is_none")]
73        pub end: Option<String>,
74
75        /// A token which correlates to the first value in `chunk`.
76        ///
77        /// This is usually the same token supplied to `from` in the request.
78        #[serde(skip_serializing_if = "Option::is_none")]
79        pub start: Option<String>,
80    }
81
82    impl Response {
83        /// Creates an empty `Response`.
84        pub fn new() -> Self {
85            Self::default()
86        }
87    }
88}
ruma_client_api/peeking/listen_to_new_events.rs

ruma_client_api/peeking/
listen_to_new_events.rs
