ruma_events/room/
image_pack.rs

1//! Types for [`m.room.image_pack`] event.
2//!
3//! [`m.room.image_pack`]: https://spec.matrix.org/v1.19/client-server-api/#mroomimage_pack
4
5use std::collections::{BTreeMap, BTreeSet};
6
7use ruma_common::OwnedMxcUri;
8use ruma_macros::{EventContent, StringEnum};
9use serde::{Deserialize, Serialize};
10
11use crate::{PrivOwnedStr, room::ImageInfo};
12
13/// The content of an [`m.room.image_pack`] event.
14///
15/// The state key is the unique identifier for the image pack.
16///
17/// [`m.room.image_pack`]: https://spec.matrix.org/v1.19/client-server-api/#mroomimage_pack
18#[derive(Clone, Debug, Default, Deserialize, Serialize, EventContent)]
19#[cfg_attr(not(ruma_unstable_exhaustive_types), non_exhaustive)]
20#[ruma_event(type = "m.room.image_pack", kind = State, state_key_type = String)]
21pub struct RoomImagePackEventContent {
22    /// A map from a shortcode to an image object.
23    ///
24    /// Each entry defines one image available in this pack.
25    pub images: BTreeMap<String, ImagePackImage>,
26
27    /// Metadata about the image pack as a whole.
28    ///
29    /// This field is not serialized if it is empty, and deserializes to its default value if it is
30    /// missing.
31    #[serde(default, skip_serializing_if = "ImagePackMeta::is_empty")]
32    pub pack: ImagePackMeta,
33}
34
35impl RoomImagePackEventContent {
36    /// Creates a new `RoomImagePackEventContent` with a list of images.
37    pub fn new(images: BTreeMap<String, ImagePackImage>) -> Self {
38        Self { images, pack: ImagePackMeta::default() }
39    }
40}
41
42/// An image object in an image pack.
43#[derive(Clone, Debug, Deserialize, Serialize)]
44#[cfg_attr(not(ruma_unstable_exhaustive_types), non_exhaustive)]
45pub struct ImagePackImage {
46    /// The MXC URI to the media file.
47    pub url: OwnedMxcUri,
48
49    /// An optional text body for this image.
50    ///
51    /// Useful for the sticker body text or the emote alt text.
52    ///
53    /// Defaults to the shortcode.
54    #[serde(skip_serializing_if = "Option::is_none")]
55    pub body: Option<String>,
56
57    /// The [ImageInfo] object used for the `info` block of `m.sticker` events.
58    #[serde(skip_serializing_if = "Option::is_none")]
59    pub info: Option<ImageInfo>,
60}
61
62impl ImagePackImage {
63    /// Creates a new `ImagePackImage` with the given MXC URI to the media file.
64    pub fn new(url: OwnedMxcUri) -> Self {
65        Self { url, body: None, info: None }
66    }
67}
68
69/// Details about an image pack.
70#[derive(Clone, Debug, Default, Deserialize, Serialize)]
71#[cfg_attr(not(ruma_unstable_exhaustive_types), non_exhaustive)]
72pub struct ImagePackMeta {
73    /// A display name for the pack.
74    ///
75    /// If absent and the pack is defined in a room, defaults to the room's name.
76    #[serde(skip_serializing_if = "Option::is_none")]
77    pub display_name: Option<String>,
78
79    /// The MXC URI of an avatar for the pack.
80    ///
81    /// If absent and the pack is defined in a room, defaults to the room's avatar.
82    #[serde(skip_serializing_if = "Option::is_none")]
83    pub avatar_url: Option<OwnedMxcUri>,
84
85    /// The intended usage(s) for this pack.
86    ///
87    /// If empty, all usage types are assumed.
88    #[serde(default, skip_serializing_if = "BTreeSet::is_empty")]
89    pub usage: BTreeSet<PackUsage>,
90
91    /// The attribution of this pack.
92    ///
93    /// For crediting the original author or source, for example.
94    #[serde(skip_serializing_if = "Option::is_none")]
95    pub attribution: Option<String>,
96}
97
98impl ImagePackMeta {
99    /// Creates a new empty `ImagePackMeta`.
100    pub fn new() -> Self {
101        Self::default()
102    }
103
104    /// Whether this `ImagePackMeta` is empty.
105    fn is_empty(&self) -> bool {
106        let Self { display_name, avatar_url, usage, attribution } = self;
107        display_name.is_none() && avatar_url.is_none() && usage.is_empty() && attribution.is_none()
108    }
109}
110
111/// The intended usages for an image pack.
112#[doc = include_str!(concat!(env!("CARGO_MANIFEST_DIR"), "/src/doc/string_enum.md"))]
113#[derive(Clone, StringEnum)]
114#[ruma_enum(rename_all = "snake_case")]
115#[non_exhaustive]
116pub enum PackUsage {
117    /// The images are intended to be sent inline in messages.
118    Emoticon,
119
120    /// The images are intended to be sent as standalone sticker events.
121    Sticker,
122
123    #[doc(hidden)]
124    _Custom(PrivOwnedStr),
125}
ruma_events/room/image_pack.rs

ruma_events/room/
image_pack.rs
