mtp-rs 0.36.2

//! Configuration types for virtual MTP devices.

use std::path::PathBuf;
use std::time::Duration;

/// Configuration for a virtual MTP device.
///
/// Defines the identity and storages of a virtual device that operates against
/// a local filesystem directory instead of real USB hardware.
///
/// Build one from [`Default`] and set only the fields your test cares about.
/// New fields then arrive with a working default instead of breaking every
/// construction site.
///
/// # Example
///
/// ```rust
/// use std::path::PathBuf;
/// use mtp_rs::transport::virtual_device::config::{VirtualDeviceConfig, VirtualStorageConfig};
///
/// let config = VirtualDeviceConfig {
///     manufacturer: "Google".into(),
///     model: "Virtual Pixel 9".into(),
///     serial: "virtual-001".into(),
///     storages: vec![VirtualStorageConfig {
///         description: "Internal Storage".into(),
///         capacity: 64 * 1024 * 1024 * 1024,
///         backing_dir: PathBuf::from("/tmp/mtp-test"),
///         read_only: false,
///     }],
///     ..Default::default()
/// };
/// ```
#[derive(Debug, Clone)]
pub struct VirtualDeviceConfig {
    /// Manufacturer name reported by the virtual device.
    pub manufacturer: String,
    /// Model name reported by the virtual device.
    pub model: String,
    /// Serial number for the virtual device.
    pub serial: String,
    /// Storage configurations. At least one storage is required.
    pub storages: Vec<VirtualStorageConfig>,
    /// Whether the device advertises SetObjectPropValue support (rename).
    pub supports_rename: bool,
    /// Whether the device advertises `GetPartialObject64` (0x95C1), the 64-bit
    /// offset partial read. Real Android devices do; many PTP cameras (e.g. the
    /// Panasonic Lumix DMC-TZ61) only advertise the 32-bit `GetPartialObject`.
    /// Set `false` to model such a camera and exercise the 32-bit fallback path.
    ///
    /// An operation this is `false` for is refused with `Operation_Not_Supported`,
    /// not just left out of `OperationsSupported`, so a consumer that ignores the
    /// capability and calls it anyway fails the way a real device makes it fail.
    pub supports_partial_object_64: bool,
    /// Whether the device advertises `GetPartialObject` (0x101B), the 32-bit
    /// offset partial read.
    ///
    /// Set this and [`supports_partial_object_64`](Self::supports_partial_object_64)
    /// both to `false` to model a responder that can only hand over whole objects:
    /// [`Capabilities::supports_partial_download`](crate::mtp::Capabilities::supports_partial_download)
    /// then reports `false`, every ranged read fails [`Error::Unsupported`](crate::Error::Unsupported),
    /// and `download(handle, ByteRange::Full)` is the only way to get the bytes.
    /// libhaze (Sphaira on the Nintendo Switch) is one such responder, and simple
    /// PTP responders are another. That combination is what a consumer's
    /// whole-object fallback path needs in order to be testable at all.
    ///
    /// Like the 64-bit flag, `false` means the operation is *refused*, not merely
    /// unadvertised.
    pub supports_partial_object: bool,
    /// Whether the device advertises and serves `GetObjectPropList` (0x9805), which
    /// lets a host list a folder's children in one request per property instead of
    /// one `GetObjectInfo` each. Modern Android advertises it, so this defaults to
    /// `true`; set `false` to model a responder without it (most PTP cameras) and
    /// exercise the per-handle listing. Like the partial-read flags, `false` means
    /// the operation is *refused*, not merely unadvertised.
    ///
    /// The answers model Android's `MtpDatabase.getObjectPropertyList`: group code
    /// 0 only, depth 0 or 1, a depth-1 answer lists the folder's children and then
    /// the folder itself, "all properties" (`0xFFFFFFFF`) returns Android's file
    /// property set (which has no `DateCreated`; the library's listings never ask
    /// for it, but low-level `ptp::` callers can), and a property the device doesn't
    /// know comes back with data type `Undefined` and no value. Every value matches
    /// what `GetObjectInfo` reports for the same object, except that `ObjectSize`
    /// is the full 64-bit size. An object that `GetObjectInfo` refuses to describe
    /// ([`undescribable_objects`](Self::undescribable_objects) or
    /// [`force_object_info_error`](super::registry::force_object_info_error)) fails
    /// any `GetObjectPropList` whose answer would include it.
    pub supports_object_prop_list: bool,
    /// Properties that `GetObjectPropList` declines with `Invalid_ObjectPropCode`
    /// (0xA801) when asked for one at a time. Use it to model a device that can't
    /// serve a property a host needs (or would like). Defaults to empty.
    pub prop_list_declined_properties: Vec<crate::ptp::ObjectPropertyCode>,
    /// How long `receive_interrupt` waits when no events are pending.
    /// Simulates the USB interrupt endpoint blocking behavior.
    /// Default: 50ms for production use. Use `Duration::ZERO` in tests
    /// to avoid slowing down the test suite.
    pub event_poll_interval: Duration,
    /// Watch backing directories for out-of-band changes and emit MTP events.
    /// When `true`, a background filesystem watcher detects files created or
    /// removed directly in the backing directories (bypassing MTP) and queues
    /// `ObjectAdded`/`ObjectRemoved` events. Set to `false` for tests that
    /// don't need this (faster startup, no background threads).
    pub watch_backing_dirs: bool,
    /// Storage-relative paths (`"b.txt"`, `"sub/c.txt"`) whose `GetObjectInfo`
    /// answers `GeneralError` instead of an ObjectInfo dataset. The objects stay
    /// present on disk and readable by every other operation, modeling a device
    /// that enumerates a handle and then won't describe it (Sphaira on the
    /// Nintendo Switch, issue #22).
    ///
    /// This is the config twin of
    /// [`force_object_info_error`](super::registry::force_object_info_error): the
    /// hook needs a handle, so it can only be armed after a listing and from
    /// inside the same process. Name the paths here instead when the device has
    /// to come up already broken, which is what a consumer testing its own
    /// binary end to end (a CLI, a FUSE mount) needs.
    ///
    /// Defaults to empty: every object describes itself.
    pub undescribable_objects: Vec<String>,
    /// The UTC offset of the virtual device's clock: the zone it reports dates in
    /// and reads zoneless dates from.
    ///
    /// The device reports each object's `DateModified` from its backing file's
    /// modification time, and `DateCreated` from its birth time where the host
    /// filesystem records one. A `DateModified` received in `SendObjectInfo`
    /// becomes the uploaded file's modification time, the way Android's
    /// `MtpServer` stamps it after the data phase: an offset on the received
    /// value is honored, and a zoneless one is read at this offset. So a
    /// fixture seeds a date by setting the backing file's modification time:
    ///
    /// ```no_run
    /// # fn main() -> std::io::Result<()> {
    /// use std::time::{Duration, UNIX_EPOCH};
    ///
    /// let file = std::fs::File::options().write(true).open("/tmp/mtp-test/photo.jpg")?;
    /// file.set_modified(UNIX_EPOCH + Duration::from_secs(1_710_513_022))?;
    /// // Reported as "20240315T143022" with the default UTC clock.
    /// # Ok(())
    /// # }
    /// ```
    ///
    /// Dates are whole seconds, as on the wire. Defaults to UTC, which keeps
    /// tests independent of the machine's zone.
    pub utc_offset: crate::mtp::UtcOffset,
    /// Whether reported dates carry [`utc_offset`](Self::utc_offset) as a suffix
    /// (`Z` or `±hhmm`). `false` writes them zoneless, the way Android does,
    /// so a consumer's handling of zoneless dates gets exercised. Defaults to
    /// `false`.
    pub dates_include_offset: bool,
}

/// A ready-to-extend starting point: an obviously-fake identity plus the
/// behavior flags a modern Android device would report.
///
/// **You must set `storages`**: the default is empty, which is not a usable
/// device. `MtpDeviceBuilder::open_virtual` rejects it up front with
/// "VirtualDeviceConfig requires at least one storage", and
/// `register_virtual_device` produces a device with nothing on it. There is no
/// honest default here, since only the caller knows which directory backs the
/// storage.
///
/// Two other fields are worth overriding:
///
/// - `serial` defaults to a fixed string, so give each device its own when you
///   register more than one at a time.
/// - `event_poll_interval` and `watch_backing_dirs` default to production-like
///   values (50 ms, watching on). Tests that don't exercise the watcher run
///   faster with `Duration::ZERO` and `false`.
impl Default for VirtualDeviceConfig {
    fn default() -> Self {
        Self {
            manufacturer: "mtp-rs".into(),
            model: "Virtual Device".into(),
            serial: "virtual-0001".into(),
            storages: Vec::new(),
            supports_rename: true,
            supports_partial_object_64: true,
            supports_partial_object: true,
            supports_object_prop_list: true,
            prop_list_declined_properties: Vec::new(),
            event_poll_interval: Duration::from_millis(50),
            watch_backing_dirs: true,
            undescribable_objects: Vec::new(),
            utc_offset: crate::mtp::UtcOffset::UTC,
            dates_include_offset: false,
        }
    }
}

/// Configuration for a single storage within a virtual device.
///
/// Deliberately has no `Default`, unlike [`VirtualDeviceConfig`]: an unset
/// `backing_dir` is never caught. Nothing validates it, so the storage just
/// reports zero objects and zero used space, and the test fails somewhere far
/// from the cause. A compile error is the better outcome here.
#[derive(Debug, Clone)]
pub struct VirtualStorageConfig {
    /// Human-readable storage description (for example, "Internal Storage").
    pub description: String,
    /// Maximum storage capacity in bytes.
    pub capacity: u64,
    /// Local directory backing this storage. Files here become MTP objects.
    pub backing_dir: PathBuf,
    /// If true, write operations return `StoreReadOnly`.
    pub read_only: bool,
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn default_config_is_complete_except_storages() {
        let config = VirtualDeviceConfig::default();

        // A device listing must never show blanks.
        assert!(!config.manufacturer.is_empty());
        assert!(!config.model.is_empty());
        assert!(!config.serial.is_empty());

        // The one field the caller must fill in: only they know the backing dir.
        // `MtpDeviceBuilder::open_virtual` rejects an empty `storages`.
        assert!(config.storages.is_empty());

        assert!(config.supports_rename);
        assert!(config.supports_partial_object_64);
        assert!(config.supports_object_prop_list);
        assert_eq!(config.event_poll_interval, Duration::from_millis(50));
        assert!(config.watch_backing_dirs);
    }
}