cros_alsa/src/control.rs

// Copyright 2020 The Chromium OS Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

//! `control` module is meant to provide easier to use and more type safe abstractions
//! for various alsa mixer controls.
//!
//! Each mixer control should implement the `Control` trait to allow itself to be created by `Card`.
//! Each mixer control could hold `Ctl` as handle and `ElemID` as id and use `#[derive(ControlOps)]` macro
//! to generate default load / save implementations of the `ControlOps` trait which allows itself to read and
//! write the underlying hardware.
//!
//! # Examples
//! This is an example of how to define a `SwitchControl`.
//!
//! ```
//! use std::error::Error;
//!
//! use cros_alsa::{Ctl, ElemId, Control, ControlError, ControlOps};
//! use cros_alsa::elem::Elem;
//!
//! type Result<T> = std::result::Result<T, ControlError>;
//!
//! #[derive(ControlOps)]
//! pub struct SwitchControl<'a> {
//!     // Must hold `Ctl` as handle and `ElemID` as id to use `#[derive(ControlOps)]`.
//!     handle: &'a mut Ctl,
//!     id: ElemId,
//! }
//!
//! impl<'a> Control<'a> for SwitchControl <'a> {
//!     type Item = [bool; 1];
//!
//!     fn new(handle: &'a mut Ctl, id: ElemId) -> Self {
//!         Self {
//!             handle,
//!             id,
//!         }
//!     }
//! }
//!
//! impl<'a> SwitchControl<'a> {
//!     /// Reads the state of a switch type mix control.
//!     pub fn state(&mut self) -> Result<bool> {
//!         // Uses ControlOps::load() to read the mixer control.
//!         let v = self.load()?;
//!         Ok(v[0])
//!     }
//!
//!     /// Updates the control state to true.
//!     pub fn on(&mut self) -> Result<()> {
//!         // Uses ControlOps::save() to write the mixer control.
//!         self.save([true])?;
//!         Ok(())
//!     }
//! }
//!
//! ```

use std::error;
use std::fmt;

use cros_alsa_derive::ControlOps;
use remain::sorted;

use crate::control_primitive::{self, Ctl, ElemId, ElemInfo, ElemType};
use crate::elem::{self, Elem};

/// The Result type of cros-alsa::control.
pub type Result<T> = std::result::Result<T, Error>;

#[sorted]
#[derive(Debug)]
/// Possible errors that can occur in cros-alsa::control.
pub enum Error {
    /// Failed to call AlsaControlAPI.
    AlsaControlAPI(control_primitive::Error),
    /// Error occurs in Elem.
    Elem(elem::Error),
    /// Elem::size() does not match the element count of the mixer control.
    MismatchElemCount(String, usize, usize),
    /// Elem::elem_type() does not match the data type of the mixer control.
    MismatchElemType(String, ElemType, ElemType),
}

impl error::Error for Error {}

impl From<control_primitive::Error> for Error {
    fn from(err: control_primitive::Error) -> Error {
        Error::AlsaControlAPI(err)
    }
}

impl From<elem::Error> for Error {
    fn from(err: elem::Error) -> Error {
        Error::Elem(err)
    }
}

impl fmt::Display for Error {
    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
        use Error::*;
        match self {
            AlsaControlAPI(e) => write!(f, "{}", e),
            Elem(e) => write!(f, "{}", e),
            MismatchElemCount(name, count, elem_count) => write!(
                f,
                "invalid `Control::size()` of {}: expect: {}, get: {}",
                name, count, elem_count
            ),
            MismatchElemType(name, t, elem_type) => write!(
                f,
                "invalid `Control::elem_type()` of {}: expect: {}, get: {}",
                name, t, elem_type
            ),
        }
    }
}

/// Each mixer control should implement the `Control` trait to allow itself to be created by `Card`.
pub trait Control<'a>: Sized + 'a {
    /// The data type of the mixer control.
    /// Use `ElemType::load()` and `ElemType::save()` to read or write the mixer control.
    type Item: Elem;

    /// Called by `Self::from(handle: &'a mut Ctl, id: ElemId)` to create a `Control`.
    fn new(handle: &'a mut Ctl, id: ElemId) -> Self;
    /// Called by `Card` to create a `Control`.
    fn from(handle: &'a mut Ctl, id: ElemId) -> Result<Self> {
        let info = ElemInfo::new(handle, &id)?;
        if info.elem_type()? != Self::elem_type() {
            return Err(Error::MismatchElemType(
                id.name()?.to_owned(),
                info.elem_type()?,
                Self::elem_type(),
            ));
        }

        if info.count() != Self::size() {
            return Err(Error::MismatchElemCount(
                id.name()?.to_owned(),
                info.count(),
                Self::size(),
            ));
        }

        Ok(Self::new(handle, id))
    }
    /// Called by `Self::from(handle: &'a mut Ctl, id: ElemId)` to validate the data type of a
    /// `Control`.
    fn elem_type() -> ElemType {
        Self::Item::elem_type()
    }
    /// Called by `Self::from(handle: &'a mut Ctl, id: ElemId)` to validate the number of value
    /// entries of a `Control`.
    fn size() -> usize {
        Self::Item::size()
    }
}

/// Each mixer control could implement the `ControlOps` trait to allow itself to read and
/// write the underlying hardware`. Users could hold `Ctl` and `ElemID` as `handle` and `id`
/// in their control structure and use `#[derive(ControlOps)]` macro to generate default
/// load / save implementations.
pub trait ControlOps<'a>: Control<'a> {
    /// Reads the values of the mixer control.
    fn load(&mut self) -> Result<<Self as Control<'a>>::Item>;
    /// Saves the values to the mixer control.
    fn save(&mut self, val: <Self as Control<'a>>::Item) -> Result<bool>;
}

/// `Control` that reads and writes a single integer value entry.
/// Since this crate is the `cros_alsa` crate, we replace the `cros_alsa`
/// path to `crate` in derive macros by `cros_alsa` attribute.
#[derive(ControlOps)]
#[cros_alsa(path = "crate")]
pub struct IntControl<'a> {
    handle: &'a mut Ctl,
    id: ElemId,
}

impl<'a> IntControl<'a> {
    /// Gets an i32 value from the mixer control.
    ///
    /// # Errors
    ///
    /// * If it fails to read from the control.
    pub fn get(&mut self) -> Result<i32> {
        let val = self.load()?;
        Ok(val[0])
    }

    /// Updates an i32 value to the mixer control.
    ///
    /// # Errors
    ///
    /// * If it fails to write to the control.
    pub fn set(&mut self, val: i32) -> Result<()> {
        self.save([val])?;
        Ok(())
    }
}

impl<'a> Control<'a> for IntControl<'a> {
    type Item = [i32; 1];
    fn new(handle: &'a mut Ctl, id: ElemId) -> Self {
        Self { handle, id }
    }
}

/// Stereo Volume Mixer Control
/// Since this crate is the `cros_alsa` crate, we replace the `cros_alsa`
/// path to `crate` in derive macros by `cros_alsa` attribute.
#[derive(ControlOps)]
#[cros_alsa(path = "crate")]
pub struct StereoVolumeControl<'a> {
    handle: &'a mut Ctl,
    id: ElemId,
}

impl<'a> StereoVolumeControl<'a> {
    /// Reads the left and right volume.
    ///
    /// # Errors
    ///
    /// * If it fails to read from the control.
    pub fn volume(&mut self) -> Result<(i32, i32)> {
        let val = self.load()?;
        Ok((val[0], val[1]))
    }

    /// Updates the left and right volume.
    ///
    /// # Errors
    ///
    /// * If it fails to write to the control.
    pub fn set_volume(&mut self, left: i32, right: i32) -> Result<()> {
        self.save([left, right])?;
        Ok(())
    }
}

impl<'a> Control<'a> for StereoVolumeControl<'a> {
    type Item = [i32; 2];
    fn new(handle: &'a mut Ctl, id: ElemId) -> Self {
        Self { handle, id }
    }
}

/// `Control` that reads and writes a single boolean value entry.
/// Since this crate is the `cros_alsa` crate, we replace the `cros_alsa`
/// path to `crate` in derive macros by `cros_alsa` attribute.
#[derive(ControlOps)]
#[cros_alsa(path = "crate")]
pub struct SwitchControl<'a> {
    handle: &'a mut Ctl,
    id: ElemId,
}

impl<'a> SwitchControl<'a> {
    /// Reads the state of a switch type mix control.
    ///
    /// # Errors
    ///
    /// * If it fails to read from the control.
    pub fn state(&mut self) -> Result<bool> {
        let v = self.load()?;
        Ok(v[0])
    }

    /// Updates the control state to true.
    ///
    /// # Errors
    ///
    /// * If it fails to write to the control.
    pub fn on(&mut self) -> Result<()> {
        self.save([true])?;
        Ok(())
    }

    /// Updates the control state to false.
    ///
    /// # Errors
    ///
    /// * If it fails to write to the control.
    pub fn off(&mut self) -> Result<()> {
        self.save([false])?;
        Ok(())
    }
}

impl<'a> Control<'a> for SwitchControl<'a> {
    type Item = [bool; 1];
    fn new(handle: &'a mut Ctl, id: ElemId) -> Self {
        Self { handle, id }
    }
}