1// Copyright (c) 2023 xmpp-rs contributors.
  2//
  3// This Source Code Form is subject to the terms of the Mozilla Public
  4// License, v. 2.0. If a copy of the MPL was not distributed with this
  5// file, You can obtain one at http://mozilla.org/MPL/2.0/.
  6
  7use tokio_xmpp::jid::BareJid;
  8#[cfg(feature = "avatars")]
  9use tokio_xmpp::jid::Jid;
 10use tokio_xmpp::parsers::roster::Item as RosterItem;
 11#[cfg(feature = "escape-hatch")]
 12use tokio_xmpp::parsers::{iq::Iq, message::Message, presence::Presence};
 13
 14use crate::parsers::confirm::Confirm;
 15use crate::{Error, MessageId, RoomNick, delay::StanzaTimeInfo};
 16
 17/// An Event notifying the client something has happened that may require attention.
 18///
 19/// This can be an XMPP event received from the server, or existing state communicated by the server to the client, like when receiving the contact list.
 20#[derive(Debug)]
 21pub enum Event {
 22    /// Client connected.
 23    Online,
 24    /// Client disconnected; if reconnect is disabled, no more event will be received.
 25    Disconnected(Error),
 26    /// Contact received from contact list (roster).
 27    ///
 28    /// This happens when:
 29    ///
 30    /// - it was added recently to the contact list
 31    /// - or when the client just came online and is receiving the existing contact list
 32    ContactAdded(RosterItem),
 33    /// Contact removed from contact list (roster).
 34    ContactRemoved(RosterItem),
 35    /// Contact changed in contact list (roster).
 36    ///
 37    /// This happens when (non-exhaustive):
 38    ///
 39    /// - the contact's nickname changed
 40    /// - the contact's subscription status changed (eg. they accepted a friend request)
 41    /// - the contact has been added to or removed from a contact group
 42    ContactChanged(RosterItem),
 43    #[cfg(feature = "avatars")]
 44    /// Avatar received for a certain JID, with sender JID / avatar path
 45    ///
 46    /// The avatar path is relative file path to the avatar data.
 47    ///
 48    /// NOTE: For now, it's not possible to configure where the avatars are stored, see [issue 112](https://gitlab.com/xmpp-rs/xmpp-rs/-/issues/112) for more information.
 49    AvatarRetrieved(Jid, String),
 50    /// A chat message was received. It may have been delayed on the network.
 51    /// - The [`MessageId`] is a unique identifier for this message.
 52    /// - The [`BareJid`] is the sender's JID.
 53    /// - The [`String`] is the message body.
 54    /// - The [`StanzaTimeInfo`] about when message was received, and when the message was claimed sent.
 55    ChatMessage(Option<MessageId>, BareJid, String, StanzaTimeInfo),
 56    /// A message in a one-to-one chat was corrected/edited.
 57    /// - The [`MessageId`] is the ID of the message that was corrected.
 58    /// - The [`BareJid`] is the JID of the other participant in the chat.
 59    /// - The [`String`] is the new body of the message, to replace the old one.
 60    /// - The [`StanzaTimeInfo`] is the time the message correction was sent/received
 61    ChatMessageCorrection(MessageId, BareJid, String, StanzaTimeInfo),
 62    /// A XEP-0070 authentication request or confirmation was received.
 63    /// - The [`BareJid`] is the sender's JID.
 64    /// - The [`Confirm`] is the info about the authentication request.
 65    /// - The [`StanzaTimeInfo`] about when message was received, and when the message was claimed sent.
 66    AuthConfirm(BareJid, Confirm, StanzaTimeInfo),
 67    /// A XEP-0070 authentication rejection was received.
 68    /// - The [`BareJid`] is the sender's JID.
 69    /// - The [`Confirm`] is the info about the authentication request that was rejected.
 70    /// - The [`StanzaTimeInfo`] about when message was received, and when the message was claimed sent.
 71    AuthReject(BareJid, Confirm, StanzaTimeInfo),
 72    /// Room joined; client may receive and send messages from/to this BareJid.
 73    RoomJoined(BareJid),
 74    /// Room left; client may not receive and send messages from/to this BareJid
 75    RoomLeft(BareJid),
 76    /// Room message received with:
 77    /// - An optional [`MessageId`] for the message.
 78    /// - The [`BareJid`] of the room the message was sent from.
 79    /// - The [`RoomNick`] of the sender.
 80    /// - A [`String`] containing the actual message.
 81    /// - The [`StanzaTimeInfo`] containing time related information for the message.
 82    RoomMessage(Option<MessageId>, BareJid, RoomNick, String, StanzaTimeInfo),
 83    /// A message in a MUC was corrected/edited.
 84    /// - The [`MessageId`] is the ID of the message that was corrected.
 85    /// - The [`BareJid`] is the JID of the room where the message was sent.
 86    /// - The [`RoomNick`] is the nickname of the sender of the message.
 87    /// - The [`String`] is the new body of the message, to replace the old one.
 88    /// - The [`StanzaTimeInfo`] is the time the message correction was sent/received
 89    RoomMessageCorrection(MessageId, BareJid, RoomNick, String, StanzaTimeInfo),
 90    /// The subject of a room was received.
 91    /// - The [`BareJid`] is the room's address.
 92    /// - The [`RoomNick`] is the nickname of the room member who set the subject.
 93    /// - The [`String`] is the new subject.
 94    RoomSubject(BareJid, Option<RoomNick>, String, StanzaTimeInfo),
 95    /// A private message received from a room, containing:
 96    /// - An optional [`MessageId`] for the message.
 97    /// - The room's [`BareJid`].
 98    /// - The sender's [`RoomNick`].
 99    /// - A [`String`] containing the actual message.
100    /// - The [`StanzaTimeInfo`] containing time related information for the message.
101    RoomPrivateMessage(Option<MessageId>, BareJid, RoomNick, String, StanzaTimeInfo),
102    /// A private message in a MUC was corrected/edited.
103    /// - The [`MessageId`] is the ID of the message that was corrected.
104    /// - The [`BareJid`] is the JID of the room where the message was sent.
105    /// - The [`RoomNick`] is the nickname of the sender of the message.
106    /// - The [`String`] is the new body of the message, to replace the old one.
107    /// - The [`StanzaTimeInfo`] is the time the message correction was sent/received
108    RoomPrivateMessageCorrection(MessageId, BareJid, RoomNick, String, StanzaTimeInfo),
109    /// Service message (eg. server notification) received, with:
110    /// - An optional [`MessageId`] for the message.
111    /// - The [`BareJid`] of the entity that sent it.
112    /// - A [`String`] containing the actual message.
113    /// - The [`StanzaTimeInfo`] containing time related information for the message.
114    ServiceMessage(Option<MessageId>, BareJid, String, StanzaTimeInfo),
115    /// A file has been uploaded over HTTP; contains the URL of the file.
116    HttpUploadedFile(String),
117    #[cfg(feature = "escape-hatch")]
118    /// Variant only available when the "escape-hatch" feature is enabled. Proxies an Iq received
119    /// as a tokio-xmpp event.
120    Iq(Iq),
121    #[cfg(feature = "escape-hatch")]
122    /// Variant only available when the "escape-hatch" feature is enabled. Proxies a Message
123    /// received as a tokio-xmpp event.
124    Message(Message),
125    #[cfg(feature = "escape-hatch")]
126    /// Variant only available when the "escape-hatch" feature is enabled. Proxies a Presence
127    /// received as a tokio-xmpp event.
128    Presence(Presence),
129}