deltachat/events/
payload.rs

1//! # Event payloads.
2
3use serde::{Deserialize, Serialize};
4use std::path::PathBuf;
5
6use crate::chat::ChatId;
7use crate::config::Config;
8use crate::contact::ContactId;
9use crate::ephemeral::Timer as EphemeralTimer;
10use crate::message::MsgId;
11use crate::reaction::Reaction;
12use crate::webxdc::StatusUpdateSerial;
13
14/// Event payload.
15#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
16pub enum EventType {
17    /// The library-user may write an informational string to the log.
18    ///
19    /// This event should *not* be reported to the end-user using a popup or something like
20    /// that.
21    Info(String),
22
23    /// Emitted when SMTP connection is established and login was successful.
24    SmtpConnected(String),
25
26    /// Emitted when IMAP connection is established and login was successful.
27    ImapConnected(String),
28
29    /// Emitted when a message was successfully sent to the SMTP server.
30    SmtpMessageSent(String),
31
32    /// Emitted when an IMAP message has been marked as deleted
33    ImapMessageDeleted(String),
34
35    /// Emitted when an IMAP message has been moved
36    ImapMessageMoved(String),
37
38    /// Emitted before going into IDLE on the Inbox folder.
39    ImapInboxIdle,
40
41    /// Emitted when an new file in the $BLOBDIR was created
42    NewBlobFile(String),
43
44    /// Emitted when an file in the $BLOBDIR was deleted
45    DeletedBlobFile(String),
46
47    /// The library-user should write a warning string to the log.
48    ///
49    /// This event should *not* be reported to the end-user using a popup or something like
50    /// that.
51    Warning(String),
52
53    /// The library-user should report an error to the end-user.
54    ///
55    /// As most things are asynchronous, things may go wrong at any time and the user
56    /// should not be disturbed by a dialog or so.  Instead, use a bubble or so.
57    ///
58    /// However, for ongoing processes (eg. configure())
59    /// or for functions that are expected to fail (eg. dc_continue_key_transfer())
60    /// it might be better to delay showing these events until the function has really
61    /// failed (returned false). It should be sufficient to report only the *last* error
62    /// in a message box then.
63    Error(String),
64
65    /// An action cannot be performed because the user is not in the group.
66    /// Reported eg. after a call to
67    /// dc_set_chat_name(), dc_set_chat_profile_image(),
68    /// dc_add_contact_to_chat(), dc_remove_contact_from_chat(),
69    /// dc_send_text_msg() or another sending function.
70    ErrorSelfNotInGroup(String),
71
72    /// Messages or chats changed.  One or more messages or chats changed for various
73    /// reasons in the database:
74    /// - Messages sent, received or removed
75    /// - Chats created, deleted or archived
76    /// - A draft has been set
77    ///
78    MsgsChanged {
79        /// Set if only a single chat is affected by the changes, otherwise 0.
80        chat_id: ChatId,
81
82        /// Set if only a single message is affected by the changes, otherwise 0.
83        msg_id: MsgId,
84    },
85
86    /// Reactions for the message changed.
87    ReactionsChanged {
88        /// ID of the chat which the message belongs to.
89        chat_id: ChatId,
90
91        /// ID of the message for which reactions were changed.
92        msg_id: MsgId,
93
94        /// ID of the contact whose reaction set is changed.
95        contact_id: ContactId,
96    },
97
98    /// A reaction to one's own sent message received.
99    /// Typically, the UI will show a notification for that.
100    ///
101    /// In addition to this event, ReactionsChanged is emitted.
102    IncomingReaction {
103        /// ID of the chat which the message belongs to.
104        chat_id: ChatId,
105
106        /// ID of the contact whose reaction set is changed.
107        contact_id: ContactId,
108
109        /// ID of the message for which reactions were changed.
110        msg_id: MsgId,
111
112        /// The reaction.
113        reaction: Reaction,
114    },
115
116    /// A webxdc wants an info message or a changed summary to be notified.
117    IncomingWebxdcNotify {
118        /// ID of the chat.
119        chat_id: ChatId,
120
121        /// ID of the contact sending.
122        contact_id: ContactId,
123
124        /// ID of the added info message or webxdc instance in case of summary change.
125        msg_id: MsgId,
126
127        /// Text to notify.
128        text: String,
129
130        /// Link assigned to this notification, if any.
131        href: Option<String>,
132    },
133
134    /// There is a fresh message. Typically, the user will show an notification
135    /// when receiving this message.
136    ///
137    /// There is no extra #DC_EVENT_MSGS_CHANGED event send together with this event.
138    IncomingMsg {
139        /// ID of the chat where the message is assigned.
140        chat_id: ChatId,
141
142        /// ID of the message.
143        msg_id: MsgId,
144    },
145
146    /// Downloading a bunch of messages just finished.
147    IncomingMsgBunch,
148
149    /// Messages were seen or noticed.
150    /// chat id is always set.
151    MsgsNoticed(ChatId),
152
153    /// A single message is sent successfully. State changed from  DC_STATE_OUT_PENDING to
154    /// DC_STATE_OUT_DELIVERED, see dc_msg_get_state().
155    MsgDelivered {
156        /// ID of the chat which the message belongs to.
157        chat_id: ChatId,
158
159        /// ID of the message that was successfully sent.
160        msg_id: MsgId,
161    },
162
163    /// A single message could not be sent. State changed from DC_STATE_OUT_PENDING or DC_STATE_OUT_DELIVERED to
164    /// DC_STATE_OUT_FAILED, see dc_msg_get_state().
165    MsgFailed {
166        /// ID of the chat which the message belongs to.
167        chat_id: ChatId,
168
169        /// ID of the message that could not be sent.
170        msg_id: MsgId,
171    },
172
173    /// A single message is read by the receiver. State changed from DC_STATE_OUT_DELIVERED to
174    /// DC_STATE_OUT_MDN_RCVD, see dc_msg_get_state().
175    MsgRead {
176        /// ID of the chat which the message belongs to.
177        chat_id: ChatId,
178
179        /// ID of the message that was read.
180        msg_id: MsgId,
181    },
182
183    /// A single message was deleted.
184    ///
185    /// This event means that the message will no longer appear in the messagelist.
186    /// UI should remove the message from the messagelist
187    /// in response to this event if the message is currently displayed.
188    ///
189    /// The message may have been explicitly deleted by the user or expired.
190    /// Internally the message may have been removed from the database,
191    /// moved to the trash chat or hidden.
192    ///
193    /// This event does not indicate the message
194    /// deletion from the server.
195    MsgDeleted {
196        /// ID of the chat where the message was prior to deletion.
197        /// Never 0 or trash chat.
198        chat_id: ChatId,
199
200        /// ID of the deleted message. Never 0.
201        msg_id: MsgId,
202    },
203
204    /// Chat changed.  The name or the image of a chat group was changed or members were added or removed.
205    /// Or the verify state of a chat has changed.
206    /// See dc_set_chat_name(), dc_set_chat_profile_image(), dc_add_contact_to_chat()
207    /// and dc_remove_contact_from_chat().
208    ///
209    /// This event does not include ephemeral timer modification, which
210    /// is a separate event.
211    ChatModified(ChatId),
212
213    /// Chat ephemeral timer changed.
214    ChatEphemeralTimerModified {
215        /// Chat ID.
216        chat_id: ChatId,
217
218        /// New ephemeral timer value.
219        timer: EphemeralTimer,
220    },
221
222    /// Chat was deleted.
223    ChatDeleted {
224        /// Chat ID.
225        chat_id: ChatId,
226    },
227
228    /// Contact(s) created, renamed, blocked, deleted or changed their "recently seen" status.
229    ///
230    /// @param data1 (int) If set, this is the contact_id of an added contact that should be selected.
231    ContactsChanged(Option<ContactId>),
232
233    /// Location of one or more contact has changed.
234    ///
235    /// @param data1 (u32) contact_id of the contact for which the location has changed.
236    ///     If the locations of several contacts have been changed,
237    ///     eg. after calling dc_delete_all_locations(), this parameter is set to `None`.
238    LocationChanged(Option<ContactId>),
239
240    /// Inform about the configuration progress started by configure().
241    ConfigureProgress {
242        /// Progress.
243        ///
244        /// 0=error, 1-999=progress in permille, 1000=success and done
245        progress: usize,
246
247        /// Progress comment or error, something to display to the user.
248        comment: Option<String>,
249    },
250
251    /// Inform about the import/export progress started by imex().
252    ///
253    /// @param data1 (usize) 0=error, 1-999=progress in permille, 1000=success and done
254    /// @param data2 0
255    ImexProgress(usize),
256
257    /// A file has been exported. A file has been written by imex().
258    /// This event may be sent multiple times by a single call to imex().
259    ///
260    /// A typical purpose for a handler of this event may be to make the file public to some system
261    /// services.
262    ///
263    /// @param data2 0
264    ImexFileWritten(PathBuf),
265
266    /// Progress information of a secure-join handshake from the view of the inviter
267    /// (Alice, the person who shows the QR code).
268    ///
269    /// These events are typically sent after a joiner has scanned the QR code
270    /// generated by dc_get_securejoin_qr().
271    SecurejoinInviterProgress {
272        /// ID of the contact that wants to join.
273        contact_id: ContactId,
274
275        /// Progress as:
276        /// 300=vg-/vc-request received, typically shown as "bob@addr joins".
277        /// 600=vg-/vc-request-with-auth received, vg-member-added/vc-contact-confirm sent, typically shown as "bob@addr verified".
278        /// 800=contact added to chat, shown as "bob@addr securely joined GROUP". Only for the verified-group-protocol.
279        /// 1000=Protocol finished for this contact.
280        progress: usize,
281    },
282
283    /// Progress information of a secure-join handshake from the view of the joiner
284    /// (Bob, the person who scans the QR code).
285    /// The events are typically sent while dc_join_securejoin(), which
286    /// may take some time, is executed.
287    SecurejoinJoinerProgress {
288        /// ID of the inviting contact.
289        contact_id: ContactId,
290
291        /// Progress as:
292        /// 400=vg-/vc-request-with-auth sent, typically shown as "alice@addr verified, introducing myself."
293        /// (Bob has verified alice and waits until Alice does the same for him)
294        /// 1000=vg-member-added/vc-contact-confirm received
295        progress: usize,
296    },
297
298    /// The connectivity to the server changed.
299    /// This means that you should refresh the connectivity view
300    /// and possibly the connectivtiy HTML; see dc_get_connectivity() and
301    /// dc_get_connectivity_html() for details.
302    ConnectivityChanged,
303
304    /// The user's avatar changed.
305    /// Deprecated by `ConfigSynced`.
306    SelfavatarChanged,
307
308    /// A multi-device synced config value changed. Maybe the app needs to refresh smth. For
309    /// uniformity this is emitted on the source device too. The value isn't here, otherwise it
310    /// would be logged which might not be good for privacy.
311    ConfigSynced {
312        /// Configuration key.
313        key: Config,
314    },
315
316    /// Webxdc status update received.
317    WebxdcStatusUpdate {
318        /// Message ID.
319        msg_id: MsgId,
320
321        /// Status update ID.
322        status_update_serial: StatusUpdateSerial,
323    },
324
325    /// Data received over an ephemeral peer channel.
326    WebxdcRealtimeData {
327        /// Message ID.
328        msg_id: MsgId,
329
330        /// Realtime data.
331        data: Vec<u8>,
332    },
333
334    /// Advertisement received over an ephemeral peer channel.
335    /// This can be used by bots to initiate peer-to-peer communication from their side.
336    WebxdcRealtimeAdvertisementReceived {
337        /// Message ID of the webxdc instance.
338        msg_id: MsgId,
339    },
340
341    /// Inform that a message containing a webxdc instance has been deleted.
342    WebxdcInstanceDeleted {
343        /// ID of the deleted message.
344        msg_id: MsgId,
345    },
346
347    /// Tells that the Background fetch was completed (or timed out).
348    /// This event acts as a marker, when you reach this event you can be sure
349    /// that all events emitted during the background fetch were processed.
350    ///
351    /// This event is only emitted by the account manager
352    AccountsBackgroundFetchDone,
353    /// Inform that set of chats or the order of the chats in the chatlist has changed.
354    ///
355    /// Sometimes this is emitted together with `UIChatlistItemChanged`.
356    ChatlistChanged,
357
358    /// Inform that a single chat list item changed and needs to be rerendered.
359    /// If `chat_id` is set to None, then all currently visible chats need to be rerendered, and all not-visible items need to be cleared from cache if the UI has a cache.
360    ChatlistItemChanged {
361        /// ID of the changed chat
362        chat_id: Option<ChatId>,
363    },
364
365    /// Inform that the list of accounts has changed (an account removed or added or (not yet implemented) the account order changes)
366    ///
367    /// This event is only emitted by the account manager
368    AccountsChanged,
369
370    /// Inform that an account property that might be shown in the account list changed, namely:
371    /// - is_configured (see [crate::context::Context::is_configured])
372    /// - displayname
373    /// - selfavatar
374    /// - private_tag
375    ///
376    /// This event is emitted from the account whose property changed.
377    AccountsItemChanged,
378
379    /// Event for using in tests, e.g. as a fence between normally generated events.
380    #[cfg(test)]
381    Test,
382
383    /// Inform than some events have been skipped due to event channel overflow.
384    EventChannelOverflow {
385        /// Number of events skipped.
386        n: u64,
387    },
388}
deltachat/events/payload.rs

deltachat/events/
payload.rs
