openlogi-hidpp 0.8.4

//! Implements functionality specific to HID++2.0.

use num_enum::{IntoPrimitive, TryFromPrimitive};
use thiserror::Error;

use crate::{
    channel::{
        ChannelError, HidppChannel, HidppMessage, LONG_REPORT_LENGTH, SEND_RESPONSE_TIMEOUT,
        SHORT_REPORT_LENGTH,
    },
    nibble::{self, U4},
};

/// Represents the header that every [`HidppMessage`] of HID++2.0 starts with.
#[derive(Clone, Copy, PartialEq, Eq, Hash, Debug)]
#[cfg_attr(feature = "serde", derive(serde::Serialize))]
pub struct MessageHeader {
    /// The index of the device involved in the communication.
    pub device_index: u8,

    /// The index of the feature the message belongs to.
    ///
    /// This is not the same as the feature ID, but the index returned from a
    /// feature enumeration request.
    pub feature_index: u8,

    /// The ID of the function involved in the communication.
    pub function_id: U4,

    /// The ID of the software communicating with the device.
    pub software_id: U4,
}

/// Represents a HID++2.0 message.
#[derive(Clone, Copy, PartialEq, Eq, Hash, Debug)]
#[cfg_attr(feature = "serde", derive(serde::Serialize))]
pub enum Message {
    /// Represents a short HID++2.0 message with 3 bytes of payload.
    Short(MessageHeader, [u8; SHORT_REPORT_LENGTH - 4]),

    /// Represents a long HID++2.0 message with 16 bytes of payload.
    Long(MessageHeader, [u8; LONG_REPORT_LENGTH - 4]),
}

impl Message {
    /// Extracts the header of the message.
    #[must_use]
    pub fn header(&self) -> MessageHeader {
        match *self {
            Message::Short(header, _) | Message::Long(header, _) => header,
        }
    }

    /// Extracts the payload of the message and fits it into an array capable of
    /// containing the longest possible payload, filling the rest up with
    /// zeroes.
    #[must_use]
    pub fn extend_payload(&self) -> [u8; LONG_REPORT_LENGTH - 4] {
        match *self {
            Message::Short(_, payload) => {
                let mut data = [0; LONG_REPORT_LENGTH - 4];
                data[..SHORT_REPORT_LENGTH - 4].copy_from_slice(&payload);
                data
            }
            Message::Long(_, payload) => payload,
        }
    }
}

impl From<HidppMessage> for Message {
    fn from(msg: HidppMessage) -> Self {
        match msg {
            HidppMessage::Short(payload) => {
                let [_, _, _, rest @ ..] = payload;
                Message::Short(
                    MessageHeader {
                        device_index: payload[0],
                        feature_index: payload[1],
                        function_id: U4::from_hi(payload[2]),
                        software_id: U4::from_lo(payload[2]),
                    },
                    rest,
                )
            }
            HidppMessage::Long(payload) => {
                let [_, _, _, rest @ ..] = payload;
                Message::Long(
                    MessageHeader {
                        device_index: payload[0],
                        feature_index: payload[1],
                        function_id: U4::from_hi(payload[2]),
                        software_id: U4::from_lo(payload[2]),
                    },
                    rest,
                )
            }
        }
    }
}

impl From<Message> for HidppMessage {
    fn from(msg: Message) -> Self {
        match msg {
            Message::Short(header, payload) => {
                let mut data = [0u8; SHORT_REPORT_LENGTH - 1];
                data[0] = header.device_index;
                data[1] = header.feature_index;
                data[2] = nibble::combine(header.function_id, header.software_id);
                data[3..].copy_from_slice(&payload);

                HidppMessage::Short(data)
            }
            Message::Long(header, payload) => {
                let mut data = [0u8; LONG_REPORT_LENGTH - 1];
                data[0] = header.device_index;
                data[1] = header.feature_index;
                data[2] = nibble::combine(header.function_id, header.software_id);
                data[3..].copy_from_slice(&payload);

                HidppMessage::Long(data)
            }
        }
    }
}

impl HidppChannel {
    /// Sends a HID++2.0 message across the channel and waits for a response
    /// that matches the message header.
    ///
    /// This method simply calls [`Self::send`] with a pre-built response
    /// predicate comparing the headers of the outgoing and incoming message.
    pub async fn send_v20(&self, msg: Message) -> Result<Message, Hidpp20Error> {
        let header = msg.header();
        let response = self
            .send(msg.into(), v20_response_predicate(header))
            .await?;
        decode_v20_response(response)
    }

    /// Sends a HID++2.0 message without timing out its native write, then waits
    /// up to [`SEND_RESPONSE_TIMEOUT`] for the matching response.
    ///
    /// `matches_payload` further filters successful responses where the feature
    /// defines echoed fields. Header-matched errors bypass this filter.
    ///
    /// The caller **must drive this future to completion**. Requester deadlines
    /// belong outside the task that owns this future; see
    /// [`HidppChannel::send_write_through`] for the transport-ordering contract.
    pub async fn send_v20_write_through(
        &self,
        msg: Message,
        matches_payload: impl Fn(&Message) -> bool + Send + 'static,
    ) -> Result<Message, Hidpp20Error> {
        let matches_header = v20_response_predicate(msg.header());
        let response = self
            .send_write_through(
                msg.into(),
                move |raw| {
                    let response = Message::from(*raw);
                    matches_header(raw)
                        && (response.header().feature_index == 0xff || matches_payload(&response))
                },
                SEND_RESPONSE_TIMEOUT,
            )
            .await?;
        decode_v20_response(response)
    }
}

fn v20_response_predicate(
    header: MessageHeader,
) -> impl Fn(&HidppMessage) -> bool + Send + 'static {
    move |&response| {
        let response = Message::from(response);
        let response_header = response.header();

        // A HID++2.0 error response sets the feature index to 0xFF and moves all header
        // values starting from the real feature index one byte to the right.
        let is_error = response_header.device_index == header.device_index
            && response_header.feature_index == 0xff
            && nibble::combine(response_header.function_id, response_header.software_id)
                == header.feature_index
            && response.extend_payload()[0]
                == nibble::combine(header.function_id, header.software_id);

        is_error || response_header == header
    }
}

fn decode_v20_response(response: HidppMessage) -> Result<Message, Hidpp20Error> {
    let response = Message::from(response);
    if response.header().feature_index == 0xff {
        let err = ErrorType::try_from(response.extend_payload()[1])
            .map_err(|_| Hidpp20Error::UnsupportedResponse)?;

        return Err(Hidpp20Error::Feature(err));
    }

    Ok(response)
}

/// Represents the type of an error a HID++2.0 device returns if a feature
/// function fails.
#[derive(Clone, Copy, PartialEq, Eq, Hash, Debug, IntoPrimitive, TryFromPrimitive)]
#[cfg_attr(feature = "serde", derive(serde::Serialize))]
#[non_exhaustive]
#[repr(u8)]
pub enum ErrorType {
    /// No error.
    NoError = 0,
    /// Unknown error.
    Unknown = 1,
    /// Invalid argument.
    InvalidArgument = 2,
    /// Argument out of range.
    OutOfRange = 3,
    /// Hardware error.
    HwError = 4,
    /// Logitech-internal firmware error.
    LogitechInternal = 5,
    /// Invalid feature index.
    InvalidFeatureIndex = 6,
    /// Invalid function ID.
    InvalidFunctionId = 7,
    /// Device is busy.
    Busy = 8,
    /// Operation is unsupported.
    Unsupported = 9,
}

/// Represents an error that may occur when calling a HID++2.0 feature function.
#[derive(Debug, Error)]
#[non_exhaustive]
pub enum Hidpp20Error {
    /// Indicates that an error occurred while communicating across the HID++
    /// channel.
    #[error("the HID++ channel returned an error")]
    Channel(#[from] ChannelError),

    /// Indicates that a call to a HID++2.0 feature function resulted in an
    /// error.
    #[error("a HID++2.0 feature returned an error")]
    Feature(ErrorType),

    /// Indicates that a received response is not fully supported.
    #[error("the received response from the device is (partly) unsupported")]
    UnsupportedResponse,
}