diff options
Diffstat (limited to 'include')
| -rw-r--r-- | include/Makefile.am | 1 | ||||
| -rw-r--r-- | include/libimobiledevice/ostrace.h | 198 |
2 files changed, 199 insertions, 0 deletions
diff --git a/include/Makefile.am b/include/Makefile.am index 2abaf49..59e54df 100644 --- a/include/Makefile.am +++ b/include/Makefile.am @@ -23,6 +23,7 @@ nobase_include_HEADERS = \ libimobiledevice/diagnostics_relay.h \ libimobiledevice/debugserver.h \ libimobiledevice/syslog_relay.h \ + libimobiledevice/ostrace.h \ libimobiledevice/mobileactivation.h \ libimobiledevice/preboard.h \ libimobiledevice/companion_proxy.h \ diff --git a/include/libimobiledevice/ostrace.h b/include/libimobiledevice/ostrace.h new file mode 100644 index 0000000..fb5a88f --- /dev/null +++ b/include/libimobiledevice/ostrace.h @@ -0,0 +1,198 @@ +/** + * @file libimobiledevice/ostrace.h + * @brief System log and tracing capabilities. + * \internal + * + * Copyright (c) 2020-2025 Nikias Bassen, All Rights Reserved. + * + * This library is free software; you can redistribute it and/or + * modify it under the terms of the GNU Lesser General Public + * License as published by the Free Software Foundation; either + * version 2.1 of the License, or (at your option) any later version. + * + * This library is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + * Lesser General Public License for more details. + * + * You should have received a copy of the GNU Lesser General Public + * License along with this library; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +#ifndef OSTRACE_H +#define OSTRACE_H + +#ifdef __cplusplus +extern "C" { +#endif + +#include <libimobiledevice/libimobiledevice.h> +#include <libimobiledevice/lockdown.h> + +/** Service identifier passed to lockdownd_start_service() to start the os trace relay service */ +#define OSTRACE_SERVICE_NAME "com.apple.os_trace_relay" + +/** Error Codes */ +typedef enum { + OSTRACE_E_SUCCESS = 0, + OSTRACE_E_INVALID_ARG = -1, + OSTRACE_E_MUX_ERROR = -2, + OSTRACE_E_SSL_ERROR = -3, + OSTRACE_E_NOT_ENOUGH_DATA = -4, + OSTRACE_E_TIMEOUT = -5, + OSTRACE_E_PLIST_ERROR = -6, + OSTRACE_E_REQUEST_FAILED = -7, + OSTRACE_E_UNKNOWN_ERROR = -256 +} ostrace_error_t; + +typedef struct ostrace_client_private ostrace_client_private; /**< \private */ +typedef ostrace_client_private *ostrace_client_t; /**< The client handle. */ + +#pragma pack(push,1) +struct ostrace_packet_header_t { + uint8_t marker; + uint32_t type; + uint32_t header_size; // 0x81 + uint32_t pid; + uint64_t procid; // == pid + unsigned char procuuid[16]; // procuuid + uint16_t procpath_len; // path to process + uint64_t aid; // activity id, usually 0 + uint64_t paid; // (parent?) activity id, usually 0 + uint64_t time_sec; // tv.tv_sec 64 bit + uint32_t time_usec; // tv.usec 32 bit + uint8_t unk06; + uint8_t level; // Notice=0, Info=0x01, Debug=0x02, Error=0x10, Fault=0x11 + uint8_t unk07; + uint8_t unk08; + uint8_t unk09; + uint8_t unk10; + uint8_t unk11; + uint8_t unk12; + uint64_t timestamp; // ? + uint32_t thread_id; + uint32_t unk13; // 0 + unsigned char imageuuid[16]; // framework/dylib uuid + uint16_t imagepath_len; // framework/dylib + uint32_t message_len; // actual log message + uint32_t offset; // offset for like timestamp or sth + uint16_t subsystem_len; // "subsystem" + uint16_t unk14; + uint16_t category_len; // "category" + uint16_t unk15; + uint32_t unk16; // 0 +}; +#pragma pack(pop) + +/** Receives unparsed ostrace data from the ostrace service */ +typedef void (*ostrace_activity_cb_t)(const unsigned char* buf, unsigned int len, void *user_data); + +/** Receives archive data from the ostrace service */ +typedef int (*ostrace_archive_write_cb_t)(const unsigned char* buf, unsigned int len, void *user_data); + +/* Interface */ + +/** + * Connects to the os_trace_relay service on the specified device. + * + * @param device The device to connect to. + * @param service The service descriptor returned by lockdownd_start_service. + * @param client Pointer that will point to a newly allocated + * ostrace_client_t upon successful return. Must be freed using + * ostrace_client_free() after use. + * + * @return OSTRACE_E_SUCCESS on success, OSTRACE_E_INVALID_ARG when + * client is NULL, or an OSTRACE_E_* error code otherwise. + */ +LIBIMOBILEDEVICE_API ostrace_error_t ostrace_client_new(idevice_t device, lockdownd_service_descriptor_t service, ostrace_client_t * client); + +/** + * Starts a new os_trace_relay service on the specified device and connects to it. + * + * @param device The device to connect to. + * @param client Pointer that will point to a newly allocated + * ostrace_client_t upon successful return. Must be freed using + * ostrace_client_free() after use. + * @param label The label to use for communication. Usually the program name. + * Pass NULL to disable sending the label in requests to lockdownd. + * + * @return OSTRACE_E_SUCCESS on success, or an OSTRACE_E_* error code otherwise. + */ +LIBIMOBILEDEVICE_API ostrace_error_t ostrace_client_start_service(idevice_t device, ostrace_client_t * client, const char* label); + +/** + * Disconnects a ostrace client from the device and frees up the + * ostrace client data. + * + * @param client The ostrace client to disconnect and free. + * + * @return OSTRACE_E_SUCCESS on success, OSTRACE_E_INVALID_ARG when + * client is NULL, or an OSTRACE_E_* error code otherwise. + */ +LIBIMOBILEDEVICE_API ostrace_error_t ostrace_client_free(ostrace_client_t client); + +/** + * Starts capturing OS trace activity data of the device using a callback. + * + * Use ostrace_stop_activity() to stop receiving the ostrace. + * + * @param client The ostrace client to use + * @param options Options dictionary to pass to StartActivity request. + * Valid options are MessageFilter (PLIST_INT, default 65535), + * Pid (PLIST_INT, default -1), and StreamFlags (PLIST_INT, default 60) + * @param callback Callback to receive data from ostrace. + * @param user_data Custom pointer passed to the callback function. + * @param user_data_free_func Function pointer that will be called when the + * activity is stopped to release user_data. Can be NULL for none. + * + * @return OSTRACE_E_SUCCESS on success, + * OSTRACE_E_INVALID_ARG when one or more parameters are + * invalid or OSTRACE_E_UNKNOWN_ERROR when an unspecified + * error occurs or an ostrace activity has already been started. + */ +LIBIMOBILEDEVICE_API ostrace_error_t ostrace_start_activity(ostrace_client_t client, plist_t options, ostrace_activity_cb_t callback, void* user_data); + +/** + * Stops the ostrace activity. + * + * Use ostrace_start_activity() to start receiving OS trace data. + * + * @param client The ostrace client to use + * + * @return OSTRACE_E_SUCCESS on success, + * OSTRACE_E_INVALID_ARG when one or more parameters are + * invalid or OSTRACE_E_UNKNOWN_ERROR when an unspecified + * error occurs or an ostrace activity has already been started. + */ +LIBIMOBILEDEVICE_API ostrace_error_t ostrace_stop_activity(ostrace_client_t client); + +/** + * Returns a dictionary with all currently running processes on the device. + * + * @param client The ostrace client to use + * @param list Pointer that will receive an allocated PLIST_DICT structure with the process data + * + * @return OSTRACE_E_SUCCESS on success, or an OSTRACE_E_* error code otherwise + */ +LIBIMOBILEDEVICE_API ostrace_error_t ostrace_get_pid_list(ostrace_client_t client, plist_t* list); + +/** + * Creates a syslog archive. + * + * @note The device will close the connection once the transfer is complete. The client + * is not usable after that anymore and must be disposed with ostrace_client_free. + * + * @param client The ostrace client to use + * @param options A dictionary with options for the request. + * Valid parameters are StartTime (PLIST_UINT), SizeLimit (PLIST_UINT), and AgeLimit (PLIST_UINT). + * + * @return OSTRACE_E_SUCCESS on success, or an OSTRACE_E_* error code otherwise + */ +LIBIMOBILEDEVICE_API ostrace_error_t ostrace_create_archive(ostrace_client_t client, plist_t options, ostrace_archive_write_cb_t callback, void* user_data); + +#ifdef __cplusplus +} +#endif + +#endif |