StephenDev0/idevice
1
0
Fork 0
mirror of https://github.com/jkcoxson/idevice.git synced 2026-03-02 06:26:15 +01:00
Code Issues Packages Projects Releases Wiki Activity

Write documentation for os_trace_relay FFI

Browse Source
This commit is contained in:
Jackson Coxson
2025-05-26 21:00:47 -06:00
parent 7070d6877e
commit 3025c797a3
2 changed files with 99 additions and 54 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
ffi/src/lib.rs
View File

@@ -23,7 +23,7 @@ pub mod logging;
pub mod misagent;
#[cfg(feature = "mobile_image_mounter")]
pub mod mobile_image_mounter;
#[cfg(feature = "os_trace_relay")]
#[cfg(feature = "syslog_relay")]
pub mod os_trace_relay;
mod pairing_file;
#[cfg(feature = "dvt")]

137
ffi/src/os_trace_relay.rs
View File

@@ -1,12 +1,12 @@
use std::os::raw::c_char;
use std::ffi::CString;
use std::os::raw::c_char;
use idevice::{os_trace_relay::OsTraceRelayClient, IdeviceError, IdeviceService};
use crate::{
provider::TcpProviderHandle, IdeviceErrorCode, RUNTIME
use idevice::{
IdeviceError, IdeviceService, os_trace_relay::OsTraceRelayClient, provider::IdeviceProvider,
};
use crate::{IdeviceErrorCode, RUNTIME, provider::IdeviceProviderHandle};
pub struct OsTraceRelayClientHandle(pub OsTraceRelayClient);
pub struct OsTraceRelayReceiverHandle(pub idevice::os_trace_relay::OsTraceRelayReceiver);
@@ -29,10 +29,21 @@ pub struct SyslogLabel {
pub category: *const c_char,
}
/// Connects to the relay with the given provider
///
/// # Arguments
/// * [`provider`] - A provider created by this library
/// * [`client`] - A pointer where the handle will be allocated
///
/// # Returns
/// 0 for success, an IdeviceErrorCode otherwise
///
/// # Safety
/// None of the arguments can be null. Provider must be allocated by this library.
#[unsafe(no_mangle)]
pub extern "C" fn os_trace_relay_connect_tcp(
provider: *mut TcpProviderHandle,
client: *mut *mut OsTraceRelayClientHandle
pub unsafe extern "C" fn os_trace_relay_connect(
provider: *mut IdeviceProviderHandle,
client: *mut *mut OsTraceRelayClientHandle,
) -> IdeviceErrorCode {
if provider.is_null() {
log::error!("Null pointer provided");
@@ -40,14 +51,8 @@ pub extern "C" fn os_trace_relay_connect_tcp(
}
let res: Result<OsTraceRelayClient, IdeviceError> = RUNTIME.block_on(async move {
let provider_box = unsafe { Box::from_raw(provider) };
let provider_ref = &provider_box.0;
let result = OsTraceRelayClient::connect(provider_ref).await;
std::mem::forget(provider_box);
result
let provider_ref: &dyn IdeviceProvider = unsafe { &*(*provider).0 };
OsTraceRelayClient::connect(provider_ref).await
});
match res {
@@ -63,18 +68,35 @@ pub extern "C" fn os_trace_relay_connect_tcp(
}
}
/// Frees the relay client
///
/// # Arguments
/// * [`handle`] - The relay client handle
///
/// # Safety
/// The handle must be allocated by this library
#[unsafe(no_mangle)]
pub extern "C" fn os_trace_relay_free(
handle: *mut OsTraceRelayClientHandle
) {
pub unsafe extern "C" fn os_trace_relay_free(handle: *mut OsTraceRelayClientHandle) {
if !handle.is_null() {
log::debug!("Freeing os trace relay client");
let _ = unsafe { Box::from_raw(handle) };
}
}
/// Creates a handle and starts receiving logs
///
/// # Arguments
/// * [`client`] - The relay client handle
/// * [`receiver`] - A pointer to allocate the new handle to
/// * [`pid`] - An optional pointer to a PID to get logs for. May be null.
///
/// # Returns
/// 0 for success, an IdeviceErrorCode otherwise
///
/// # Safety
/// The handle must be allocated by this library. It is consumed, and must never be used again.
#[unsafe(no_mangle)]
pub extern "C" fn os_trace_relay_start_trace(
pub unsafe extern "C" fn os_trace_relay_start_trace(
client: *mut OsTraceRelayClientHandle,
receiver: *mut *mut OsTraceRelayReceiverHandle,
pid: *const u32,
@@ -92,12 +114,7 @@ pub extern "C" fn os_trace_relay_start_trace(
let client_owned = unsafe { Box::from_raw(client) };
let res= RUNTIME.block_on(async {
client_owned
.0
.start_trace(pid_option)
.await
});
let res = RUNTIME.block_on(async { client_owned.0.start_trace(pid_option).await });
match res {
Ok(relay) => {
@@ -105,58 +122,75 @@ pub extern "C" fn os_trace_relay_start_trace(
unsafe { *receiver = Box::into_raw(boxed) };
IdeviceErrorCode::IdeviceSuccess
},
}
Err(e) => e.into(),
}
}
/// Frees the receiver handle
///
/// # Arguments
/// * [`handle`] - The relay receiver client handle
///
/// # Safety
/// The handle must be allocated by this library. It is consumed, and must never be used again.
#[unsafe(no_mangle)]
pub unsafe extern "C" fn os_trace_relay_receiver_free(
handle: *mut OsTraceRelayReceiverHandle
) {
pub unsafe extern "C" fn os_trace_relay_receiver_free(handle: *mut OsTraceRelayReceiverHandle) {
if !handle.is_null() {
log::debug!("Freeing syslog relay client");
let _ = unsafe { Box::from_raw(handle) };
}
}
/// Gets the PID list from the device
///
/// # Arguments
/// * [`client`] - The relay receiver client handle
/// * [`list`] - A pointer to allocate a list of PIDs to
///
/// # Returns
/// 0 for success, an IdeviceErrorCode otherwise
///
/// # Safety
/// The handle must be allocated by this library.
#[unsafe(no_mangle)]
pub extern "C" fn os_trace_relay_get_pid_list(
pub unsafe extern "C" fn os_trace_relay_get_pid_list(
client: *mut OsTraceRelayClientHandle,
list: *mut *mut Vec<u64>,
) -> IdeviceErrorCode {
let res = RUNTIME.block_on(async {
unsafe { &mut *client }
.0
.get_pid_list()
.await
});
let res = RUNTIME.block_on(async { unsafe { &mut *client }.0.get_pid_list().await });
match res {
Ok(r) => {
unsafe { *list = Box::into_raw(Box::new(r)) };
IdeviceErrorCode::IdeviceSuccess
},
}
Err(e) => e.into(),
}
}
/// Gets the next log from the relay
///
/// # Arguments
/// * [`client`] - The relay receiver client handle
/// * [`log`] - A pointer to allocate the new log
///
/// # Returns
/// 0 for success, an IdeviceErrorCode otherwise
///
/// # Safety
/// The handle must be allocated by this library.
#[unsafe(no_mangle)]
pub extern "C" fn os_trace_relay_next(
pub unsafe extern "C" fn os_trace_relay_next(
client: *mut OsTraceRelayReceiverHandle,
log: *mut *mut OsTraceLog
log: *mut *mut OsTraceLog,
) -> IdeviceErrorCode {
if client.is_null() {
log::error!("Null pointer provided");
return IdeviceErrorCode::InvalidArg;
}
let res = RUNTIME.block_on(async {
unsafe { &mut *client }
.0
.next()
.await
});
let res = RUNTIME.block_on(async { unsafe { &mut *client }.0.next().await });
match res {
Ok(r) => {
@@ -184,6 +218,16 @@ pub extern "C" fn os_trace_relay_next(
}
}
/// Frees a log received from the relay
///
/// # Arguments
/// * [`log`] - The log to free
///
/// # Returns
/// 0 for success, an IdeviceErrorCode otherwise
///
/// # Safety
/// The log must be allocated by this library. It is consumed and must not be used again.
#[unsafe(no_mangle)]
pub unsafe extern "C" fn os_trace_relay_free_log(log: *mut OsTraceLog) {
if !log.is_null() {
@@ -215,3 +259,4 @@ pub unsafe extern "C" fn os_trace_relay_free_log(log: *mut OsTraceLog) {
}
}
}