ruma_client_api/room/
create_room.rs

1//! `POST /_matrix/client/*/createRoom`
2//!
3//! Create a new room.
4
5pub mod v3 {
6    //! `/v3/` ([spec])
7    //!
8    //! [spec]: https://spec.matrix.org/latest/client-server-api/#post_matrixclientv3createroom
9
10    use assign::assign;
11    use ruma_common::{
12        api::{request, response, Metadata},
13        metadata,
14        room::RoomType,
15        serde::{Raw, StringEnum},
16        OwnedRoomId, OwnedUserId, RoomVersionId,
17    };
18    use ruma_events::{
19        room::{
20            create::{PreviousRoom, RoomCreateEventContent},
21            power_levels::RoomPowerLevelsEventContent,
22        },
23        AnyInitialStateEvent,
24    };
25    use serde::{Deserialize, Serialize};
26
27    use crate::{membership::Invite3pid, room::Visibility, PrivOwnedStr};
28
29    const METADATA: Metadata = metadata! {
30        method: POST,
31        rate_limited: false,
32        authentication: AccessToken,
33        history: {
34            1.0 => "/_matrix/client/r0/createRoom",
35            1.1 => "/_matrix/client/v3/createRoom",
36        }
37    };
38
39    /// Request type for the `create_room` endpoint.
40    #[request(error = crate::Error)]
41    #[derive(Default)]
42    pub struct Request {
43        /// Extra keys to be added to the content of the `m.room.create`.
44        #[serde(default, skip_serializing_if = "Option::is_none")]
45        pub creation_content: Option<Raw<CreationContent>>,
46
47        /// List of state events to send to the new room.
48        ///
49        /// Takes precedence over events set by preset, but gets overridden by name and topic keys.
50        #[serde(default, skip_serializing_if = "<[_]>::is_empty")]
51        pub initial_state: Vec<Raw<AnyInitialStateEvent>>,
52
53        /// A list of user IDs to invite to the room.
54        ///
55        /// This will tell the server to invite everyone in the list to the newly created room.
56        #[serde(default, skip_serializing_if = "<[_]>::is_empty")]
57        pub invite: Vec<OwnedUserId>,
58
59        /// List of third party IDs of users to invite.
60        #[serde(default, skip_serializing_if = "<[_]>::is_empty")]
61        pub invite_3pid: Vec<Invite3pid>,
62
63        /// If set, this sets the `is_direct` flag on room invites.
64        #[serde(default, skip_serializing_if = "ruma_common::serde::is_default")]
65        pub is_direct: bool,
66
67        /// If this is included, an `m.room.name` event will be sent into the room to indicate the
68        /// name of the room.
69        #[serde(skip_serializing_if = "Option::is_none")]
70        pub name: Option<String>,
71
72        /// Power level content to override in the default power level event.
73        #[serde(skip_serializing_if = "Option::is_none")]
74        pub power_level_content_override: Option<Raw<RoomPowerLevelsEventContent>>,
75
76        /// Convenience parameter for setting various default state events based on a preset.
77        #[serde(skip_serializing_if = "Option::is_none")]
78        pub preset: Option<RoomPreset>,
79
80        /// The desired room alias local part.
81        #[serde(skip_serializing_if = "Option::is_none")]
82        pub room_alias_name: Option<String>,
83
84        /// Room version to set for the room.
85        ///
86        /// Defaults to homeserver's default if not specified.
87        #[serde(skip_serializing_if = "Option::is_none")]
88        pub room_version: Option<RoomVersionId>,
89
90        /// If this is included, an `m.room.topic` event will be sent into the room to indicate
91        /// the topic for the room.
92        #[serde(skip_serializing_if = "Option::is_none")]
93        pub topic: Option<String>,
94
95        /// A public visibility indicates that the room will be shown in the published room list.
96        ///
97        /// A private visibility will hide the room from the published room list. Defaults to
98        /// `Private`.
99        #[serde(default, skip_serializing_if = "ruma_common::serde::is_default")]
100        pub visibility: Visibility,
101    }
102
103    /// Response type for the `create_room` endpoint.
104    #[response(error = crate::Error)]
105    pub struct Response {
106        /// The created room's ID.
107        pub room_id: OwnedRoomId,
108    }
109
110    impl Request {
111        /// Creates a new `Request` will all-default parameters.
112        pub fn new() -> Self {
113            Default::default()
114        }
115    }
116
117    impl Response {
118        /// Creates a new `Response` with the given room id.
119        pub fn new(room_id: OwnedRoomId) -> Self {
120            Self { room_id }
121        }
122    }
123
124    /// Extra options to be added to the `m.room.create` event.
125    ///
126    /// This is the same as the event content struct for `m.room.create`, but without some fields
127    /// that servers are supposed to ignore.
128    #[derive(Clone, Debug, Deserialize, Serialize)]
129    #[cfg_attr(not(ruma_unstable_exhaustive_types), non_exhaustive)]
130    pub struct CreationContent {
131        /// Whether users on other servers can join this room.
132        ///
133        /// Defaults to `true` if key does not exist.
134        #[serde(
135            rename = "m.federate",
136            default = "ruma_common::serde::default_true",
137            skip_serializing_if = "ruma_common::serde::is_true"
138        )]
139        pub federate: bool,
140
141        /// A reference to the room this room replaces, if the previous room was upgraded.
142        #[serde(skip_serializing_if = "Option::is_none")]
143        pub predecessor: Option<PreviousRoom>,
144
145        /// The room type.
146        ///
147        /// This is currently only used for spaces.
148        #[serde(skip_serializing_if = "Option::is_none", rename = "type")]
149        pub room_type: Option<RoomType>,
150    }
151
152    impl CreationContent {
153        /// Creates a new `CreationContent` with all fields defaulted.
154        pub fn new() -> Self {
155            Self { federate: true, predecessor: None, room_type: None }
156        }
157
158        /// Given a `CreationContent` and the other fields that a homeserver has to fill, construct
159        /// a `RoomCreateEventContent`.
160        pub fn into_event_content(
161            self,
162            creator: OwnedUserId,
163            room_version: RoomVersionId,
164        ) -> RoomCreateEventContent {
165            assign!(RoomCreateEventContent::new_v1(creator), {
166                federate: self.federate,
167                room_version: room_version,
168                predecessor: self.predecessor,
169                room_type: self.room_type
170            })
171        }
172
173        /// Returns whether all fields have their default value.
174        pub fn is_empty(&self) -> bool {
175            self.federate && self.predecessor.is_none() && self.room_type.is_none()
176        }
177    }
178
179    impl Default for CreationContent {
180        fn default() -> Self {
181            Self::new()
182        }
183    }
184
185    /// A convenience parameter for setting a few default state events.
186    #[doc = include_str!(concat!(env!("CARGO_MANIFEST_DIR"), "/src/doc/string_enum.md"))]
187    #[derive(Clone, PartialEq, Eq, StringEnum)]
188    #[ruma_enum(rename_all = "snake_case")]
189    #[non_exhaustive]
190    pub enum RoomPreset {
191        /// `join_rules` is set to `invite` and `history_visibility` is set to `shared`.
192        PrivateChat,
193
194        /// `join_rules` is set to `public` and `history_visibility` is set to `shared`.
195        PublicChat,
196
197        /// Same as `PrivateChat`, but all initial invitees get the same power level as the
198        /// creator.
199        TrustedPrivateChat,
200
201        #[doc(hidden)]
202        _Custom(PrivOwnedStr),
203    }
204}
ruma_client_api/room/create_room.rs

ruma_client_api/room/
create_room.rs
