diff options
Diffstat (limited to 'mumlib')
| -rw-r--r-- | mumlib/src/command.rs | 44 | ||||
| -rw-r--r-- | mumlib/src/config.rs | 23 | ||||
| -rw-r--r-- | mumlib/src/lib.rs | 2 | ||||
| -rw-r--r-- | mumlib/src/state.rs | 7 |
4 files changed, 76 insertions, 0 deletions
diff --git a/mumlib/src/command.rs b/mumlib/src/command.rs index 8cb7cb9..642c8b9 100644 --- a/mumlib/src/command.rs +++ b/mumlib/src/command.rs @@ -1,3 +1,7 @@ +//! [Command]s can be sent from a controller to mumd who might respond with a +//! [CommandResponse]. The commands and their responses are serializable and +//! can be sent in any way you want. + use crate::state::{Channel, Server}; use chrono::NaiveDateTime; @@ -56,29 +60,51 @@ impl fmt::Display for MumbleEventKind { } } +/// Sent by a controller to mumd who might respond with a [CommandResponse]. Not +/// all commands receive a response. #[derive(Clone, Debug, Deserialize, Serialize)] pub enum Command { + /// No response. ChannelJoin { channel_identifier: String, }, + + /// Response: [CommandResponse::ChannelList]. ChannelList, + + /// Force reloading of config file from disk. No response. ConfigReload, + /// Response: [CommandResponse::DeafenStatus]. Toggles if None. DeafenSelf(Option<bool>), Events { block: bool }, + /// Set the outgoing audio volume (i.e. from you to the server). No response. InputVolumeSet(f32), + + /// Response: [CommandResponse::MuteStatus]. Toggles if None. MuteOther(String, Option<bool>), + + /// Response: [CommandResponse::MuteStatus]. Toggles if None. MuteSelf(Option<bool>), + + /// Set the master incoming audio volume (i.e. from the server to you). + /// No response. OutputVolumeSet(f32), + PastMessages { block: bool, }, + + /// Response: [CommandResponse::Pong]. Used to test existance of a + /// mumd-instance. Ping, + SendMessage { message: String, targets: MessageTarget, }, + /// Connect to the specified server. Response: [CommandResponse::ServerConnect]. ServerConnect { host: String, port: u16, @@ -86,43 +112,61 @@ pub enum Command { password: Option<String>, accept_invalid_cert: bool, }, + + /// No response. ServerDisconnect, + + /// Send a server status request via UDP (e.g. not requiring a TCP connection). + /// Response: [CommandResponse::ServerStatus]. ServerStatus { host: String, port: u16, }, + + /// Response: [CommandResponse::Status]. Status, + + /// No response. UserVolumeSet(String, f32), } +/// A response to a sent [Command]. #[derive(Debug, Deserialize, Serialize)] pub enum CommandResponse { ChannelList { channels: Channel, }, + DeafenStatus { is_deafened: bool, }, + Event { event: MumbleEvent, }, + MuteStatus { is_muted: bool, }, + PastMessage { message: (NaiveDateTime, String, String), }, + Pong, + ServerConnect { welcome_message: Option<String>, server_state: Server, }, + ServerStatus { version: u32, users: u32, max_users: u32, bandwidth: u32, }, + Status { server_state: Server, }, diff --git a/mumlib/src/config.rs b/mumlib/src/config.rs index 3edef37..b5bcdb1 100644 --- a/mumlib/src/config.rs +++ b/mumlib/src/config.rs @@ -23,6 +23,8 @@ struct TOMLConfig { servers: Option<Array>, } +/// Our representation of the mumdrc config file. +// Deserialized via [TOMLConfig]. #[derive(Clone, Debug, Default)] pub struct Config { pub audio: AudioConfig, @@ -34,6 +36,15 @@ pub struct Config { } impl Config { + /// Writes this config to the specified path. + /// + /// Pass create = true if you want the file to be created if it doesn't already exist. + /// + /// # Errors + /// + /// - [ConfigError::WontCreateFile] if the file doesn't exist and create = false was passed. + /// - Any [ConfigError::TOMLErrorSer] encountered when serializing the config. + /// - Any [ConfigError::IOError] encountered when writing the file. pub fn write(&self, path: &Path, create: bool) -> Result<(), ConfigError> { // Possible race here. It's fine since it shows when: // 1) the file doesn't exist when checked and is then created @@ -90,6 +101,10 @@ impl ServerConfig { } } +/// Finds the default path of the configuration file. +/// +/// The user config dir is looked for first (cross-platform friendly) and +/// `/etc/mumdrc` is used as a fallback. pub fn default_cfg_path() -> PathBuf { match dirs::config_dir() { Some(mut p) => { @@ -143,6 +158,14 @@ impl From<Config> for TOMLConfig { } } +/// Reads the config at the specified path. +/// +/// If the file isn't found, returns a default config. +/// +/// # Errors +/// +/// - Any [ConfigError::TOMLErrorDe] encountered when deserializing the config. +/// - Any [ConfigError::IOError] encountered when reading the file. pub fn read_cfg(path: &Path) -> Result<Config, ConfigError> { match fs::read_to_string(path) { Ok(s) => { diff --git a/mumlib/src/lib.rs b/mumlib/src/lib.rs index 9b7d686..4b302e3 100644 --- a/mumlib/src/lib.rs +++ b/mumlib/src/lib.rs @@ -9,6 +9,8 @@ use colored::*; use log::*; pub const SOCKET_PATH: &str = "/tmp/mumd"; + +/// The default mumble port. pub const DEFAULT_PORT: u16 = 64738; pub fn setup_logger<T: Into<fern::Output>>(target: T, color: bool) { diff --git a/mumlib/src/state.rs b/mumlib/src/state.rs index 772e822..182a8fc 100644 --- a/mumlib/src/state.rs +++ b/mumlib/src/state.rs @@ -36,6 +36,9 @@ impl Channel { links: Vec::new(), } } + + /// Create an iterator over this channel and its children in a pre-order + /// traversal. pub fn iter(&self) -> Iter<'_> { Iter { me: Some(&self), @@ -48,6 +51,8 @@ impl Channel { } } + /// Create an iterator over this channel and its childrens connected users + /// in a pre-order traversal. pub fn users_iter(&self) -> UsersIter<'_> { UsersIter { channels: self.children.iter().map(|e| e.users_iter()).collect(), @@ -62,6 +67,7 @@ impl Channel { } } +/// An iterator over channels. Created by [Channel::iter]. pub struct Iter<'a> { me: Option<&'a Channel>, channel: Option<usize>, @@ -92,6 +98,7 @@ impl<'a> Iterator for Iter<'a> { } } +/// An iterator over users. Created by [Channel::users_iter]. pub struct UsersIter<'a> { channel: Option<usize>, channels: Vec<UsersIter<'a>>, |