ruma_events/
location.rs

1//! Types for extensible location message events ([MSC3488]).
2//!
3//! [MSC3488]: https://github.com/matrix-org/matrix-spec-proposals/pull/3488
4
5use js_int::UInt;
6use ruma_macros::{EventContent, StringEnum};
7use serde::{Deserialize, Serialize};
8
9mod zoomlevel_serde;
10
11use ruma_common::MilliSecondsSinceUnixEpoch;
12
13use super::{message::TextContentBlock, room::message::Relation};
14use crate::PrivOwnedStr;
15
16/// The payload for an extensible location message.
17///
18/// This is the new primary type introduced in [MSC3488] and should only be sent in rooms with a
19/// version that supports it. See the documentation of the [`message`] module for more information.
20///
21/// [MSC3488]: https://github.com/matrix-org/matrix-spec-proposals/pull/3488
22/// [`message`]: super::message
23#[derive(Clone, Debug, Serialize, Deserialize, EventContent)]
24#[cfg_attr(not(ruma_unstable_exhaustive_types), non_exhaustive)]
25#[ruma_event(type = "m.location", kind = MessageLike, without_relation)]
26pub struct LocationEventContent {
27    /// The text representation of the message.
28    #[serde(rename = "org.matrix.msc1767.text")]
29    pub text: TextContentBlock,
30
31    /// The location info of the message.
32    #[serde(rename = "m.location")]
33    pub location: LocationContent,
34
35    /// The asset this message refers to.
36    #[serde(default, rename = "m.asset", skip_serializing_if = "ruma_common::serde::is_default")]
37    pub asset: AssetContent,
38
39    /// The timestamp this message refers to.
40    #[serde(rename = "m.ts", skip_serializing_if = "Option::is_none")]
41    pub ts: Option<MilliSecondsSinceUnixEpoch>,
42
43    /// Whether this message is automated.
44    #[cfg(feature = "unstable-msc3955")]
45    #[serde(
46        default,
47        skip_serializing_if = "ruma_common::serde::is_default",
48        rename = "org.matrix.msc1767.automated"
49    )]
50    pub automated: bool,
51
52    /// Information about related messages.
53    #[serde(
54        flatten,
55        skip_serializing_if = "Option::is_none",
56        deserialize_with = "crate::room::message::relation_serde::deserialize_relation"
57    )]
58    pub relates_to: Option<Relation<LocationEventContentWithoutRelation>>,
59}
60
61impl LocationEventContent {
62    /// Creates a new `LocationEventContent` with the given fallback representation and location.
63    pub fn new(text: TextContentBlock, location: LocationContent) -> Self {
64        Self {
65            text,
66            location,
67            asset: Default::default(),
68            ts: None,
69            #[cfg(feature = "unstable-msc3955")]
70            automated: false,
71            relates_to: None,
72        }
73    }
74
75    /// Creates a new `LocationEventContent` with the given plain text fallback representation and
76    /// location.
77    pub fn with_plain_text(plain_text: impl Into<String>, location: LocationContent) -> Self {
78        Self {
79            text: TextContentBlock::plain(plain_text),
80            location,
81            asset: Default::default(),
82            ts: None,
83            #[cfg(feature = "unstable-msc3955")]
84            automated: false,
85            relates_to: None,
86        }
87    }
88}
89
90/// Location content.
91#[derive(Clone, Debug, Serialize, Deserialize)]
92#[cfg_attr(not(ruma_unstable_exhaustive_types), non_exhaustive)]
93pub struct LocationContent {
94    /// A `geo:` URI representing the location.
95    ///
96    /// See [RFC 5870](https://datatracker.ietf.org/doc/html/rfc5870) for more details.
97    pub uri: String,
98
99    /// The description of the location.
100    ///
101    /// It should be used to label the location on a map.
102    #[serde(skip_serializing_if = "Option::is_none")]
103    pub description: Option<String>,
104
105    /// A zoom level to specify the displayed area size.
106    #[serde(skip_serializing_if = "Option::is_none")]
107    pub zoom_level: Option<ZoomLevel>,
108}
109
110impl LocationContent {
111    /// Creates a new `LocationContent` with the given geo URI.
112    pub fn new(uri: String) -> Self {
113        Self { uri, description: None, zoom_level: None }
114    }
115}
116
117/// An error encountered when trying to convert to a `ZoomLevel`.
118#[derive(Copy, Clone, Debug, Eq, Hash, PartialEq, thiserror::Error)]
119#[non_exhaustive]
120pub enum ZoomLevelError {
121    /// The value is higher than [`ZoomLevel::MAX`].
122    #[error("value too high")]
123    TooHigh,
124}
125
126/// A zoom level.
127///
128/// This is an integer between 0 and 20 as defined in the [OpenStreetMap Wiki].
129///
130/// [OpenStreetMap Wiki]: https://wiki.openstreetmap.org/wiki/Zoom_levels
131#[derive(Clone, Debug, Serialize)]
132pub struct ZoomLevel(UInt);
133
134impl ZoomLevel {
135    /// The smallest value of a `ZoomLevel`, 0.
136    pub const MIN: u8 = 0;
137
138    /// The largest value of a `ZoomLevel`, 20.
139    pub const MAX: u8 = 20;
140
141    /// Creates a new `ZoomLevel` with the given value.
142    pub fn new(value: u8) -> Option<Self> {
143        if value > Self::MAX {
144            None
145        } else {
146            Some(Self(value.into()))
147        }
148    }
149
150    /// The value of this `ZoomLevel`.
151    pub fn get(&self) -> UInt {
152        self.0
153    }
154}
155
156impl TryFrom<u8> for ZoomLevel {
157    type Error = ZoomLevelError;
158
159    fn try_from(value: u8) -> Result<Self, Self::Error> {
160        Self::new(value).ok_or(ZoomLevelError::TooHigh)
161    }
162}
163
164/// Asset content.
165#[derive(Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
166#[cfg_attr(not(ruma_unstable_exhaustive_types), non_exhaustive)]
167pub struct AssetContent {
168    /// The type of asset being referred to.
169    #[serde(rename = "type")]
170    pub type_: AssetType,
171}
172
173impl AssetContent {
174    /// Creates a new default `AssetContent`.
175    pub fn new() -> Self {
176        Self::default()
177    }
178}
179
180/// The type of an asset.
181#[doc = include_str!(concat!(env!("CARGO_MANIFEST_DIR"), "/src/doc/string_enum.md"))]
182#[derive(Clone, Default, PartialEq, Eq, PartialOrd, Ord, StringEnum)]
183#[ruma_enum(rename_all = "m.snake_case")]
184#[non_exhaustive]
185pub enum AssetType {
186    /// The asset is the sender of the event.
187    #[default]
188    #[ruma_enum(rename = "m.self")]
189    Self_,
190
191    /// The asset is a location pinned by the sender.
192    Pin,
193
194    #[doc(hidden)]
195    _Custom(PrivOwnedStr),
196}
ruma_events/location.rs

ruma_events/
location.rs
