events: Add filename and formatted fields to media messages

For MSC2530 media captions

crates/ruma-events/CHANGELOG.md

@@ -22,6 +22,7 @@ Improvements:
 - Add unstable support for manually marking rooms as unread through [MSC2867](https://github.com/matrix-org/matrix-spec-proposals/pull/2867) 
   and the room account data `m.marked_unread` event (unstable type `com.famedly.marked_unread`)
 - Implement `From<JoinRule>` for `SpaceRoomJoinRule`
+- Add `filename` and `formatted` fields to media event contents to support media captions as per [MSC2530](https://github.com/matrix-org/matrix-spec-proposals/pull/2530)
 
 # 0.27.11
 

crates/ruma-events/src/room/message/audio.rs

@@ -4,6 +4,7 @@ use js_int::UInt;
 use ruma_common::OwnedMxcUri;
 use serde::{Deserialize, Serialize};
 
+use super::FormattedBody;
 use crate::room::{EncryptedFile, MediaSource};
 
 /// The payload for an audio message.
@@ -12,8 +13,19 @@ use crate::room::{EncryptedFile, MediaSource};
 #[serde(tag = "msgtype", rename = "m.audio")]
 pub struct AudioMessageEventContent {
     /// The textual representation of this message.
+    ///
+    /// If the `filename` field is not set or has the same value, this is the filename of the
+    /// uploaded file. Otherwise, this should be interpreted as a user-written media caption.
     pub body: String,
 
+    /// Formatted form of the message `body`, if `body` is a caption.
+    #[serde(flatten)]
+    pub formatted: Option<FormattedBody>,
+
+    /// The original filename of the uploaded file.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub filename: Option<String>,
+
     /// The source of the audio clip.
     #[serde(flatten)]
     pub source: MediaSource,
@@ -44,6 +56,8 @@ impl AudioMessageEventContent {
     pub fn new(body: String, source: MediaSource) -> Self {
         Self {
             body,
+            formatted: None,
+            filename: None,
             source,
             info: None,
             #[cfg(feature = "unstable-msc3245-v1-compat")]
@@ -64,6 +78,24 @@ impl AudioMessageEventContent {
         Self::new(body, MediaSource::Encrypted(Box::new(file)))
     }
 
+    /// Creates a new `AudioMessageEventContent` from `self` with the `filename` field set to the
+    /// given value.
+    ///
+    /// Since the field is public, you can also assign to it directly. This method merely acts
+    /// as a shorthand for that, because it is very common to set this field.
+    pub fn filename(self, filename: impl Into<Option<String>>) -> Self {
+        Self { filename: filename.into(), ..self }
+    }
+
+    /// Creates a new `AudioMessageEventContent` from `self` with the `formatted` field set to the
+    /// given value.
+    ///
+    /// Since the field is public, you can also assign to it directly. This method merely acts
+    /// as a shorthand for that, because it is very common to set this field.
+    pub fn formatted(self, formatted: impl Into<Option<FormattedBody>>) -> Self {
+        Self { formatted: formatted.into(), ..self }
+    }
+
     /// Creates a new `AudioMessageEventContent` from `self` with the `info` field set to the given
     /// value.
     ///

crates/ruma-events/src/room/message/file.rs

@@ -2,6 +2,7 @@ use js_int::UInt;
 use ruma_common::OwnedMxcUri;
 use serde::{Deserialize, Serialize};
 
+use super::FormattedBody;
 use crate::room::{EncryptedFile, MediaSource, ThumbnailInfo};
 
 /// The payload for a file message.
@@ -11,9 +12,14 @@ use crate::room::{EncryptedFile, MediaSource, ThumbnailInfo};
 pub struct FileMessageEventContent {
     /// A human-readable description of the file.
     ///
-    /// This is recommended to be the filename of the original upload.
+    /// If the `filename` field is not set or has the same value, this is the filename of the
+    /// uploaded file. Otherwise, this should be interpreted as a user-written media caption.
     pub body: String,
 
+    /// Formatted form of the message `body`, if `body` is a caption.
+    #[serde(flatten)]
+    pub formatted: Option<FormattedBody>,
+
     /// The original filename of the uploaded file.
     #[serde(skip_serializing_if = "Option::is_none")]
     pub filename: Option<String>,
@@ -30,7 +36,7 @@ pub struct FileMessageEventContent {
 impl FileMessageEventContent {
     /// Creates a new `FileMessageEventContent` with the given body and source.
     pub fn new(body: String, source: MediaSource) -> Self {
-        Self { body, filename: None, source, info: None }
+        Self { body, formatted: None, filename: None, source, info: None }
     }
 
     /// Creates a new non-encrypted `FileMessageEventContent` with the given body and url.
@@ -53,6 +59,15 @@ impl FileMessageEventContent {
         Self { filename: filename.into(), ..self }
     }
 
+    /// Creates a new `FileMessageEventContent` from `self` with the `formatted` field set to the
+    /// given value.
+    ///
+    /// Since the field is public, you can also assign to it directly. This method merely acts
+    /// as a shorthand for that, because it is very common to set this field.
+    pub fn formatted(self, formatted: impl Into<Option<FormattedBody>>) -> Self {
+        Self { formatted: formatted.into(), ..self }
+    }
+
     /// Creates a new `FileMessageEventContent` from `self` with the `info` field set to the given
     /// value.
     ///

crates/ruma-events/src/room/message/image.rs

@@ -1,6 +1,7 @@
 use ruma_common::OwnedMxcUri;
 use serde::{Deserialize, Serialize};
 
+use super::FormattedBody;
 use crate::room::{EncryptedFile, ImageInfo, MediaSource};
 
 /// The payload for an image message.
@@ -10,10 +11,18 @@ use crate::room::{EncryptedFile, ImageInfo, MediaSource};
 pub struct ImageMessageEventContent {
     /// A textual representation of the image.
     ///
-    /// Could be the alt text of the image, the filename of the image, or some kind of content
-    /// description for accessibility e.g. "image attachment".
+    /// If the `filename` field is not set or has the same value, this is the filename of the
+    /// uploaded file. Otherwise, this should be interpreted as a user-written media caption.
     pub body: String,
 
+    /// Formatted form of the message `body`, if `body` is a caption.
+    #[serde(flatten)]
+    pub formatted: Option<FormattedBody>,
+
+    /// The original filename of the uploaded file.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub filename: Option<String>,
+
     /// The source of the image.
     #[serde(flatten)]
     pub source: MediaSource,
@@ -26,7 +35,7 @@ pub struct ImageMessageEventContent {
 impl ImageMessageEventContent {
     /// Creates a new `ImageMessageEventContent` with the given body and source.
     pub fn new(body: String, source: MediaSource) -> Self {
-        Self { body, source, info: None }
+        Self { body, formatted: None, filename: None, source, info: None }
     }
 
     /// Creates a new non-encrypted `ImageMessageEventContent` with the given body and url.
@@ -40,6 +49,24 @@ impl ImageMessageEventContent {
         Self::new(body, MediaSource::Encrypted(Box::new(file)))
     }
 
+    /// Creates a new `ImageMessageEventContent` from `self` with the `filename` field set to the
+    /// given value.
+    ///
+    /// Since the field is public, you can also assign to it directly. This method merely acts
+    /// as a shorthand for that, because it is very common to set this field.
+    pub fn filename(self, filename: impl Into<Option<String>>) -> Self {
+        Self { filename: filename.into(), ..self }
+    }
+
+    /// Creates a new `ImageMessageEventContent` from `self` with the `formatted` field set to the
+    /// given value.
+    ///
+    /// Since the field is public, you can also assign to it directly. This method merely acts
+    /// as a shorthand for that, because it is very common to set this field.
+    pub fn formatted(self, formatted: impl Into<Option<FormattedBody>>) -> Self {
+        Self { formatted: formatted.into(), ..self }
+    }
+
     /// Creates a new `ImageMessageEventContent` from `self` with the `info` field set to the given
     /// value.
     ///

crates/ruma-events/src/room/message/video.rs

@@ -4,6 +4,7 @@ use js_int::UInt;
 use ruma_common::OwnedMxcUri;
 use serde::{Deserialize, Serialize};
 
+use super::FormattedBody;
 use crate::room::{EncryptedFile, MediaSource, ThumbnailInfo};
 
 /// The payload for a video message.
@@ -11,10 +12,20 @@ use crate::room::{EncryptedFile, MediaSource, ThumbnailInfo};
 #[cfg_attr(not(feature = "unstable-exhaustive-types"), non_exhaustive)]
 #[serde(tag = "msgtype", rename = "m.video")]
 pub struct VideoMessageEventContent {
-    /// A description of the video, e.g. "Gangnam Style", or some kind of content description for
-    /// accessibility, e.g. "video attachment".
+    /// A description of the video.
+    ///
+    /// If the `filename` field is not set or has the same value, this is the filename of the
+    /// uploaded file. Otherwise, this should be interpreted as a user-written media caption.
     pub body: String,
 
+    /// Formatted form of the message `body`, if `body` is a caption.
+    #[serde(flatten)]
+    pub formatted: Option<FormattedBody>,
+
+    /// The original filename of the uploaded file.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub filename: Option<String>,
+
     /// The source of the video clip.
     #[serde(flatten)]
     pub source: MediaSource,
@@ -27,7 +38,7 @@ pub struct VideoMessageEventContent {
 impl VideoMessageEventContent {
     /// Creates a new `VideoMessageEventContent` with the given body and source.
     pub fn new(body: String, source: MediaSource) -> Self {
-        Self { body, source, info: None }
+        Self { body, formatted: None, filename: None, source, info: None }
     }
 
     /// Creates a new non-encrypted `VideoMessageEventContent` with the given body and url.
@@ -41,6 +52,24 @@ impl VideoMessageEventContent {
         Self::new(body, MediaSource::Encrypted(Box::new(file)))
     }
 
+    /// Creates a new `VideoMessageEventContent` from `self` with the `filename` field set to the
+    /// given value.
+    ///
+    /// Since the field is public, you can also assign to it directly. This method merely acts
+    /// as a shorthand for that, because it is very common to set this field.
+    pub fn filename(self, filename: impl Into<Option<String>>) -> Self {
+        Self { filename: filename.into(), ..self }
+    }
+
+    /// Creates a new `VideoMessageEventContent` from `self` with the `formatted` field set to the
+    /// given value.
+    ///
+    /// Since the field is public, you can also assign to it directly. This method merely acts
+    /// as a shorthand for that, because it is very common to set this field.
+    pub fn formatted(self, formatted: impl Into<Option<FormattedBody>>) -> Self {
+        Self { formatted: formatted.into(), ..self }
+    }
+
     /// Creates a new `VideoMessageEventContent` from `self` with the `info` field set to the given
     /// value.
     ///