medea_control_api_proto/
callback.rs

1//! API for receiving callbacks from a media server.
2
3use async_trait::async_trait;
4use derive_more::with_trait::From;
5use time::OffsetDateTime as DateTime;
6
7use crate::Fid;
8
9/// API for receiving callbacks from a media server.
10///
11/// Both API client and API server should implement this trait.
12#[async_trait]
13pub trait Api {
14    /// Error returned by this [`CallbackApi`].
15    ///
16    /// [`CallbackApi`]: Api
17    type Error;
18
19    /// Fires when a certain callback [`Event`] happens on a media server.
20    async fn on_event(&self, request: Request) -> Result<(), Self::Error>;
21}
22
23/// Request with a fired callback [`Event`] and its meta information.
24///
25/// Used for invoking and processing callbacks via [`CallbackApi::on_event()`].
26///
27/// [`CallbackApi::on_event()`]: Api::on_event
28#[derive(Debug)]
29pub struct Request {
30    /// FID (Full ID) of the media [`Element`], the occurred [`Event`] is
31    /// related to.
32    ///
33    /// [`Element`]: crate::Element
34    pub fid: Fid,
35
36    /// Occurred [`Event`].
37    pub event: Event,
38
39    /// [`DateTime`] when the [`Event`] occurred.
40    pub at: DateTime,
41}
42
43/// Possible callbacks events which may happen on a media server.
44#[derive(Clone, Copy, Debug, From)]
45pub enum Event {
46    /// [`Member`] joined a [`Room`].
47    ///
48    /// [`Member`]: crate::Member
49    /// [`Room`]: crate::Room
50    OnJoin(OnJoinEvent),
51
52    /// [`Member`] left its [`Room`].
53    ///
54    /// [`Member`]: crate::Member
55    /// [`Room`]: crate::Room
56    OnLeave(OnLeaveEvent),
57}
58
59/// [`Event`] notifying about a [`Member`] joining a [`Room`].
60///
61/// [`Member`]: crate::Member
62/// [`Room`]: crate::Room
63#[derive(Clone, Copy, Debug)]
64pub struct OnJoinEvent;
65
66/// [`Event`] notifying about a [`Member`] leaving its [`Room`].
67///
68/// [`Member`]: crate::Member
69/// [`Room`]: crate::Room
70#[derive(Clone, Copy, Debug)]
71pub struct OnLeaveEvent {
72    /// Reason of why the [`Member`] leaves.
73    ///
74    /// [`Member`]: crate::Member
75    pub reason: OnLeaveReason,
76}
77
78impl OnLeaveEvent {
79    /// Creates a new [`OnLeaveEvent`] with the provided [`OnLeaveReason`].
80    #[must_use]
81    pub const fn new(reason: OnLeaveReason) -> Self {
82        Self { reason }
83    }
84}
85
86/// Possible reasons of why a [`Member`] leaves its [`Room`].
87///
88/// [`Member`]: crate::Member
89/// [`Room`]: crate::Room
90#[derive(Clone, Copy, Debug)]
91pub enum OnLeaveReason {
92    /// [`Member`] was disconnected normally.
93    ///
94    /// [`Member`]: crate::Member
95    Disconnected,
96
97    /// Connection with the [`Member`] was lost.
98    ///
99    /// [`Member`]: crate::Member
100    Lost,
101
102    /// [`Member`] was forcibly disconnected by a media server.
103    ///
104    /// [`Member`]: crate::Member
105    Kicked,
106
107    /// Media server was shut down.
108    Shutdown,
109}
medea_control_api_proto/callback.rs

medea_control_api_proto/
callback.rs
