ruma_events/room/message/
file.rs

1use js_int::UInt;
2use ruma_common::OwnedMxcUri;
3use serde::{Deserialize, Serialize};
4
5use super::FormattedBody;
6use crate::room::{
7    message::media_caption::{caption, formatted_caption},
8    EncryptedFile, MediaSource, ThumbnailInfo,
9};
10
11/// The payload for a file message.
12#[derive(Clone, Debug, Deserialize, Serialize)]
13#[cfg_attr(not(ruma_unstable_exhaustive_types), non_exhaustive)]
14#[serde(tag = "msgtype", rename = "m.file")]
15pub struct FileMessageEventContent {
16    /// A human-readable description of the file.
17    ///
18    /// If the `filename` field is not set or has the same value, this is the filename of the
19    /// uploaded file. Otherwise, this should be interpreted as a user-written media caption.
20    pub body: String,
21
22    /// Formatted form of the message `body`.
23    ///
24    /// This should only be set if the body represents a caption.
25    #[serde(flatten)]
26    pub formatted: Option<FormattedBody>,
27
28    /// The original filename of the uploaded file as deserialized from the event.
29    ///
30    /// It is recommended to use the `filename` method to get the filename which automatically
31    /// falls back to the `body` field when the `filename` field is not set.
32    #[serde(skip_serializing_if = "Option::is_none")]
33    pub filename: Option<String>,
34
35    /// The source of the file.
36    #[serde(flatten)]
37    pub source: MediaSource,
38
39    /// Metadata about the file referred to in `source`.
40    #[serde(skip_serializing_if = "Option::is_none")]
41    pub info: Option<Box<FileInfo>>,
42}
43
44impl FileMessageEventContent {
45    /// Creates a new `FileMessageEventContent` with the given body and source.
46    pub fn new(body: String, source: MediaSource) -> Self {
47        Self { body, formatted: None, filename: None, source, info: None }
48    }
49
50    /// Creates a new non-encrypted `FileMessageEventContent` with the given body and url.
51    pub fn plain(body: String, url: OwnedMxcUri) -> Self {
52        Self::new(body, MediaSource::Plain(url))
53    }
54
55    /// Creates a new encrypted `FileMessageEventContent` with the given body and encrypted
56    /// file.
57    pub fn encrypted(body: String, file: EncryptedFile) -> Self {
58        Self::new(body, MediaSource::Encrypted(Box::new(file)))
59    }
60
61    /// Creates a new `FileMessageEventContent` from `self` with the `info` field set to the given
62    /// value.
63    ///
64    /// Since the field is public, you can also assign to it directly. This method merely acts
65    /// as a shorthand for that, because it is very common to set this field.
66    pub fn info(self, info: impl Into<Option<Box<FileInfo>>>) -> Self {
67        Self { info: info.into(), ..self }
68    }
69
70    /// Computes the filename for the file as defined by the [spec](https://spec.matrix.org/latest/client-server-api/#media-captions).
71    ///
72    /// This differs from the `filename` field as this method falls back to the `body` field when
73    /// the `filename` field is not set.
74    pub fn filename(&self) -> &str {
75        self.filename.as_deref().unwrap_or(&self.body)
76    }
77
78    /// Returns the caption of the media file as defined by the [spec](https://spec.matrix.org/latest/client-server-api/#media-captions).
79    ///
80    /// In short, this is the `body` field if the `filename` field exists and has a different value,
81    /// otherwise the media file does not have a caption.
82    pub fn caption(&self) -> Option<&str> {
83        caption(&self.body, self.filename.as_deref())
84    }
85
86    /// Returns the formatted caption of the media file as defined by the [spec](https://spec.matrix.org/latest/client-server-api/#media-captions).
87    ///
88    /// This is the same as `caption`, but returns the formatted body instead of the plain body.
89    pub fn formatted_caption(&self) -> Option<&FormattedBody> {
90        formatted_caption(&self.body, self.formatted.as_ref(), self.filename.as_deref())
91    }
92}
93
94/// Metadata about a file.
95#[derive(Clone, Debug, Default, Deserialize, Serialize)]
96#[cfg_attr(not(ruma_unstable_exhaustive_types), non_exhaustive)]
97pub struct FileInfo {
98    /// The mimetype of the file, e.g. "application/msword".
99    #[serde(skip_serializing_if = "Option::is_none")]
100    pub mimetype: Option<String>,
101
102    /// The size of the file in bytes.
103    #[serde(skip_serializing_if = "Option::is_none")]
104    pub size: Option<UInt>,
105
106    /// Metadata about the image referred to in `thumbnail_source`.
107    #[serde(skip_serializing_if = "Option::is_none")]
108    pub thumbnail_info: Option<Box<ThumbnailInfo>>,
109
110    /// The source of the thumbnail of the file.
111    #[serde(
112        flatten,
113        with = "crate::room::thumbnail_source_serde",
114        skip_serializing_if = "Option::is_none"
115    )]
116    pub thumbnail_source: Option<MediaSource>,
117}
118
119impl FileInfo {
120    /// Creates an empty `FileInfo`.
121    pub fn new() -> Self {
122        Self::default()
123    }
124}
ruma_events/room/message/file.rs

ruma_events/room/message/
file.rs
