1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113
//! `GET /_matrix/client/*/rooms/{roomId}/threads`
//!
//! Retrieve a list of threads in a room, with optional filters.
pub mod v1 {
//! `/v1/` ([spec])
//!
//! [spec]: https://spec.matrix.org/latest/client-server-api/#get_matrixclientv1roomsroomidthreads
use js_int::UInt;
use ruma_common::{
api::{request, response, Metadata},
metadata,
serde::{Raw, StringEnum},
OwnedRoomId,
};
use ruma_events::AnyTimelineEvent;
use crate::PrivOwnedStr;
const METADATA: Metadata = metadata! {
method: GET,
rate_limited: true,
authentication: AccessToken,
history: {
unstable => "/_matrix/client/unstable/org.matrix.msc3856/rooms/:room_id/threads",
1.4 => "/_matrix/client/v1/rooms/:room_id/threads",
}
};
/// Request type for the `get_thread_roots` endpoint.
#[request(error = crate::Error)]
pub struct Request {
/// The room ID where the thread roots are located.
#[ruma_api(path)]
pub room_id: OwnedRoomId,
/// The pagination token to start returning results from.
///
/// If `None`, results start at the most recent topological event visible to the user.
#[serde(skip_serializing_if = "Option::is_none")]
#[ruma_api(query)]
pub from: Option<String>,
/// Which thread roots are of interest to the caller.
#[serde(skip_serializing_if = "ruma_common::serde::is_default")]
#[ruma_api(query)]
pub include: IncludeThreads,
/// The maximum number of results to return in a single `chunk`.
///
/// Servers should apply a default value, and impose a maximum value to avoid resource
/// exhaustion.
#[serde(skip_serializing_if = "Option::is_none")]
#[ruma_api(query)]
pub limit: Option<UInt>,
}
/// Response type for the `get_thread_roots` endpoint.
#[response(error = crate::Error)]
pub struct Response {
/// The thread roots, ordered by the `latest_event` in each event's aggregation bundle.
///
/// All events returned include bundled aggregations.
pub chunk: Vec<Raw<AnyTimelineEvent>>,
/// An opaque string to provide to `from` to keep paginating the responses.
///
/// If this is `None`, there are no more results to fetch and the client should stop
/// paginating.
#[serde(skip_serializing_if = "Option::is_none")]
pub next_batch: Option<String>,
}
impl Request {
/// Creates a new `Request` with the given room ID.
pub fn new(room_id: OwnedRoomId) -> Self {
Self { room_id, from: None, include: IncludeThreads::default(), limit: None }
}
}
impl Response {
/// Creates a new `Response` with the given chunk.
pub fn new(chunk: Vec<Raw<AnyTimelineEvent>>) -> Self {
Self { chunk, next_batch: None }
}
}
/// Which threads to include in the response.
#[doc = include_str!(concat!(env!("CARGO_MANIFEST_DIR"), "/src/doc/string_enum.md"))]
#[derive(Clone, Default, PartialEq, Eq, PartialOrd, Ord, StringEnum)]
#[ruma_enum(rename_all = "lowercase")]
#[non_exhaustive]
pub enum IncludeThreads {
/// `all`
///
/// Include all thread roots found in the room.
///
/// This is the default.
#[default]
All,
/// `participated`
///
/// Only include thread roots for threads where [`current_user_participated`] is `true`.
///
/// [`current_user_participated`]: https://spec.matrix.org/latest/client-server-api/#server-side-aggregation-of-mthread-relationships
Participated,
#[doc(hidden)]
_Custom(PrivOwnedStr),
}
}