Add DVT screenshot bindings

cpp/examples/CMakeLists.txt

@@ -32,8 +32,8 @@ endif()
 # ---- Build the C++ wrapper library -----------------------------------------
 
 # Collect your .cpps
-file(GLOB IDEVICE_CPP_SOURCES
-  ${IDEVICE_CPP_SRC_DIR}/*.cpp
+file(GLOB_RECURSE IDEVICE_CPP_SOURCES
+  "${IDEVICE_CPP_SRC_DIR}/*.cpp"
 )
 
 file(GLOB PLIST_CPP_SOURCES

cpp/examples/location_simulation.cpp

@@ -6,11 +6,11 @@
 #include <thread>
 
 #include <idevice++/core_device_proxy.hpp>
+#include <idevice++/dvt/location_simulation.hpp>
+#include <idevice++/dvt/remote_server.hpp>
 #include <idevice++/ffi.hpp>
-#include <idevice++/location_simulation.hpp>
 #include <idevice++/provider.hpp>
 #include <idevice++/readwrite.hpp>
-#include <idevice++/remote_server.hpp>
 #include <idevice++/rsd.hpp>
 #include <idevice++/usbmuxd.hpp>
 

cpp/examples/screenshot.cpp

@@ -0,0 +1,106 @@
+// Jackson Coxson
+
+#include <cstdlib>
+#include <fstream>
+#include <iostream>
+#include <string>
+
+#include <idevice++/core_device_proxy.hpp>
+#include <idevice++/dvt/remote_server.hpp>
+#include <idevice++/dvt/screenshot.hpp>
+#include <idevice++/ffi.hpp>
+#include <idevice++/provider.hpp>
+#include <idevice++/readwrite.hpp>
+#include <idevice++/rsd.hpp>
+#include <idevice++/usbmuxd.hpp>
+
+using namespace IdeviceFFI;
+
+[[noreturn]]
+static void die(const char* msg, const FfiError& e) {
+    std::cerr << msg << ": " << e.message << "\n";
+    std::exit(1);
+}
+
+int main(int argc, char** argv) {
+    // Usage:
+    //   take_screenshot <output.png>
+    if (argc != 2) {
+        std::cerr << "Usage:\n"
+                  << "  " << argv[0] << " <output.png>\n";
+        return 2;
+    }
+
+    std::string out_path = argv[1];
+
+    // 1) Connect to usbmuxd and pick first device
+    auto mux     = UsbmuxdConnection::default_new(/*tag*/ 0).expect("failed to connect to usbmuxd");
+
+    auto devices = mux.get_devices().expect("failed to list devices");
+    if (devices.empty()) {
+        std::cerr << "no devices connected\n";
+        return 1;
+    }
+    auto& dev  = (devices)[0];
+
+    auto  udid = dev.get_udid();
+    if (udid.is_none()) {
+        std::cerr << "device has no UDID\n";
+        return 1;
+    }
+    auto mux_id = dev.get_id();
+    if (mux_id.is_none()) {
+        std::cerr << "device has no mux id\n";
+        return 1;
+    }
+
+    // 2) Provider via default usbmuxd addr
+    auto              addr  = UsbmuxdAddr::default_new();
+    const uint32_t    tag   = 0;
+    const std::string label = "screenshot-client";
+
+    auto              provider =
+        Provider::usbmuxd_new(std::move(addr), tag, udid.unwrap(), mux_id.unwrap(), label)
+            .expect("failed to create provider");
+
+    // 3) CoreDeviceProxy
+    auto cdp = CoreDeviceProxy::connect(provider).unwrap_or_else(
+        [](FfiError e) -> CoreDeviceProxy { die("failed to connect CoreDeviceProxy", e); });
+
+    auto rsd_port = cdp.get_server_rsd_port().unwrap_or_else(
+        [](FfiError err) -> uint16_t { die("failed to get server RSD port", err); });
+
+    // 4) Create software tunnel adapter (consumes proxy)
+    auto adapter =
+        std::move(cdp).create_tcp_adapter().expect("failed to create software tunnel adapter");
+
+    // 5) Connect adapter to RSD → ReadWrite stream
+    auto stream = adapter.connect(rsd_port).expect("failed to connect RSD stream");
+
+    // 6) RSD handshake (consumes stream)
+    auto rsd    = RsdHandshake::from_socket(std::move(stream)).expect("failed RSD handshake");
+
+    // 7) RemoteServer over RSD (borrows adapter + handshake)
+    auto rs = RemoteServer::connect_rsd(adapter, rsd).expect("failed to connect to RemoteServer");
+
+    // 8) ScreenshotClient (borrows RemoteServer)
+    auto ss = ScreenshotClient::create(rs).unwrap_or_else(
+        [](FfiError e) -> ScreenshotClient { die("failed to create ScreenshotClient", e); });
+
+    // 9) Capture screenshot
+    auto buf = ss.capture().unwrap_or_else(
+        [](FfiError e) -> std::vector<uint8_t> { die("failed to capture screenshot", e); });
+
+    // 10) Write PNG file
+    std::ofstream out(out_path, std::ios::binary);
+    if (!out.is_open()) {
+        std::cerr << "failed to open output file: " << out_path << "\n";
+        return 1;
+    }
+
+    out.write(reinterpret_cast<const char*>(buf.data()), static_cast<std::streamsize>(buf.size()));
+    out.close();
+
+    std::cout << "Screenshot saved to " << out_path << " (" << buf.size() << " bytes)\n";
+    return 0;
+}

cpp/include/idevice++/dvt/location_simulation.hpp

@@ -2,7 +2,7 @@
 
 #pragma once
 #include <idevice++/bindings.hpp>
-#include <idevice++/remote_server.hpp>
+#include <idevice++/dvt/remote_server.hpp>
 #include <idevice++/result.hpp>
 #include <memory>
 

cpp/include/idevice++/dvt/process_control.hpp

@@ -2,7 +2,7 @@
 
 #pragma once
 #include <idevice++/bindings.hpp>
-#include <idevice++/remote_server.hpp>
+#include <idevice++/dvt/remote_server.hpp>
 #include <idevice++/result.hpp>
 #include <memory>
 

cpp/include/idevice++/dvt/screenshot.hpp

@@ -0,0 +1,49 @@
+// Jackson Coxson
+
+#pragma once
+#include <cstring>
+#include <idevice++/bindings.hpp>
+#include <idevice++/dvt/remote_server.hpp>
+#include <idevice++/result.hpp>
+#include <memory>
+#include <vector>
+
+namespace IdeviceFFI {
+
+using ScreenshotClientPtr =
+    std::unique_ptr<ScreenshotClientHandle,
+                    FnDeleter<ScreenshotClientHandle, screenshot_client_free>>;
+
+/// C++ wrapper around the ScreenshotClient FFI handle
+///
+/// Provides a high-level interface for capturing screenshots
+/// from a connected iOS device through the DVT service.
+class ScreenshotClient {
+  public:
+    /// Creates a new ScreenshotClient using an existing RemoteServer.
+    ///
+    /// The RemoteServer is borrowed, not consumed.
+    static Result<ScreenshotClient, FfiError> create(RemoteServer& server);
+
+    /// Captures a screenshot and returns it as a PNG buffer.
+    ///
+    /// On success, returns a vector containing PNG-encoded bytes.
+    Result<std::vector<uint8_t>, FfiError>    capture();
+
+    ~ScreenshotClient() noexcept                               = default;
+    ScreenshotClient(ScreenshotClient&&) noexcept              = default;
+    ScreenshotClient& operator=(ScreenshotClient&&) noexcept   = default;
+    ScreenshotClient(const ScreenshotClient&)                  = delete;
+    ScreenshotClient&       operator=(const ScreenshotClient&) = delete;
+
+    ScreenshotClientHandle* raw() const noexcept { return handle_.get(); }
+    static ScreenshotClient adopt(ScreenshotClientHandle* h) noexcept {
+        return ScreenshotClient(h);
+    }
+
+  private:
+    explicit ScreenshotClient(ScreenshotClientHandle* h) noexcept : handle_(h) {}
+    ScreenshotClientPtr handle_{};
+};
+
+} // namespace IdeviceFFI

cpp/src/dvt/location_simulation.cpp

@@ -1,6 +1,6 @@
 // Jackson Coxson
 
-#include <idevice++/location_simulation.hpp>
+#include <idevice++/dvt/location_simulation.hpp>
 
 namespace IdeviceFFI {
 

cpp/src/dvt/process_control.cpp

@@ -1,6 +1,6 @@
 // Jackson Coxson
 
-#include <idevice++/process_control.hpp>
+#include <idevice++/dvt/process_control.hpp>
 
 namespace IdeviceFFI {
 

cpp/src/dvt/remote_server.cpp

@@ -1,6 +1,6 @@
 // Jackson Coxson
 
-#include <idevice++/remote_server.hpp>
+#include <idevice++/dvt/remote_server.hpp>
 
 namespace IdeviceFFI {
 

cpp/src/dvt/screenshot.cpp

@@ -0,0 +1,37 @@
+// Jackson Coxson
+
+#include <idevice++/dvt/screenshot.hpp>
+
+namespace IdeviceFFI {
+
+Result<ScreenshotClient, FfiError> ScreenshotClient::create(RemoteServer& server) {
+    ScreenshotClientHandle* out = nullptr;
+    FfiError                e(::screenshot_client_new(server.raw(), &out));
+    if (e) {
+        return Err(e);
+    }
+    return Ok(ScreenshotClient::adopt(out));
+}
+
+Result<std::vector<uint8_t>, FfiError> ScreenshotClient::capture() {
+    uint8_t* data = nullptr;
+    size_t   len  = 0;
+
+    FfiError e(::screenshot_client_clear(handle_.get(), &data, &len));
+    if (e) {
+        return Err(e);
+    }
+
+    // Copy into a C++ buffer
+    std::vector<uint8_t> out(len);
+    if (len > 0 && data != nullptr) {
+        std::memcpy(out.data(), data, len);
+    }
+
+    // Free Rust-allocated data
+    ::idevice_data_free(data, len);
+
+    return Ok(std::move(out));
+}
+
+} // namespace IdeviceFFI

ffi/src/dvt/location_simulation.rs

@@ -4,7 +4,7 @@ use std::ptr::null_mut;
 
 use idevice::{ReadWrite, dvt::location_simulation::LocationSimulationClient};
 
-use crate::{IdeviceFfiError, RUNTIME, ffi_err, remote_server::RemoteServerHandle};
+use crate::{IdeviceFfiError, RUNTIME, dvt::remote_server::RemoteServerHandle, ffi_err};
 
 /// Opaque handle to a ProcessControlClient
 pub struct LocationSimulationHandle<'a>(pub LocationSimulationClient<'a, Box<dyn ReadWrite>>);

ffi/src/dvt/mod.rs

@@ -0,0 +1,8 @@
+// Jackson Coxson
+
+#[cfg(feature = "location_simulation")]
+pub mod location_simulation;
+
+pub mod process_control;
+pub mod remote_server;
+pub mod screenshot;

ffi/src/dvt/process_control.rs

@@ -8,7 +8,7 @@ use std::{
 use idevice::{ReadWrite, dvt::process_control::ProcessControlClient};
 use plist::{Dictionary, Value};
 
-use crate::{IdeviceFfiError, RUNTIME, ffi_err, remote_server::RemoteServerHandle};
+use crate::{IdeviceFfiError, RUNTIME, dvt::remote_server::RemoteServerHandle, ffi_err};
 
 /// Opaque handle to a ProcessControlClient
 pub struct ProcessControlHandle<'a>(pub ProcessControlClient<'a, Box<dyn ReadWrite>>);

ffi/src/dvt/screenshot.rs

@@ -0,0 +1,113 @@
+// Jackson Coxson
+
+use std::ptr::null_mut;
+
+use idevice::{ReadWrite, dvt::screenshot::ScreenshotClient};
+
+use crate::{IdeviceFfiError, RUNTIME, dvt::remote_server::RemoteServerHandle, ffi_err};
+
+/// An opaque FFI handle for a [`ScreenshotClient`].
+///
+/// This type wraps a [`ScreenshotClient`] that communicates with
+/// a connected device to capture screenshots through the DVT (Device Virtualization Toolkit) service.
+pub struct ScreenshotClientHandle<'a>(pub ScreenshotClient<'a, Box<dyn ReadWrite>>);
+
+/// Creates a new [`ScreenshotClient`] associated with a given [`RemoteServerHandle`].
+///
+/// # Arguments
+/// * `server` - A pointer to a valid [`RemoteServerHandle`], previously created by this library.
+/// * `handle` - A pointer to a location where the newly created [`ScreenshotClientHandle`] will be stored.
+///
+/// # Returns
+/// * `null_mut()` on success.
+/// * A pointer to an [`IdeviceFfiError`] on failure.
+///
+/// # Safety
+/// - `server` must be a non-null pointer to a valid remote server handle allocated by this library.
+/// - `handle` must be a non-null pointer to a writable memory location where the handle will be stored.
+/// - The returned handle must later be freed using [`screenshot_client_free`].
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn screenshot_client_new(
+    server: *mut RemoteServerHandle,
+    handle: *mut *mut ScreenshotClientHandle<'static>,
+) -> *mut IdeviceFfiError {
+    if server.is_null() || handle.is_null() {
+        return ffi_err!(IdeviceError::FfiInvalidArg);
+    }
+
+    let server = unsafe { &mut (*server).0 };
+    let res = RUNTIME.block_on(async move { ScreenshotClient::new(server).await });
+
+    match res {
+        Ok(client) => {
+            let boxed = Box::new(ScreenshotClientHandle(client));
+            unsafe { *handle = Box::into_raw(boxed) };
+            null_mut()
+        }
+        Err(e) => ffi_err!(e),
+    }
+}
+
+/// Frees a [`ScreenshotClientHandle`].
+///
+/// This releases all memory associated with the handle.  
+/// After calling this function, the handle pointer must not be used again.
+///
+/// # Arguments
+/// * `handle` - Pointer to a [`ScreenshotClientHandle`] previously returned by [`screenshot_client_new`].
+///
+/// # Safety
+/// - `handle` must either be `NULL` or a valid pointer created by this library.
+/// - Double-freeing or using the handle after freeing causes undefined behavior.
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn screenshot_client_free(handle: *mut ScreenshotClientHandle<'static>) {
+    if !handle.is_null() {
+        let _ = unsafe { Box::from_raw(handle) };
+    }
+}
+
+/// Captures a screenshot from the connected device.
+///
+/// On success, this function writes a pointer to the PNG-encoded screenshot data and its length
+/// into the provided output arguments. The caller is responsible for freeing this data using
+/// `idevice_data_free`.
+///
+/// # Arguments
+/// * `handle` - A pointer to a valid [`ScreenshotClientHandle`].
+/// * `data` - Output pointer where the screenshot buffer pointer will be written.
+/// * `len` - Output pointer where the buffer length (in bytes) will be written.
+///
+/// # Returns
+/// * `null_mut()` on success.
+/// * A pointer to an [`IdeviceFfiError`] on failure.
+///
+/// # Safety
+/// - `handle` must be a valid pointer to a [`ScreenshotClientHandle`].
+/// - `data` and `len` must be valid writable pointers.
+/// - The data returned through `*data` must be freed by the caller with `idevice_data_free`.
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn screenshot_client_clear(
+    handle: *mut ScreenshotClientHandle<'static>,
+    data: *mut *mut u8,
+    len: *mut usize,
+) -> *mut IdeviceFfiError {
+    if handle.is_null() || data.is_null() || len.is_null() {
+        return ffi_err!(IdeviceError::FfiInvalidArg);
+    }
+
+    let client = unsafe { &mut (*handle).0 };
+    let res = RUNTIME.block_on(async move { client.take_screenshot().await });
+
+    match res {
+        Ok(r) => {
+            let mut r = r.into_boxed_slice();
+            unsafe {
+                *data = r.as_mut_ptr();
+                *len = r.len();
+            }
+            std::mem::forget(r); // Prevent Rust from freeing the buffer
+            null_mut()
+        }
+        Err(e) => ffi_err!(e),
+    }
+}

ffi/src/lib.rs

@@ -12,13 +12,13 @@ pub mod core_device;
 pub mod core_device_proxy;
 #[cfg(feature = "debug_proxy")]
 pub mod debug_proxy;
+#[cfg(feature = "dvt")]
+pub mod dvt;
 mod errors;
 #[cfg(feature = "heartbeat")]
 pub mod heartbeat;
 #[cfg(feature = "installation_proxy")]
 pub mod installation_proxy;
-#[cfg(feature = "location_simulation")]
-pub mod location_simulation;
 pub mod lockdown;
 pub mod logging;
 #[cfg(feature = "misagent")]
@@ -28,11 +28,7 @@ pub mod mobile_image_mounter;
 #[cfg(feature = "syslog_relay")]
 pub mod os_trace_relay;
 mod pairing_file;
-#[cfg(feature = "dvt")]
-pub mod process_control;
 pub mod provider;
-#[cfg(feature = "dvt")]
-pub mod remote_server;
 #[cfg(feature = "xpc")]
 pub mod rsd;
 #[cfg(feature = "springboardservices")]