OS_remote_device C API (Reverse-Engineered)¶

Date: 2026-04-07 Source: RemoteServiceDiscovery.framework, SIP-disabled macOS 26 VM Status: Fully mapped. Connection is REQUIRED for RSDDeviceWrapper.

OS_remote_device Class¶

ObjC class in RemoteServiceDiscovery.framework (dyld shared cache). Inherits NSObject. Represents a remote device discovered via RSD protocol.

Instance Layout¶

Offset	Ivar	Type	Description
0	isa	Class	ObjC class pointer
8	device_name	char*	Human-readable name
16	device_alias	char*	Alias string
24	_remotexpc_tls_enabled	BOOL	TLS for RemoteXPC
28	_state	uint32_t	Device state enum
32	_type	uint32_t	Device type enum
40	_dq	dispatch_queue_t	Internal queue (MUST be concurrent)
48	_properties	xpc_object_t	XPC dictionary with device properties
56	_uuid	char*	Pointer to uuid_t (16 bytes binary, NOT string)
64	_device_id	uint64_t	Device ID
72	_messaging_protocol_version	uint64_t	Protocol version
80	_connection	xpc_object_t	XPC connection to device (REQUIRED)
88+	callbacks	various	Connected/disconnected callbacks + queues

Device Type Enum (remote_device_type_t)¶

Value	Name	Use case
1	loopback	Local
2	eos	EOS device
7	bonjour-peer	Bonjour discovered
8	ncm-device	USB NCM (iPhone)
10	coredevice-device	CoreDevice managed
14	network-peer	Network device (our type)
17	virtualmachine	VM device

Device State Enum (remote_device_state_t)¶

Value	Name
1	attached
2	connected
3	disconnected

Properties XPC Dictionary Keys¶

UniqueDeviceID, DeviceName, ProductType, HardwareModel, BuildVersion, OSVersion, DeviceClass, ModelNumber, SerialNumber, EthernetAddress, CPUArchitecture, Services (nested dict)

RSDDeviceWrapper¶

Swift class in CoreDevice.framework. Wraps OS_remote_device for CoreDevice system.

Init¶

RSDDeviceWrapper.__allocating_init(
    remoteDevice: OS_remote_device,     // RDI
    deviceIdentifier: DeviceIdentifier, // RSI (indirect, 33 bytes)
    // R13 = RSDDeviceWrapper metatype
) -> RSDDeviceWrapper                   // RAX = object pointer

Mangled: $s10CoreDevice16RSDDeviceWrapperC06remoteB016deviceIdentifierACSo03OS_e1_F0C_AA0bG0OtcfC

CRITICAL: init calls remote_device_copy_service_names¶

During init, RSDDeviceWrapper calls:

device.serviceNames (Swift getter)
  → remote_device_copy_service_names(device) (C function)
    → xpc_connection_send_message_with_reply_sync(device._connection, msg)

If _connection is NULL → crash: _xpc_api_misuse("Given: nil, required: OS_xpc_connection")

This means OS_remote_device MUST have a valid _connection before creating RSDDeviceWrapper.

Connection Requirement¶

The _connection ivar (offset 80) must be a valid xpc_connection_t that speaks the RemoteXPC protocol. When remote_device_copy_service_names is called, it sends:

{"cmd": "list_services"}

and expects a response with the service list.

How to provide _connection¶

For pymobiledevice3 tunnel integration, need to create an xpc_connection_t that connects to the tunnel endpoint (fd71:2692:7313::1 port 51233) and translates XPC messages to/from the RemoteXPC protocol that pymobiledevice3 speaks.

This is the RemoteXPC-over-TCP protocol: 1. TCP connection to tunnel IPv6 address + port 2. HTTP/2 framing (SETTINGS, HEADERS, DATA frames) 3. XPC binary messages inside DATA frames 4. Service multiplexing via stream IDs

Protocol Chain for Full Xcode Integration¶

Xcode → CoreDeviceService → RSDDeviceWrapper → OS_remote_device
  → _connection (xpc_connection_t)
    → RemoteXPC over TCP/HTTP2
      → pymobiledevice3 tunnel
        → iPhone RSD services

Apple Plugin Architecture (Internal Only)¶

CoreDevice plugin API exists but is COMPLETELY UNDOCUMENTED: - No public headers, swiftinterface, or documentation - No WWDC sessions about plugin development - No third-party plugins exist anywhere - Zero results on Apple Developer Forums

The plugin system is used internally by Apple for: - USB devices (RemotePairingDeviceRepresentationBrowser) - DFU/Recovery (RestorableDeviceRefDeviceRepresentationBrowser) - Virtual machines (VirtualMachineClientSupport, compiled into CoreDevice) - Static devices (StaticDeviceRepresentationBrowser)

ProviderType enum includes: .virtualMachine, .cloud — confirming non-USB use cases.