zbus_names/
bus_name.rs

1use core::{
2    borrow::Borrow,
3    fmt::{self, Debug, Display, Formatter},
4    ops::Deref,
5};
6use std::{borrow::Cow, sync::Arc};
7
8use crate::{
9    utils::impl_str_basic, Error, OwnedUniqueName, OwnedWellKnownName, Result, UniqueName,
10    WellKnownName,
11};
12use serde::{de, Deserialize, Serialize};
13use static_assertions::assert_impl_all;
14use zvariant::{NoneValue, OwnedValue, Str, Type, Value};
15
16/// String that identifies a [bus name].
17///
18/// # Examples
19///
20/// ```
21/// use zbus_names::BusName;
22///
23/// // Valid well-known names.
24/// let name = BusName::try_from("org.gnome.Service-for_you").unwrap();
25/// assert!(matches!(name, BusName::WellKnown(_)));
26/// assert_eq!(name, "org.gnome.Service-for_you");
27/// let name = BusName::try_from("a.very.loooooooooooooooooo-ooooooo_0000o0ng.Name").unwrap();
28/// assert!(matches!(name, BusName::WellKnown(_)));
29/// assert_eq!(name, "a.very.loooooooooooooooooo-ooooooo_0000o0ng.Name");
30///
31/// // Valid unique names.
32/// let name = BusName::try_from(":org.gnome.Service-for_you").unwrap();
33/// assert!(matches!(name, BusName::Unique(_)));
34/// assert_eq!(name, ":org.gnome.Service-for_you");
35/// let name = BusName::try_from(":a.very.loooooooooooooooooo-ooooooo_0000o0ng.Name").unwrap();
36/// assert!(matches!(name, BusName::Unique(_)));
37/// assert_eq!(name, ":a.very.loooooooooooooooooo-ooooooo_0000o0ng.Name");
38///
39/// // Invalid bus names
40/// BusName::try_from("").unwrap_err();
41/// BusName::try_from("double..dots").unwrap_err();
42/// BusName::try_from(".").unwrap_err();
43/// BusName::try_from(".start.with.dot").unwrap_err();
44/// BusName::try_from("1start.with.digit").unwrap_err();
45/// BusName::try_from("no-dots").unwrap_err();
46/// ```
47///
48/// [bus name]: https://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names-bus
49#[derive(Clone, Hash, PartialEq, Eq, PartialOrd, Ord, Serialize)]
50#[serde(untagged)]
51pub enum BusName<'name> {
52    #[serde(borrow)]
53    Unique(UniqueName<'name>),
54    #[serde(borrow)]
55    WellKnown(WellKnownName<'name>),
56}
57
58assert_impl_all!(BusName<'_>: Send, Sync, Unpin);
59
60impl_str_basic!(BusName<'_>);
61
62impl<'name> BusName<'name> {
63    /// This is faster than `Clone::clone` when `self` contains owned data.
64    pub fn as_ref(&self) -> BusName<'_> {
65        match self {
66            BusName::Unique(name) => BusName::Unique(name.as_ref()),
67            BusName::WellKnown(name) => BusName::WellKnown(name.as_ref()),
68        }
69    }
70
71    /// The well-known-name as string.
72    pub fn as_str(&self) -> &str {
73        match self {
74            BusName::Unique(name) => name.as_str(),
75            BusName::WellKnown(name) => name.as_str(),
76        }
77    }
78
79    /// Creates an owned clone of `self`.
80    pub fn to_owned(&self) -> BusName<'static> {
81        match self {
82            BusName::Unique(name) => BusName::Unique(name.to_owned()),
83            BusName::WellKnown(name) => BusName::WellKnown(name.to_owned()),
84        }
85    }
86
87    /// Creates an owned clone of `self`.
88    pub fn into_owned(self) -> BusName<'static> {
89        match self {
90            BusName::Unique(name) => BusName::Unique(name.into_owned()),
91            BusName::WellKnown(name) => BusName::WellKnown(name.into_owned()),
92        }
93    }
94
95    /// Same as `try_from`, except it takes a `&'static str`.
96    pub fn from_static_str(name: &'static str) -> Result<Self> {
97        match Self::try_from(name)? {
98            BusName::Unique(_) => Ok(BusName::Unique(UniqueName::from_static_str_unchecked(name))),
99            BusName::WellKnown(_) => Ok(BusName::WellKnown(
100                WellKnownName::from_static_str_unchecked(name),
101            )),
102        }
103    }
104}
105
106impl Deref for BusName<'_> {
107    type Target = str;
108
109    fn deref(&self) -> &Self::Target {
110        self.as_str()
111    }
112}
113
114impl Borrow<str> for BusName<'_> {
115    fn borrow(&self) -> &str {
116        self.as_str()
117    }
118}
119
120impl Debug for BusName<'_> {
121    fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
122        match self {
123            BusName::Unique(name) => f
124                .debug_tuple("BusName::Unique")
125                .field(&name.as_str())
126                .finish(),
127            BusName::WellKnown(name) => f
128                .debug_tuple("BusName::WellKnown")
129                .field(&name.as_str())
130                .finish(),
131        }
132    }
133}
134
135impl Display for BusName<'_> {
136    fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
137        Display::fmt(&self.as_str(), f)
138    }
139}
140
141impl PartialEq<str> for BusName<'_> {
142    fn eq(&self, other: &str) -> bool {
143        self.as_str() == other
144    }
145}
146
147impl PartialEq<&str> for BusName<'_> {
148    fn eq(&self, other: &&str) -> bool {
149        self.as_str() == *other
150    }
151}
152
153impl PartialEq<OwnedBusName> for BusName<'_> {
154    fn eq(&self, other: &OwnedBusName) -> bool {
155        *self == other.0
156    }
157}
158
159impl PartialEq<UniqueName<'_>> for BusName<'_> {
160    fn eq(&self, other: &UniqueName<'_>) -> bool {
161        match self {
162            Self::Unique(name) => *name == *other,
163            Self::WellKnown(_) => false,
164        }
165    }
166}
167
168impl PartialEq<WellKnownName<'_>> for BusName<'_> {
169    fn eq(&self, other: &WellKnownName<'_>) -> bool {
170        match self {
171            Self::Unique(_) => false,
172            Self::WellKnown(name) => *name == *other,
173        }
174    }
175}
176
177impl<'name> NoneValue for BusName<'name> {
178    type NoneType = &'name str;
179
180    fn null_value() -> Self::NoneType {
181        <&str>::default()
182    }
183}
184
185// Manual deserialize implementation to get the desired error on invalid bus names.
186impl<'de: 'name, 'name> Deserialize<'de> for BusName<'name> {
187    fn deserialize<D>(deserializer: D) -> core::result::Result<Self, D::Error>
188    where
189        D: serde::Deserializer<'de>,
190    {
191        let name = <Cow<'name, str>>::deserialize(deserializer)?;
192
193        Self::try_from(name).map_err(|e| de::Error::custom(e.to_string()))
194    }
195}
196
197impl Type for BusName<'_> {
198    fn signature() -> zvariant::Signature<'static> {
199        <&str>::signature()
200    }
201}
202
203impl<'name> From<UniqueName<'name>> for BusName<'name> {
204    fn from(name: UniqueName<'name>) -> Self {
205        BusName::Unique(name)
206    }
207}
208
209impl<'name> From<WellKnownName<'name>> for BusName<'name> {
210    fn from(name: WellKnownName<'name>) -> Self {
211        BusName::WellKnown(name)
212    }
213}
214
215impl<'s> TryFrom<Str<'s>> for BusName<'s> {
216    type Error = Error;
217
218    fn try_from(value: Str<'s>) -> Result<Self> {
219        match UniqueName::try_from(value.clone()) {
220            Err(Error::InvalidUniqueName(unique_err)) => match WellKnownName::try_from(value) {
221                Err(Error::InvalidWellKnownName(well_known_err)) => {
222                    Err(Error::InvalidBusName(unique_err, well_known_err))
223                }
224                Err(e) => Err(e),
225                Ok(name) => Ok(BusName::WellKnown(name)),
226            },
227            Err(e) => Err(e),
228            Ok(name) => Ok(BusName::Unique(name)),
229        }
230    }
231}
232
233impl<'s> TryFrom<&'s str> for BusName<'s> {
234    type Error = Error;
235
236    fn try_from(value: &'s str) -> Result<Self> {
237        Str::from(value).try_into()
238    }
239}
240
241impl<'s> TryFrom<String> for BusName<'s> {
242    type Error = Error;
243
244    fn try_from(value: String) -> Result<Self> {
245        Str::from(value).try_into()
246    }
247}
248
249impl<'s> TryFrom<Arc<str>> for BusName<'s> {
250    type Error = Error;
251
252    fn try_from(value: Arc<str>) -> Result<Self> {
253        Str::from(value).try_into()
254    }
255}
256
257impl<'s> TryFrom<Value<'s>> for BusName<'s> {
258    type Error = Error;
259
260    fn try_from(value: Value<'s>) -> Result<Self> {
261        Str::try_from(value)
262            .map_err(Into::into)
263            .and_then(TryInto::try_into)
264    }
265}
266
267/// This never succeeds but is provided so it's easier to pass `Option::None` values for API
268/// requiring `Option<TryInto<impl BusName>>`, since type inference won't work here.
269impl TryFrom<()> for BusName<'_> {
270    type Error = Error;
271
272    fn try_from(_value: ()) -> Result<Self> {
273        unreachable!("Conversion from `()` is not meant to actually work.");
274    }
275}
276
277impl<'name> TryFrom<Cow<'name, str>> for BusName<'name> {
278    type Error = Error;
279
280    fn try_from(value: Cow<'name, str>) -> Result<Self> {
281        Str::from(value).try_into()
282    }
283}
284
285impl<'s> From<BusName<'s>> for Value<'s> {
286    fn from(name: BusName<'s>) -> Self {
287        match name {
288            BusName::Unique(name) => name.into(),
289            BusName::WellKnown(name) => name.into(),
290        }
291    }
292}
293
294impl<'name> From<BusName<'name>> for Str<'name> {
295    fn from(value: BusName<'name>) -> Self {
296        match value {
297            BusName::Unique(name) => name.into(),
298            BusName::WellKnown(name) => name.into(),
299        }
300    }
301}
302
303impl<'name> From<&BusName<'name>> for BusName<'name> {
304    fn from(name: &BusName<'name>) -> Self {
305        name.clone()
306    }
307}
308
309impl TryFrom<OwnedValue> for BusName<'_> {
310    type Error = Error;
311
312    fn try_from(value: OwnedValue) -> Result<Self> {
313        Str::try_from(value)
314            .map_err(Into::into)
315            .and_then(TryInto::try_into)
316    }
317}
318
319impl TryFrom<BusName<'static>> for OwnedValue {
320    type Error = Error;
321
322    fn try_from(name: BusName<'static>) -> Result<Self> {
323        match name {
324            BusName::Unique(name) => name.try_into(),
325            BusName::WellKnown(name) => name.try_into(),
326        }
327        .map_err(Into::into)
328    }
329}
330
331impl From<OwnedUniqueName> for BusName<'_> {
332    fn from(name: OwnedUniqueName) -> Self {
333        BusName::Unique(name.into())
334    }
335}
336
337impl<'a> From<&'a OwnedUniqueName> for BusName<'a> {
338    fn from(name: &'a OwnedUniqueName) -> Self {
339        BusName::Unique(name.into())
340    }
341}
342
343impl From<OwnedWellKnownName> for BusName<'_> {
344    fn from(name: OwnedWellKnownName) -> Self {
345        BusName::WellKnown(name.into())
346    }
347}
348
349impl<'a> From<&'a OwnedWellKnownName> for BusName<'a> {
350    fn from(name: &'a OwnedWellKnownName) -> Self {
351        BusName::WellKnown(name.into())
352    }
353}
354
355/// Owned sibling of [`BusName`].
356#[derive(Clone, Hash, PartialEq, Eq, Serialize, PartialOrd, Ord, Type)]
357pub struct OwnedBusName(#[serde(borrow)] BusName<'static>);
358
359impl_str_basic!(OwnedBusName);
360
361impl OwnedBusName {
362    /// Convert to the inner `BusName`, consuming `self`.
363    pub fn into_inner(self) -> BusName<'static> {
364        self.0
365    }
366
367    /// Get a reference to the inner `BusName`.
368    pub fn inner(&self) -> &BusName<'static> {
369        &self.0
370    }
371}
372
373impl Deref for OwnedBusName {
374    type Target = BusName<'static>;
375
376    fn deref(&self) -> &Self::Target {
377        &self.0
378    }
379}
380
381impl Borrow<str> for OwnedBusName {
382    fn borrow(&self) -> &str {
383        self.0.as_str()
384    }
385}
386
387impl Debug for OwnedBusName {
388    fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
389        match &self.0 {
390            BusName::Unique(name) => f
391                .debug_tuple("OwnedBusName::Unique")
392                .field(&name.as_str())
393                .finish(),
394            BusName::WellKnown(name) => f
395                .debug_tuple("OwnedBusName::WellKnown")
396                .field(&name.as_str())
397                .finish(),
398        }
399    }
400}
401
402impl Display for OwnedBusName {
403    fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
404        Display::fmt(&BusName::from(self), f)
405    }
406}
407
408impl From<OwnedBusName> for BusName<'_> {
409    fn from(name: OwnedBusName) -> Self {
410        name.into_inner()
411    }
412}
413
414impl<'unowned, 'owned: 'unowned> From<&'owned OwnedBusName> for BusName<'unowned> {
415    fn from(name: &'owned OwnedBusName) -> Self {
416        match &name.0 {
417            BusName::Unique(name) => BusName::Unique(UniqueName::from_str_unchecked(name)),
418            BusName::WellKnown(name) => BusName::WellKnown(WellKnownName::from_str_unchecked(name)),
419        }
420    }
421}
422
423impl From<BusName<'_>> for OwnedBusName {
424    fn from(name: BusName<'_>) -> Self {
425        OwnedBusName(name.into_owned())
426    }
427}
428
429impl TryFrom<&'_ str> for OwnedBusName {
430    type Error = Error;
431
432    fn try_from(value: &str) -> Result<Self> {
433        BusName::try_from(value).map(Self::from)
434    }
435}
436
437impl TryFrom<String> for OwnedBusName {
438    type Error = Error;
439
440    fn try_from(value: String) -> Result<Self> {
441        BusName::try_from(value).map(Self::from)
442    }
443}
444
445impl TryFrom<Cow<'_, str>> for OwnedBusName {
446    type Error = Error;
447
448    fn try_from(value: Cow<'_, str>) -> Result<Self> {
449        BusName::try_from(value).map(Self::from)
450    }
451}
452
453impl TryFrom<Value<'static>> for OwnedBusName {
454    type Error = Error;
455
456    fn try_from(value: Value<'static>) -> Result<Self> {
457        BusName::try_from(value).map(Self::from)
458    }
459}
460
461impl From<OwnedBusName> for Value<'_> {
462    fn from(name: OwnedBusName) -> Self {
463        name.0.into()
464    }
465}
466
467impl TryFrom<OwnedValue> for OwnedBusName {
468    type Error = Error;
469
470    fn try_from(value: OwnedValue) -> Result<Self> {
471        BusName::try_from(value).map(Self::from)
472    }
473}
474
475impl TryFrom<OwnedBusName> for OwnedValue {
476    type Error = Error;
477
478    fn try_from(name: OwnedBusName) -> Result<Self> {
479        name.0.try_into()
480    }
481}
482
483impl From<OwnedBusName> for Str<'_> {
484    fn from(value: OwnedBusName) -> Self {
485        match value.0 {
486            BusName::Unique(name) => name.into(),
487            BusName::WellKnown(name) => name.into(),
488        }
489    }
490}
491
492impl<'de> Deserialize<'de> for OwnedBusName {
493    fn deserialize<D>(deserializer: D) -> std::result::Result<Self, D::Error>
494    where
495        D: de::Deserializer<'de>,
496    {
497        String::deserialize(deserializer)
498            .and_then(|n| BusName::try_from(n).map_err(|e| de::Error::custom(e.to_string())))
499            .map(Self)
500    }
501}
502
503impl PartialEq<&str> for OwnedBusName {
504    fn eq(&self, other: &&str) -> bool {
505        self.as_str() == *other
506    }
507}
508
509impl PartialEq<BusName<'_>> for OwnedBusName {
510    fn eq(&self, other: &BusName<'_>) -> bool {
511        self.0 == *other
512    }
513}
514
515impl NoneValue for OwnedBusName {
516    type NoneType = <BusName<'static> as NoneValue>::NoneType;
517
518    fn null_value() -> Self::NoneType {
519        BusName::null_value()
520    }
521}
zbus_names/bus_name.rs

zbus_names/
bus_name.rs
