deltachat/param.rs
1use std::collections::BTreeMap;
2use std::fmt;
3use std::path::PathBuf;
4use std::str;
5
6use anyhow::ensure;
7use anyhow::{bail, Error, Result};
8use num_traits::FromPrimitive;
9use serde::{Deserialize, Serialize};
10
11use crate::blob::BlobObject;
12use crate::context::Context;
13use crate::mimeparser::SystemMessage;
14
15/// Available param keys.
16#[derive(
17 PartialEq, Eq, Debug, Clone, Copy, Hash, PartialOrd, Ord, FromPrimitive, Serialize, Deserialize,
18)]
19#[repr(u8)]
20pub enum Param {
21 /// For messages
22 File = b'f',
23
24 /// For messages: original filename (as shown in chat)
25 Filename = b'v',
26
27 /// For messages: This name should be shown instead of contact.get_display_name()
28 /// (used if this is a mailinglist
29 /// or explicitly set using set_override_sender_name(), eg. by bots)
30 OverrideSenderDisplayname = b'O',
31
32 /// For Messages
33 Width = b'w',
34
35 /// For Messages
36 Height = b'h',
37
38 /// For Messages
39 Duration = b'd',
40
41 /// For Messages
42 MimeType = b'm',
43
44 /// For Messages: HTML to be written to the database and to be send.
45 /// `SendHtml` param is not used for received messages.
46 /// Use `MsgId::get_html()` to get HTML of received messages.
47 SendHtml = b'T',
48
49 /// For Messages: message is encrypted, outgoing: guarantee E2EE or the message is not send
50 GuaranteeE2ee = b'c',
51
52 /// For Messages: quoted message is encrypted.
53 ///
54 /// If this message is sent unencrypted, quote text should be replaced.
55 ProtectQuote = b'0',
56
57 /// For Messages: decrypted with validation errors or without mutual set, if neither
58 /// 'c' nor 'e' are preset, the messages is only transport encrypted.
59 ///
60 /// Deprecated on 2024-12-25.
61 ErroneousE2ee = b'e',
62
63 /// For Messages: force unencrypted message, a value from `ForcePlaintext` enum.
64 ForcePlaintext = b'u',
65
66 /// For Messages: do not include Autocrypt header.
67 SkipAutocrypt = b'o',
68
69 /// For Messages
70 WantsMdn = b'r',
71
72 /// For Messages: the message is a reaction.
73 Reaction = b'x',
74
75 /// For Chats: the timestamp of the last reaction.
76 LastReactionTimestamp = b'y',
77
78 /// For Chats: Message ID of the last reaction.
79 LastReactionMsgId = b'Y',
80
81 /// For Chats: Contact ID of the last reaction.
82 LastReactionContactId = b'1',
83
84 /// For Messages: a message with "Auto-Submitted: auto-generated" header ("bot").
85 Bot = b'b',
86
87 /// For Messages: unset or 0=not forwarded,
88 /// 1=forwarded from unknown msg_id, >9 forwarded from msg_id
89 Forwarded = b'a',
90
91 /// For Messages: quoted text.
92 Quote = b'q',
93
94 /// For Messages: the 1st part of summary text (i.e. before the dash if any).
95 Summary1 = b'4',
96
97 /// For Messages
98 Cmd = b'S',
99
100 /// For Messages
101 Arg = b'E',
102
103 /// For Messages
104 Arg2 = b'F',
105
106 /// `Secure-Join-Fingerprint` header for `{vc,vg}-request-with-auth` messages.
107 Arg3 = b'G',
108
109 /// Deprecated `Secure-Join-Group` header for messages.
110 Arg4 = b'H',
111
112 /// For Messages
113 AttachGroupImage = b'A',
114
115 /// For Messages
116 WebrtcRoom = b'V',
117
118 /// For Messages: space-separated list of messaged IDs of forwarded copies.
119 ///
120 /// This is used when a [crate::message::Message] is in the
121 /// [crate::message::MessageState::OutPending] state but is already forwarded.
122 /// In this case the forwarded messages are written to the
123 /// database and their message IDs are added to this parameter of
124 /// the original message, which is also saved in the database.
125 /// When the original message is then finally sent this parameter
126 /// is used to also send all the forwarded messages.
127 PrepForwards = b'P',
128
129 /// For Messages
130 SetLatitude = b'l',
131
132 /// For Messages
133 SetLongitude = b'n',
134
135 /// For Groups
136 ///
137 /// An unpromoted group has not had any messages sent to it and thus only exists on the
138 /// creator's device. Any changes made to an unpromoted group do not need to send
139 /// system messages to the group members to update them of the changes. Once a message
140 /// has been sent to a group it is promoted and group changes require sending system
141 /// messages to all members.
142 Unpromoted = b'U',
143
144 /// For Groups and Contacts
145 ProfileImage = b'i',
146
147 /// For Chats
148 /// Signals whether the chat is the `saved messages` chat
149 Selftalk = b'K',
150
151 /// For Chats: On sending a new message we set the subject to `Re: <last subject>`.
152 /// Usually we just use the subject of the parent message, but if the parent message
153 /// is deleted, we use the LastSubject of the chat.
154 LastSubject = b't',
155
156 /// For Chats
157 Devicetalk = b'D',
158
159 /// For Chats: If this is a mailing list chat, contains the List-Post address.
160 /// None if there simply is no `List-Post` header in the mailing list.
161 /// Some("") if the mailing list is using multiple different List-Post headers.
162 ///
163 /// The List-Post address is the email address where the user can write to in order to
164 /// post something to the mailing list.
165 ListPost = b'p',
166
167 /// For Contacts: If this is the List-Post address of a mailing list, contains
168 /// the List-Id of the mailing list (which is also used as the group id of the chat).
169 ListId = b's',
170
171 /// For Contacts: timestamp of status (aka signature or footer) update.
172 StatusTimestamp = b'j',
173
174 /// For Contacts and Chats: timestamp of avatar update.
175 AvatarTimestamp = b'J',
176
177 /// For Chats: timestamp of status/signature/footer update.
178 EphemeralSettingsTimestamp = b'B',
179
180 /// For Chats: timestamp of subject update.
181 SubjectTimestamp = b'C',
182
183 /// For Chats: timestamp of group name update.
184 GroupNameTimestamp = b'g',
185
186 /// For Chats: timestamp of member list update.
187 MemberListTimestamp = b'k',
188
189 /// For Webxdc Message Instances: Current document name
190 WebxdcDocument = b'R',
191
192 /// For Webxdc Message Instances: timestamp of document name update.
193 WebxdcDocumentTimestamp = b'W',
194
195 /// For Webxdc Message Instances: Current summary
196 WebxdcSummary = b'N',
197
198 /// For Webxdc Message Instances: timestamp of summary update.
199 WebxdcSummaryTimestamp = b'Q',
200
201 /// For Webxdc Message Instances: Webxdc is an integration, see init_webxdc_integration()
202 WebxdcIntegration = b'3',
203
204 /// For Webxdc Message Instances: Chat to integrate the Webxdc for.
205 WebxdcIntegrateFor = b'2',
206
207 /// For messages: Whether [crate::message::Viewtype::Sticker] should be forced.
208 ForceSticker = b'X',
209
210 /// For messages: Message is a deletion request. The value is a list of rfc724_mid of the messages to delete.
211 DeleteRequestFor = b'M',
212
213 /// For messages: Message is a text edit message. the value of this parameter is the rfc724_mid of the original message.
214 TextEditFor = b'I',
215
216 /// For messages: Message text was edited.
217 IsEdited = b'L',
218
219 /// For info messages: Contact ID in added or removed to a group.
220 ContactAddedRemoved = b'5',
221}
222
223/// An object for handling key=value parameter lists.
224///
225/// The structure is serialized by calling `to_string()` on it.
226///
227/// Only for library-internal use.
228#[derive(Debug, Clone, PartialEq, Eq, Default, Serialize, Deserialize)]
229pub struct Params {
230 inner: BTreeMap<Param, String>,
231}
232
233impl fmt::Display for Params {
234 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
235 for (i, (key, value)) in self.inner.iter().enumerate() {
236 if i > 0 {
237 writeln!(f)?;
238 }
239 write!(
240 f,
241 "{}={}",
242 *key as u8 as char,
243 value.split('\n').collect::<Vec<&str>>().join("\n\n")
244 )?;
245 }
246 Ok(())
247 }
248}
249
250impl str::FromStr for Params {
251 type Err = Error;
252
253 /// Parse a raw string to Param.
254 ///
255 /// Silently ignore unknown keys:
256 /// they may come from a downgrade (when a shortly new version adds a key)
257 /// or from an upgrade (when a key is dropped but was used in the past)
258 fn from_str(s: &str) -> std::result::Result<Self, Self::Err> {
259 let mut inner = BTreeMap::new();
260 let mut lines = s.lines().peekable();
261
262 while let Some(line) = lines.next() {
263 if let [key, value] = line.splitn(2, '=').collect::<Vec<_>>()[..] {
264 let key = key.to_string();
265 let mut value = value.to_string();
266 while let Some(s) = lines.peek() {
267 if !s.is_empty() {
268 break;
269 }
270 lines.next();
271 value.push('\n');
272 value += lines.next().unwrap_or_default();
273 }
274
275 if let Some(key) = key.as_bytes().first().and_then(|key| Param::from_u8(*key)) {
276 inner.insert(key, value);
277 }
278 } else {
279 bail!("Not a key-value pair: {:?}", line);
280 }
281 }
282
283 Ok(Params { inner })
284 }
285}
286
287impl Params {
288 /// Create new empty params.
289 pub fn new() -> Self {
290 Default::default()
291 }
292
293 /// Get the value of the given key, return `None` if no value is set.
294 pub fn get(&self, key: Param) -> Option<&str> {
295 self.inner.get(&key).map(|s| s.as_str())
296 }
297
298 /// Check if the given key is set.
299 pub fn exists(&self, key: Param) -> bool {
300 self.inner.contains_key(&key)
301 }
302
303 /// Set the given key to the passed in value.
304 pub fn set(&mut self, key: Param, value: impl ToString) -> &mut Self {
305 if key == Param::File {
306 debug_assert!(value.to_string().starts_with("$BLOBDIR/"));
307 }
308 self.inner.insert(key, value.to_string());
309 self
310 }
311
312 /// Removes the given key, if it exists.
313 pub fn remove(&mut self, key: Param) -> &mut Self {
314 self.inner.remove(&key);
315 self
316 }
317
318 /// Sets the given key from an optional value.
319 /// Removes the key if the value is `None`.
320 pub fn set_optional(&mut self, key: Param, value: Option<impl ToString>) -> &mut Self {
321 if let Some(value) = value {
322 self.set(key, value)
323 } else {
324 self.remove(key)
325 }
326 }
327
328 /// Check if there are any values in this.
329 pub fn is_empty(&self) -> bool {
330 self.inner.is_empty()
331 }
332
333 /// Returns how many key-value pairs are set.
334 pub fn len(&self) -> usize {
335 self.inner.len()
336 }
337
338 /// Get the given parameter and parse as `i32`.
339 pub fn get_int(&self, key: Param) -> Option<i32> {
340 self.get(key).and_then(|s| s.parse().ok())
341 }
342
343 /// Get the given parameter and parse as `i64`.
344 pub fn get_i64(&self, key: Param) -> Option<i64> {
345 self.get(key).and_then(|s| s.parse().ok())
346 }
347
348 /// Get the given parameter and parse as `bool`.
349 pub fn get_bool(&self, key: Param) -> Option<bool> {
350 self.get_int(key).map(|v| v != 0)
351 }
352
353 /// Get the parameter behind `Param::Cmd` interpreted as `SystemMessage`.
354 pub fn get_cmd(&self) -> SystemMessage {
355 self.get_int(Param::Cmd)
356 .and_then(SystemMessage::from_i32)
357 .unwrap_or_default()
358 }
359
360 /// Set the parameter behind `Param::Cmd`.
361 pub fn set_cmd(&mut self, value: SystemMessage) {
362 self.set_int(Param::Cmd, value as i32);
363 }
364
365 /// Get the given parameter and parse as `f64`.
366 pub fn get_float(&self, key: Param) -> Option<f64> {
367 self.get(key).and_then(|s| s.parse().ok())
368 }
369
370 /// Returns a [BlobObject] for the [Param::File] parameter.
371 pub fn get_file_blob<'a>(&self, context: &'a Context) -> Result<Option<BlobObject<'a>>> {
372 let Some(val) = self.get(Param::File) else {
373 return Ok(None);
374 };
375 ensure!(val.starts_with("$BLOBDIR/"));
376 let blob = BlobObject::from_name(context, val)?;
377 Ok(Some(blob))
378 }
379
380 /// Returns a [PathBuf] for the [Param::File] parameter.
381 pub fn get_file_path(&self, context: &Context) -> Result<Option<PathBuf>> {
382 let blob = self.get_file_blob(context)?;
383 Ok(blob.map(|p| p.to_abs_path()))
384 }
385
386 /// Set the given parameter to the passed in `i32`.
387 pub fn set_int(&mut self, key: Param, value: i32) -> &mut Self {
388 self.set(key, format!("{value}"));
389 self
390 }
391
392 /// Set the given parameter to the passed in `i64`.
393 pub fn set_i64(&mut self, key: Param, value: i64) -> &mut Self {
394 self.set(key, value.to_string());
395 self
396 }
397
398 /// Set the given parameter to the passed in `f64` .
399 pub fn set_float(&mut self, key: Param, value: f64) -> &mut Self {
400 self.set(key, format!("{value}"));
401 self
402 }
403}
404
405#[cfg(test)]
406mod tests {
407 use std::str::FromStr;
408
409 use super::*;
410
411 #[test]
412 fn test_dc_param() {
413 let mut p1: Params = "a=1\nw=2\nc=3".parse().unwrap();
414
415 assert_eq!(p1.get_int(Param::Forwarded), Some(1));
416 assert_eq!(p1.get_int(Param::Width), Some(2));
417 assert_eq!(p1.get_int(Param::Height), None);
418 assert!(!p1.exists(Param::Height));
419
420 p1.set_int(Param::Duration, 4);
421
422 assert_eq!(p1.get_int(Param::Duration), Some(4));
423
424 let mut p1 = Params::new();
425
426 p1.set(Param::Forwarded, "foo")
427 .set_int(Param::Width, 2)
428 .remove(Param::GuaranteeE2ee)
429 .set_int(Param::Duration, 4);
430
431 assert_eq!(p1.to_string(), "a=foo\nd=4\nw=2");
432
433 p1.remove(Param::Width);
434
435 assert_eq!(p1.to_string(), "a=foo\nd=4",);
436 assert_eq!(p1.len(), 2);
437
438 p1.remove(Param::Forwarded);
439 p1.remove(Param::Duration);
440
441 assert_eq!(p1.to_string(), "",);
442
443 assert!(p1.is_empty());
444 assert_eq!(p1.len(), 0)
445 }
446
447 #[test]
448 fn test_roundtrip() {
449 let mut params = Params::new();
450 params.set(Param::Height, "foo\nbar=baz\nquux");
451 params.set(Param::Width, "\n\n\na=\n=");
452 assert_eq!(params.to_string().parse::<Params>().unwrap(), params);
453 }
454
455 #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
456 async fn test_params_unknown_key() -> Result<()> {
457 // 'Z' is used as a key that is known to be unused; these keys should be ignored silently by definition.
458 let p = Params::from_str("w=12\nZ=13\nh=14")?;
459 assert_eq!(p.len(), 2);
460 assert_eq!(p.get(Param::Width), Some("12"));
461 assert_eq!(p.get(Param::Height), Some("14"));
462 Ok(())
463 }
464}