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: &UniqueName<'_>) => f&mut DebugTuple<'_, '_>
124 .debug_tuple(name:"BusName::Unique")
125 .field(&name.as_str())
126 .finish(),
127 BusName::WellKnown(name: &WellKnownName<'_>) => f&mut DebugTuple<'_, '_>
128 .debug_tuple(name:"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: &UniqueName<'_>) => *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: &WellKnownName<'_>) => *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> = <Cow<'name, str>>::deserialize(deserializer)?;
192
193 Self::try_from(name).map_err(|e: Error| de::Error::custom(msg: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: String)) => match WellKnownName::try_from(value) {
221 Err(Error::InvalidWellKnownName(well_known_err: String)) => {
222 Err(Error::InvalidBusName(unique_err, well_known_err))
223 }
224 Err(e: Error) => Err(e),
225 Ok(name: WellKnownName<'_>) => Ok(BusName::WellKnown(name)),
226 },
227 Err(e: Error) => Err(e),
228 Ok(name: UniqueName<'_>) => 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(op: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: UniqueName<'_>) => name.into(),
289 BusName::WellKnown(name: WellKnownName<'_>) => 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: UniqueName<'_>) => name.into(),
298 BusName::WellKnown(name: WellKnownName<'_>) => 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(op: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(op: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: &UniqueName<'_>) => f&mut DebugTuple<'_, '_>
391 .debug_tuple(name:"OwnedBusName::Unique")
392 .field(&name.as_str())
393 .finish(),
394 BusName::WellKnown(name: &WellKnownName<'_>) => f&mut DebugTuple<'_, '_>
395 .debug_tuple(name:"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: &UniqueName<'_>) => BusName::Unique(UniqueName::from_str_unchecked(name)),
418 BusName::WellKnown(name: &WellKnownName<'_>) => 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: UniqueName<'_>) => name.into(),
487 BusName::WellKnown(name: WellKnownName<'_>) => 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}
522