zbus 5.12.0

API for D-Bus communication
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106

use zbus_names::{BusName, InterfaceName, MemberName};

use crate::{zvariant::ObjectPath, Connection, Error, Result};

/// A signal emitter.
///
/// For signal emission using the high-level API, you'll need instances of this type.
///
/// See [`crate::object_server::InterfaceRef::signal_emitter`] and [`crate::interface`]
/// documentation for details and examples of this type in use.
#[derive(Clone, Debug)]
pub struct SignalEmitter<'s> {
    conn: Connection,
    path: ObjectPath<'s>,
    destination: Option<BusName<'s>>,
}

impl<'s> SignalEmitter<'s> {
    /// Create a new signal context for the given connection and object path.
    pub fn new<P>(conn: &Connection, path: P) -> Result<Self>
    where
        P: TryInto<ObjectPath<'s>>,
        P::Error: Into<Error>,
    {
        path.try_into()
            .map(|p| Self {
                conn: conn.clone(),
                path: p,
                destination: None,
            })
            .map_err(Into::into)
    }

    /// Create a new signal context for the given connection and object path.
    pub fn from_parts(conn: Connection, path: ObjectPath<'s>) -> Self {
        Self {
            conn,
            path,
            destination: None,
        }
    }

    /// Emit a signal on the given interface with the given signal name and body.
    pub async fn emit<'i, 'm, I, M, B>(&self, interface: I, signal_name: M, body: &B) -> Result<()>
    where
        I: TryInto<InterfaceName<'i>>,
        I::Error: Into<Error>,
        M: TryInto<MemberName<'m>>,
        M::Error: Into<Error>,
        B: serde::ser::Serialize + zvariant::DynamicType,
    {
        self.conn
            .emit_signal(
                self.destination.as_ref(),
                &self.path,
                interface,
                signal_name,
                body,
            )
            .await
    }

    /// Set the destination for the signal emission.
    ///
    /// Signals are typically broadcasted and thus don't have a destination. However, there are
    /// cases where you need to unicast signals to specific peers. This method allows you to set the
    /// destination for the signals emitted with this context.
    pub fn set_destination(mut self, destination: BusName<'s>) -> Self {
        self.destination = Some(destination);

        self
    }

    /// Get a reference to the associated connection.
    pub fn connection(&self) -> &Connection {
        &self.conn
    }

    /// Get a reference to the associated object path.
    pub fn path(&self) -> &ObjectPath<'s> {
        &self.path
    }

    /// Get a reference to the associated destination (if any).
    pub fn destination(&self) -> Option<&BusName<'s>> {
        self.destination.as_ref()
    }

    /// Create an owned clone of `self`.
    pub fn to_owned(&self) -> SignalEmitter<'static> {
        SignalEmitter {
            conn: self.conn.clone(),
            path: self.path.to_owned(),
            destination: self.destination.as_ref().map(|d| d.to_owned()),
        }
    }

    /// Convert into an owned clone of `self`.
    pub fn into_owned(self) -> SignalEmitter<'static> {
        SignalEmitter {
            conn: self.conn,
            path: self.path.into_owned(),
            destination: self.destination.map(|d| d.into_owned()),
        }
    }
}