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
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168

#![warn(missing_docs)]
#![deny(
    missing_debug_implementations,
    missing_copy_implementations,
    trivial_casts,
    trivial_numeric_casts,
    unsafe_code,
    unreachable_pub,
    unstable_features,
    unused_import_braces,
    unused_qualifications
)]

//!
//! # mpris
//!
//! `mpris` is an idiomatic library for dealing with [MPRIS2][spec]-compatible media players over D-Bus.
//!
//! This would mostly apply to the Linux-ecosystem which is a heavy user of D-Bus.
//!
//! ## Getting started
//!
//! Some hints on how to use this library:
//!
//! 1. Look at the examples under `examples/`.
//! 2. Look at the [`PlayerFinder`] struct.
//!
//! [spec]: https://specifications.freedesktop.org/mpris-spec/latest/

use thiserror::Error;

mod extensions;

#[allow(unreachable_pub)]
mod generated;

mod event;
mod find;
mod metadata;
mod player;
mod pooled_connection;
mod progress;
mod track_list;

pub use crate::event::{Event, EventError, PlayerEvents};
pub use crate::find::{FindingError, PlayerFinder, PlayerIter};
pub use crate::metadata::Metadata;
pub use crate::metadata::Value as MetadataValue;
pub use crate::metadata::ValueKind as MetadataValueKind;
pub use crate::player::Player;
pub use crate::progress::{Progress, ProgressError, ProgressTick, ProgressTracker};
pub use crate::track_list::{TrackID, TrackList, TrackListError};

#[derive(Debug, PartialEq, Eq, Copy, Clone)]
#[allow(missing_docs)]
/// The [`Player`]'s playback status
///
/// See: [MPRIS2 specification about `PlaybackStatus`][playback_status]
///
/// [playback_status]: https://specifications.freedesktop.org/mpris-spec/latest/Player_Interface.html#Enum:Playback_Status
pub enum PlaybackStatus {
    /// A track is currently playing.
    Playing,
    /// A track is currently paused.
    Paused,
    /// There is no track currently playing.
    Stopped,
}

#[derive(Debug, PartialEq, Eq, Copy, Clone)]
/// A [`Player`]'s looping status.
///
/// See: [MPRIS2 specification about `Loop_Status`][loop_status]
///
/// [loop_status]: https://specifications.freedesktop.org/mpris-spec/latest/Player_Interface.html#Enum:Loop_Status
pub enum LoopStatus {
    /// The playback will stop when there are no more tracks to play
    None,

    /// The current track will start again from the begining once it has finished playing
    Track,

    /// The playback loops through a list of tracks
    Playlist,
}

/// [`PlaybackStatus`] had an invalid string value.
#[derive(Debug, Error)]
#[error("PlaybackStatus must be one of Playing, Paused, Stopped, but was {0}")]
pub struct InvalidPlaybackStatus(String);

impl ::std::str::FromStr for PlaybackStatus {
    type Err = InvalidPlaybackStatus;

    fn from_str(string: &str) -> Result<Self, Self::Err> {
        use crate::PlaybackStatus::*;

        match string {
            "Playing" => Ok(Playing),
            "Paused" => Ok(Paused),
            "Stopped" => Ok(Stopped),
            other => Err(InvalidPlaybackStatus(other.to_string())),
        }
    }
}

/// [`LoopStatus`] had an invalid string value.
#[derive(Debug, Error)]
#[error("LoopStatus must be one of None, Track, Playlist, but was {0}")]
pub struct InvalidLoopStatus(String);

impl ::std::str::FromStr for LoopStatus {
    type Err = InvalidLoopStatus;

    fn from_str(string: &str) -> Result<Self, Self::Err> {
        match string {
            "None" => Ok(LoopStatus::None),
            "Track" => Ok(LoopStatus::Track),
            "Playlist" => Ok(LoopStatus::Playlist),
            other => Err(InvalidLoopStatus(other.to_string())),
        }
    }
}

impl LoopStatus {
    fn dbus_value(self) -> String {
        String::from(match self {
            LoopStatus::None => "None",
            LoopStatus::Track => "Track",
            LoopStatus::Playlist => "Playlist",
        })
    }
}

/// Something went wrong when communicating with the D-Bus. This could either be an underlying
/// D-Bus library problem, or that the other side did not conform to the expected protocols.
#[derive(Debug, Error)]
pub enum DBusError {
    /// An error occurred while talking to the D-Bus.
    #[error("D-Bus call failed: {0}")]
    TransportError(#[from] dbus::Error),

    /// Failed to parse an enum from a string value received from the [`Player`]. This means that the
    /// [`Player`] replied with unexpected data.
    #[error("Failed to parse enum value: {0}")]
    EnumParseError(String),

    /// A D-Bus method call did not pass arguments of the correct type. This means that the [`Player`]
    /// replied with unexpected data.
    #[error("D-Bus call failed: {0}")]
    TypeMismatchError(#[from] dbus::arg::TypeMismatchError),

    /// Some other unexpected error occurred.
    #[error("Unexpected error: {0}")]
    Miscellaneous(String),
}

impl From<InvalidPlaybackStatus> for DBusError {
    fn from(error: InvalidPlaybackStatus) -> Self {
        DBusError::EnumParseError(error.to_string())
    }
}

impl From<InvalidLoopStatus> for DBusError {
    fn from(error: InvalidLoopStatus) -> Self {
        DBusError::EnumParseError(error.to_string())
    }
}