ruma_events/room/message/
image.rs

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

ruma_events/room/message/
image.rs
