idevice 0.1.59

A Rust library to interact with services on iOS devices.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152

//! iOS screenshotr service client
//!
//! Provides functionality for interacting with the screenshot service on iOS devices below iOS 17,
//! which allows taking screenshots.

use crate::{Idevice, IdeviceError, IdeviceService, obf};
use std::borrow::Cow;
use tokio::io::AsyncReadExt;
use tracing::{debug, warn};

#[derive(Debug)]
pub struct ScreenshotService {
    /// Underlying device connection
    pub idevice: Idevice,
}

impl IdeviceService for ScreenshotService {
    fn service_name() -> Cow<'static, str> {
        obf!("com.apple.mobile.screenshotr")
    }

    async fn from_stream(idevice: Idevice) -> Result<Self, IdeviceError> {
        let mut client = Self::new(idevice);
        // Perform DeviceLink handshake first
        client.dl_version_exchange().await?;
        Ok(client)
    }
}

impl ScreenshotService {
    pub fn new(idevice: Idevice) -> Self {
        Self { idevice }
    }

    async fn dl_version_exchange(&mut self) -> Result<(), IdeviceError> {
        debug!("Starting DeviceLink version exchange");
        // 1) Receive DLMessageVersionExchange
        let (msg, _arr) = self.receive_dl_message().await?;
        if msg != "DLMessageVersionExchange" {
            warn!("Expected DLMessageVersionExchange, got {msg}");
            return Err(IdeviceError::UnexpectedResponse(format!(
                "expected DLMessageVersionExchange, got {msg}"
            )));
        }

        // 2) Send DLVersionsOk with version 400
        let out = vec![
            plist::Value::String("DLMessageVersionExchange".into()),
            plist::Value::String("DLVersionsOk".into()),
            plist::Value::Integer(400u64.into()),
        ];
        self.send_dl_array(out).await?;

        // 3) Receive DLMessageDeviceReady
        let (msg2, _arr2) = self.receive_dl_message().await?;
        if msg2 != "DLMessageDeviceReady" {
            warn!("Expected DLMessageDeviceReady, got {msg2}");
            return Err(IdeviceError::UnexpectedResponse(format!(
                "expected DLMessageDeviceReady, got {msg2}"
            )));
        }
        Ok(())
    }

    /// Sends a raw DL array as binary plist
    async fn send_dl_array(&mut self, array: Vec<plist::Value>) -> Result<(), IdeviceError> {
        self.idevice.send_bplist(plist::Value::Array(array)).await
    }

    /// Receives any DL* message and returns (message_tag, full_array_value)
    pub async fn receive_dl_message(&mut self) -> Result<(String, plist::Value), IdeviceError> {
        if let Some(socket) = &mut self.idevice.socket {
            let mut buf = [0u8; 4];
            socket.read_exact(&mut buf).await?;
            let len = u32::from_be_bytes(buf);
            let mut body = vec![0; len as usize];
            socket.read_exact(&mut body).await?;
            let value: plist::Value = plist::from_bytes(&body)?;
            if let plist::Value::Array(arr) = &value
                && let Some(plist::Value::String(tag)) = arr.first()
            {
                return Ok((tag.clone(), value));
            }
            warn!("Invalid DL message format");
            Err(IdeviceError::UnexpectedResponse(
                "invalid DL message format, expected array with string tag".into(),
            ))
        } else {
            Err(IdeviceError::NoEstablishedConnection)
        }
    }

    pub async fn take_screenshot(&mut self) -> Result<Vec<u8>, IdeviceError> {
        // Send DLMessageTakeScreenshot

        let message_type_dict = crate::plist!(dict {
            "MessageType": "ScreenShotRequest"
        });

        let out = vec![
            plist::Value::String("DLMessageProcessMessage".into()),
            plist::Value::Dictionary(message_type_dict),
        ];
        self.send_dl_array(out).await?;

        // Receive DLMessageScreenshotData
        let (msg, value) = self.receive_dl_message().await?;
        if msg != "DLMessageProcessMessage" {
            warn!("Expected DLMessageProcessMessage, got {msg}");
            return Err(IdeviceError::UnexpectedResponse(format!(
                "expected DLMessageProcessMessage, got {msg}"
            )));
        }

        if let plist::Value::Array(arr) = &value
            && arr.len() == 2
        {
            if let Some(plist::Value::Dictionary(dict)) = arr.get(1) {
                if let Some(plist::Value::Data(data)) = dict.get("ScreenShotData") {
                    Ok(data.clone())
                } else {
                    warn!("Invalid ScreenShotData format");
                    Err(IdeviceError::UnexpectedResponse(
                        "missing ScreenShotData in response dictionary".into(),
                    ))
                }
            } else {
                warn!("Invalid DLMessageScreenshotData format");
                Err(IdeviceError::UnexpectedResponse(
                    "expected dictionary in DL screenshot response".into(),
                ))
            }
        } else {
            warn!("Invalid DLMessageScreenshotData format");
            Err(IdeviceError::UnexpectedResponse(
                "expected array with 2 elements in DL screenshot response".into(),
            ))
        }
    }
}

#[cfg(feature = "rsd")]
impl crate::RsdService for ScreenshotService {
    fn rsd_service_name() -> std::borrow::Cow<'static, str> {
        crate::obf!("com.apple.screenshotr.shim.remote")
    }
    async fn from_stream(stream: Box<dyn crate::ReadWrite>) -> Result<Self, crate::IdeviceError> {
        let mut idevice = crate::Idevice::new(stream, "");
        idevice.rsd_checkin().await?;
        Ok(Self::new(idevice))
    }
}