ruma_events/
image.rs

Help
1//! Types for extensible image message events ([MSC3552]).
2//!
3//! [MSC3552]: https://github.com/matrix-org/matrix-spec-proposals/pull/3552
4
5use std::ops::Deref;
6
7use js_int::UInt;
8use ruma_common::OwnedMxcUri;
9use ruma_macros::EventContent;
10use serde::{Deserialize, Serialize};
11
12use super::{
13    file::{CaptionContentBlock, EncryptedContent, FileContentBlock},
14    message::TextContentBlock,
15    room::message::Relation,
16};
17
18/// The payload for an extensible image message.
19///
20/// This is the new primary type introduced in [MSC3552] and should only be sent in rooms with a
21/// version that supports it. This type replaces both the `m.room.message` type with `msgtype:
22/// "m.image"` and the `m.sticker` type. To replace the latter, `sticker` must be set to `true` in
23/// `image_details`. See the documentation of the [`message`] module for more information.
24///
25/// [MSC3552]: https://github.com/matrix-org/matrix-spec-proposals/pull/3552
26/// [`message`]: super::message
27#[derive(Clone, Debug, Serialize, Deserialize, EventContent)]
28#[cfg_attr(not(ruma_unstable_exhaustive_types), non_exhaustive)]
29#[ruma_event(type = "org.matrix.msc1767.image", kind = MessageLike, without_relation)]
30pub struct ImageEventContent {
31    /// The text representation of the message.
32    #[serde(rename = "org.matrix.msc1767.text")]
33    pub text: TextContentBlock,
34
35    /// The file content of the message.
36    #[serde(rename = "org.matrix.msc1767.file")]
37    pub file: FileContentBlock,
38
39    /// The image details of the message, if any.
40    #[serde(rename = "org.matrix.msc1767.image_details", skip_serializing_if = "Option::is_none")]
41    pub image_details: Option<ImageDetailsContentBlock>,
42
43    /// The thumbnails of the message, if any.
44    ///
45    /// This is optional and defaults to an empty array.
46    #[serde(
47        rename = "org.matrix.msc1767.thumbnail",
48        default,
49        skip_serializing_if = "ThumbnailContentBlock::is_empty"
50    )]
51    pub thumbnail: ThumbnailContentBlock,
52
53    /// The caption of the message, if any.
54    #[serde(rename = "org.matrix.msc1767.caption", skip_serializing_if = "Option::is_none")]
55    pub caption: Option<CaptionContentBlock>,
56
57    /// The alternative text of the image, for accessibility considerations, if any.
58    #[serde(rename = "org.matrix.msc1767.alt_text", skip_serializing_if = "Option::is_none")]
59    pub alt_text: Option<AltTextContentBlock>,
60
61    /// Whether this message is automated.
62    #[cfg(feature = "unstable-msc3955")]
63    #[serde(
64        default,
65        skip_serializing_if = "ruma_common::serde::is_default",
66        rename = "org.matrix.msc1767.automated"
67    )]
68    pub automated: bool,
69
70    /// Information about related messages.
71    #[serde(
72        flatten,
73        skip_serializing_if = "Option::is_none",
74        deserialize_with = "crate::room::message::relation_serde::deserialize_relation"
75    )]
76    pub relates_to: Option<Relation<ImageEventContentWithoutRelation>>,
77}
78
79impl ImageEventContent {
80    /// Creates a new `ImageEventContent` with the given fallback representation and
81    /// file.
82    pub fn new(text: TextContentBlock, file: FileContentBlock) -> Self {
83        Self {
84            text,
85            file,
86            image_details: None,
87            thumbnail: Default::default(),
88            caption: None,
89            alt_text: None,
90            #[cfg(feature = "unstable-msc3955")]
91            automated: false,
92            relates_to: None,
93        }
94    }
95
96    /// Creates a new `ImageEventContent` with the given plain text fallback representation and
97    /// file.
98    pub fn with_plain_text(plain_text: impl Into<String>, file: FileContentBlock) -> Self {
99        Self {
100            text: TextContentBlock::plain(plain_text),
101            file,
102            image_details: None,
103            thumbnail: Default::default(),
104            caption: None,
105            alt_text: None,
106            #[cfg(feature = "unstable-msc3955")]
107            automated: false,
108            relates_to: None,
109        }
110    }
111}
112
113/// A block for details of image content.
114#[derive(Default, Clone, Debug, Serialize, Deserialize)]
115#[cfg_attr(not(ruma_unstable_exhaustive_types), non_exhaustive)]
116pub struct ImageDetailsContentBlock {
117    /// The height of the image in pixels.
118    pub height: UInt,
119
120    /// The width of the image in pixels.
121    pub width: UInt,
122
123    /// Whether the image should be presented as sticker.
124    #[serde(
125        rename = "org.matrix.msc1767.sticker",
126        default,
127        skip_serializing_if = "ruma_common::serde::is_default"
128    )]
129    pub sticker: bool,
130}
131
132impl ImageDetailsContentBlock {
133    /// Creates a new `ImageDetailsContentBlock` with the given width and height.
134    pub fn new(width: UInt, height: UInt) -> Self {
135        Self { height, width, sticker: Default::default() }
136    }
137}
138
139/// A block for thumbnail content.
140///
141/// This is an array of [`Thumbnail`].
142///
143/// To construct a `ThumbnailContentBlock` convert a `Vec<Thumbnail>` with
144/// `ThumbnailContentBlock::from()` / `.into()`.
145#[derive(Clone, Debug, Default, Serialize, Deserialize)]
146#[allow(clippy::exhaustive_structs)]
147pub struct ThumbnailContentBlock(Vec<Thumbnail>);
148
149impl ThumbnailContentBlock {
150    /// Whether this content block is empty.
151    pub fn is_empty(&self) -> bool {
152        self.0.is_empty()
153    }
154}
155
156impl From<Vec<Thumbnail>> for ThumbnailContentBlock {
157    fn from(thumbnails: Vec<Thumbnail>) -> Self {
158        Self(thumbnails)
159    }
160}
161
162impl FromIterator<Thumbnail> for ThumbnailContentBlock {
163    fn from_iter<T: IntoIterator<Item = Thumbnail>>(iter: T) -> Self {
164        Self(iter.into_iter().collect())
165    }
166}
167
168impl Deref for ThumbnailContentBlock {
169    type Target = [Thumbnail];
170
171    fn deref(&self) -> &Self::Target {
172        &self.0
173    }
174}
175
176/// Thumbnail content.
177#[derive(Clone, Debug, Deserialize, Serialize)]
178#[cfg_attr(not(ruma_unstable_exhaustive_types), non_exhaustive)]
179pub struct Thumbnail {
180    /// The file info of the thumbnail.
181    #[serde(rename = "org.matrix.msc1767.file")]
182    pub file: ThumbnailFileContentBlock,
183
184    /// The image info of the thumbnail.
185    #[serde(rename = "org.matrix.msc1767.image_details")]
186    pub image_details: ThumbnailImageDetailsContentBlock,
187}
188
189impl Thumbnail {
190    /// Creates a `Thumbnail` with the given file and image details.
191    pub fn new(
192        file: ThumbnailFileContentBlock,
193        image_details: ThumbnailImageDetailsContentBlock,
194    ) -> Self {
195        Self { file, image_details }
196    }
197}
198
199/// A block for thumbnail file content.
200#[derive(Clone, Debug, Serialize, Deserialize)]
201#[cfg_attr(not(ruma_unstable_exhaustive_types), non_exhaustive)]
202pub struct ThumbnailFileContentBlock {
203    /// The URL to the thumbnail.
204    pub url: OwnedMxcUri,
205
206    /// The mimetype of the file, e.g. "image/png".
207    pub mimetype: String,
208
209    /// The original filename of the uploaded file.
210    #[serde(skip_serializing_if = "Option::is_none")]
211    pub name: Option<String>,
212
213    /// The size of the file in bytes.
214    #[serde(skip_serializing_if = "Option::is_none")]
215    pub size: Option<UInt>,
216
217    /// Information on the encrypted thumbnail.
218    ///
219    /// Required if the thumbnail is encrypted.
220    #[serde(flatten, skip_serializing_if = "Option::is_none")]
221    pub encryption_info: Option<Box<EncryptedContent>>,
222}
223
224impl ThumbnailFileContentBlock {
225    /// Creates a new non-encrypted `ThumbnailFileContentBlock` with the given url and mimetype.
226    pub fn plain(url: OwnedMxcUri, mimetype: String) -> Self {
227        Self { url, mimetype, name: None, size: None, encryption_info: None }
228    }
229
230    /// Creates a new encrypted `ThumbnailFileContentBlock` with the given url, mimetype and
231    /// encryption info.
232    pub fn encrypted(
233        url: OwnedMxcUri,
234        mimetype: String,
235        encryption_info: EncryptedContent,
236    ) -> Self {
237        Self {
238            url,
239            mimetype,
240            name: None,
241            size: None,
242            encryption_info: Some(Box::new(encryption_info)),
243        }
244    }
245
246    /// Whether the thumbnail file is encrypted.
247    pub fn is_encrypted(&self) -> bool {
248        self.encryption_info.is_some()
249    }
250}
251
252/// A block for details of thumbnail image content.
253#[derive(Default, Clone, Debug, Serialize, Deserialize)]
254#[cfg_attr(not(ruma_unstable_exhaustive_types), non_exhaustive)]
255pub struct ThumbnailImageDetailsContentBlock {
256    /// The height of the image in pixels.
257    pub height: UInt,
258
259    /// The width of the image in pixels.
260    pub width: UInt,
261}
262
263impl ThumbnailImageDetailsContentBlock {
264    /// Creates a new `ThumbnailImageDetailsContentBlock` with the given width and height.
265    pub fn new(width: UInt, height: UInt) -> Self {
266        Self { height, width }
267    }
268}
269
270/// A block for alternative text content.
271///
272/// The content should only contain plain text messages. Non-plain text messages should be ignored.
273///
274/// To construct an `AltTextContentBlock` with a custom [`TextContentBlock`], convert it with
275/// `AltTextContentBlock::from()` / `.into()`.
276#[derive(Clone, Debug, Serialize, Deserialize)]
277#[cfg_attr(not(ruma_unstable_exhaustive_types), non_exhaustive)]
278pub struct AltTextContentBlock {
279    /// The alternative text.
280    #[serde(rename = "org.matrix.msc1767.text")]
281    pub text: TextContentBlock,
282}
283
284impl AltTextContentBlock {
285    /// A convenience constructor to create a plain text alternative text content block.
286    pub fn plain(body: impl Into<String>) -> Self {
287        Self { text: TextContentBlock::plain(body) }
288    }
289}
290
291impl From<TextContentBlock> for AltTextContentBlock {
292    fn from(text: TextContentBlock) -> Self {
293        Self { text }
294    }
295}
ruma_events/image.rs

ruma_events/
image.rs
