sonor/
lib.rs

1#![warn(
2    nonstandard_style,
3    rust_2018_idioms,
4    future_incompatible,
5    missing_debug_implementations,
6    missing_docs
7)]
8
9//! This crate is a Sonos controller library written in Rust.
10//! It operates asynchronously and aims for a simple to use yet powerful API.
11//!
12//! # Example
13//! ```rust,no_run
14//! # use futures::prelude::*;
15//! # use std::time::Duration;
16//! # async fn f() -> Result<(), sonor::Error> {
17//! let speaker = sonor::find("your room name", Duration::from_secs(2)).await?
18//!     .expect("room exists");
19//!
20//! println!("The volume is currently at {}", speaker.volume().await?);
21//!
22//! match speaker.track().await? {
23//!     Some(track_info) => println!("- Currently playing '{}", track_info.track()),
24//!     None => println!("- No track currently playing"),
25//! }
26//!
27//! speaker.clear_queue().await?;
28//!
29//! speaker.join("some other room").await?;
30//!
31//! # Ok(())
32//! # };
33//! ```
34//! For a full list of actions implemented, look at the [Speaker](struct.Speaker.html) docs.
35//!
36//! If your use case isn't covered, this crate also exposes the raw UPnP Action API
37//! [here](struct.Speaker.html#method.action).
38//! It can be used like this:
39//! ```rust,no_run
40//! # use futures::prelude::*;
41//! # use std::time::Duration;
42//! use sonor::URN;
43//! # async fn f() -> Result<(), sonor::Error> {
44//! # let speaker = sonor::find("your room name", Duration::from_secs(2)).await?.expect("room exists");
45//!
46//! let service = URN::service("schemas-upnp-org", "GroupRenderingControl", 1);
47//! let args = "<InstanceID>0</InstanceID>";
48//! let response = speaker.action(&service, "GetGroupMute", args).await?;
49//!
50//! println!("{}", response["CurrentMute"]);
51//!
52//! # Ok(())
53//! # };
54//! ```
55
56mod datatypes;
57mod discovery;
58mod snapshot;
59mod speaker;
60mod track;
61mod utils;
62
63pub use datatypes::{RepeatMode, SpeakerInfo};
64pub use discovery::{discover, find};
65pub use rupnp::{self, ssdp::URN};
66pub use snapshot::Snapshot;
67pub use speaker::Speaker;
68use thiserror::*;
69pub use track::{Track, TrackInfo};
70
71/// Represents an error encountered by Sonor
72#[derive(Error, Debug)]
73pub enum Error {
74    /// Errors sourced from the rupnp crate
75    #[error(transparent)]
76    UPnP(#[from] rupnp::Error),
77    /// Errors sourced from XML parsing
78    #[error(transparent)]
79    Xml(#[from] roxmltree::Error),
80    /// Errors source from URI manipulation
81    #[error(transparent)]
82    InvalidUri(#[from] http::uri::InvalidUri),
83    /// This error is produced when attempting to perform an action and
84    /// the specified service is not present.
85    #[error("Service {service} was not found when performing {action} with {payload}")]
86    MissingServiceForUPnPAction {
87        /// The required service for the action
88        service: URN,
89        /// The action to be performed
90        action: String,
91        /// The action payload
92        payload: String,
93    },
94    /// An impossible? situation where a speaker isn't included
95    /// in its own zone group state
96    #[error("asked for zone group state but the speaker doesn't seem to be included there")]
97    SpeakerNotIncludedInOwnZoneGroupState,
98    /// An impossible? situation where GetZoneGroupState returned non-Sonos devices
99    #[error("The Sonos-specific GetZoneGroupState action returned non-Sonos devices")]
100    GetZoneGroupStateReturnedNonSonos,
101    /// An impossible? situation where non-Sonos devices responded
102    /// to UPnP discovery for Sono devices
103    #[error("UPnP discovery for Sonos devices returned non-Sonos devices")]
104    NonSonosDevicesInSonosUPnPDiscovery,
105}
106
107type Result<T, E = Error> = std::result::Result<T, E>;
sonor/lib.rs

sonor/
lib.rs
