idevice

The AFC (Apple File Conduit) service provides two types of handles for interacting with open files on a device:

1. FileDescriptor<'a>: A borrowed handle that holds a reference to an AfcClient. Use this when you want to perform file operations without taking ownership of the client.
2. OwnedFileDescriptor: An owned handle that contains the AfcClient. Use this when you want the file handle to manage the lifecycle of the client.

CRITICAL: Manual Resource Management Neither FileDescriptor nor OwnedFileDescriptor will automatically close the file descriptor on the device when they are dropped in Rust. To prevent leaking file descriptors on the device, you must explicitly call .close().await.

If you do not call .close(), the file descriptor will only be reclaimed automatically when the entire AFC session ends.

// Example of using FileDescriptor (borrowed)
// Note: .close() must be called to release the device-side FD
let mut fd = FileDescriptor::new(&mut afc_client, raw_fd, path_string);
fd.write_entire(b"data").await?;
fd.close().await?;

The com.apple.coredevice.displayservice manages the control plane and media negotiation for device screen mirroring.

Control Plane

Control operations (status, start, stop) are handled via plain RemoteXPC.

Media Negotiation

Media is negotiated as an AVConference session:

1. The client sends a negotiatorOffer (a zlib+protobuf blob).
2. The device responds to the offer.
3. The device streams plaintext RTP/HEVC to the receiver address specified in the parameters.

Session Lifecycle

To successfully establish a screen-sharing session, the client should follow this sequence:

1. Start Audio: Use build_start_audio_parameters and start_media_stream. This establishes the session rules.
2. Start Video: Use build_start_video_parameters and start_media_stream using the same client_session_id used for audio.
3. Stop: Use stop_media_stream to terminate active streams.

You can establish a connection to the Installation Proxy using one of three methods depending on your available handles:

1. Via IdeviceProvider: Use installation_proxy_connect with a valid IdeviceProviderHandle.
2. Via RSD (Remote Service Discovery): Use installation_proxy_connect_rsd if you have an AdapterHandle and an RsdHandshakeHandle (requires core_device_proxy and rsd features).
3. Via IdeviceSocket: Use installation_proxy_new with an IdeviceHandle. Note that this consumes the socket and it cannot be used again.

All connection functions return a pointer to an IdeviceFfiError on failure, or NULL on success. On success, the client pointer will be updated to a new InstallationProxyClientHandle.

// Example: Connecting via provider
InstallationProxyClientHandle* client = NULL;
IdeviceFfiError* err = installation_proxy_connect(provider_handle, &client);
if (err == NULL) {
    // Success
}

The idevice-rs-tools CLI is used to manage and manipulate iOS devices. It supports connecting via USB (using usbmuxd) or over a network (TCP).

Global Flags

All subcommands can use the following flags to specify the target device and connection method:

• --pairing-file <PATH>: The path to the pairing file to use.
• --host <IP_ADDRESS>: The host IP address to connect to (used with --pairing-file).
• --udid <UDID>: The unique device identifier (UDID) to use.

Connection Modes

1. USB Mode: If no --host is provided, the tool attempts to connect via usbmuxd. If --udid is provided, it targets that specific device. If no UDID is provided, it selects the first available USB device (falling back to the first available device if no USB devices are found).
2. Network Mode: If both --host and --pairing-file are provided, the tool connects via TCP to the specified host.

Environment Variables

• USBMUXD_SOCKET_ADDRESS: Allows specifying a custom socket address for usbmuxd connection.

# Example: Connect to a specific device via USB
idevice-rs-tools --udid 00008030-001A246E12345678 subcommand

# Example: Connect to a device over the network
idevice-rs-tools --host 192.168.1.50 --pairing-file ./my_device.plist subcommand

To interact with a device, you typically follow this workflow:

1. Connect to the usbmuxd daemon.
2. Retrieve a list of connected devices.
3. Create a provider using to_provider. The provider abstracts the complexity of opening multiple connections required by various services.
4. Use the provider to connect to specific clients, such as LockdowndClient.

Note: to_provider requires a UsbmuxdAddr, a port, and a program name.

use idevice::{lockdown::LockdowndClient, IdeviceService};
use idevice::usbmuxd::{UsbmuxdAddr, UsbmuxdConnection};

#[tokio::main]
async fn main() {
    // 1. Connect to usbmuxd
    let mut usbmuxd = UsbmuxdConnection::default()
        .await
        .expect("Unable to connect to usbmuxd");
    
    let devs = usbmuxd.get_devices().unwrap();
    if devs.is_empty() {
        eprintln!("No devices connected!");
        return;
    }

    // 2. Create a provider for the first device
    let provider = devs[0].to_provider(UsbmuxdAddr::from_env_var().unwrap(), 0, "example-program");

    // 3. Connect to the lockdown client
    let mut lockdown_client = match LockdowndClient::connect(&provider).await {
        Ok(l) => l,
        Err(e) => {
            eprintln!("Unable to connect to lockdown: {e:?}");
            return;
        }
    };

    // 4. Perform actions
    println!("{:?}", lockdown_client.get_value("ProductVersion").await);
}