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