diff options
Diffstat (limited to 'include')
26 files changed, 177 insertions, 86 deletions
diff --git a/include/libimobiledevice/afc.h b/include/libimobiledevice/afc.h index b59b070..a2d70d3 100644 --- a/include/libimobiledevice/afc.h +++ b/include/libimobiledevice/afc.h @@ -31,6 +31,7 @@ extern "C" { #include <libimobiledevice/libimobiledevice.h> #include <libimobiledevice/lockdown.h> +/** Service identifier passed to lockdownd_start_service() to start the AFC service */ #define AFC_SERVICE_NAME "com.apple.afc" /** Error Codes */ @@ -89,7 +90,7 @@ typedef enum { AFC_LOCK_UN = 8 | 4 /**< unlock */ } afc_lock_op_t; -typedef struct afc_client_private afc_client_private; +typedef struct afc_client_private afc_client_private; /**< \private */ typedef afc_client_private *afc_client_t; /**< The client handle. */ /* Interface */ diff --git a/include/libimobiledevice/companion_proxy.h b/include/libimobiledevice/companion_proxy.h index 19c88eb..d786766 100644 --- a/include/libimobiledevice/companion_proxy.h +++ b/include/libimobiledevice/companion_proxy.h @@ -30,6 +30,7 @@ extern "C" { #include <libimobiledevice/libimobiledevice.h> #include <libimobiledevice/lockdown.h> +/** Service identifier passed to lockdownd_start_service() to start the companion proxy service */ #define COMPANION_PROXY_SERVICE_NAME "com.apple.companion_proxy" /** Error Codes */ @@ -48,9 +49,10 @@ typedef enum { COMPANION_PROXY_E_UNKNOWN_ERROR = -256 } companion_proxy_error_t; -typedef struct companion_proxy_client_private companion_proxy_client_private; +typedef struct companion_proxy_client_private companion_proxy_client_private; /**< \private */ typedef companion_proxy_client_private *companion_proxy_client_t; /**< The client handle. */ +/** Callback for companion device events */ typedef void (*companion_proxy_device_event_cb_t) (plist_t event, void* userdata); /** @@ -119,7 +121,7 @@ companion_proxy_error_t companion_proxy_receive(companion_proxy_client_t client, * Retrieves a list of paired devices. * * @param client The companion_proxy client - * @param devices Point that will receive a PLIST_ARRAY with paired device UDIDs + * @param paired_devices Point that will receive a PLIST_ARRAY with paired device UDIDs * * @note The device closes the connection after sending the reply. * @@ -161,6 +163,8 @@ companion_proxy_error_t companion_proxy_stop_listening_for_devices(companion_pro * @param client The companion_proxy client * @param companion_udid UDID of the (paired) companion device * @param key The key to retrieve the value for + * @param value A pointer to a plist_t that will receive the value for the given key. + * The consumer is responsible for freeing the value with plist_free() when no longer needed. * * @note The device closes the connection after sending the reply. * diff --git a/include/libimobiledevice/debugserver.h b/include/libimobiledevice/debugserver.h index 90ba514..eaa7c48 100644 --- a/include/libimobiledevice/debugserver.h +++ b/include/libimobiledevice/debugserver.h @@ -30,7 +30,9 @@ extern "C" { #include <libimobiledevice/libimobiledevice.h> #include <libimobiledevice/lockdown.h> +/** Service identifier passed to lockdownd_start_service() to start the debugserver service */ #define DEBUGSERVER_SERVICE_NAME "com.apple.debugserver" +/** Service identifier passed to lockdownd_start_service() to start the secure debugserver service */ #define DEBUGSERVER_SECURE_SERVICE_NAME DEBUGSERVER_SERVICE_NAME ".DVTSecureSocketProxy" /** Error Codes */ @@ -44,10 +46,10 @@ typedef enum { DEBUGSERVER_E_UNKNOWN_ERROR = -256 } debugserver_error_t; -typedef struct debugserver_client_private debugserver_client_private; +typedef struct debugserver_client_private debugserver_client_private; /**< \private */ typedef debugserver_client_private *debugserver_client_t; /**< The client handle. */ -typedef struct debugserver_command_private debugserver_command_private; +typedef struct debugserver_command_private debugserver_command_private; /**< \private */ typedef debugserver_command_private *debugserver_command_t; /**< The command handle. */ /* Interface */ diff --git a/include/libimobiledevice/diagnostics_relay.h b/include/libimobiledevice/diagnostics_relay.h index d37ad74..f80a86b 100644 --- a/include/libimobiledevice/diagnostics_relay.h +++ b/include/libimobiledevice/diagnostics_relay.h @@ -30,6 +30,7 @@ extern "C" { #include <libimobiledevice/libimobiledevice.h> #include <libimobiledevice/lockdown.h> +/** Service identifier passed to lockdownd_start_service() to start the diagnostics relay service */ #define DIAGNOSTICS_RELAY_SERVICE_NAME "com.apple.mobile.diagnostics_relay" /** Error Codes */ @@ -42,18 +43,19 @@ typedef enum { DIAGNOSTICS_RELAY_E_UNKNOWN_ERROR = -256 } diagnostics_relay_error_t; +/** Action type for #diagnostics_relay_restart and #diagnostics_relay_shutdown */ typedef enum { DIAGNOSTICS_RELAY_ACTION_FLAG_WAIT_FOR_DISCONNECT = 1 << 1, DIAGNOSTICS_RELAY_ACTION_FLAG_DISPLAY_PASS = 1 << 2, DIAGNOSTICS_RELAY_ACTION_FLAG_DISPLAY_FAIL = 1 << 3 } diagnostics_relay_action_t; -#define DIAGNOSTICS_RELAY_REQUEST_TYPE_ALL "All" -#define DIAGNOSTICS_RELAY_REQUEST_TYPE_WIFI "WiFi" -#define DIAGNOSTICS_RELAY_REQUEST_TYPE_GAS_GAUGE "GasGauge" -#define DIAGNOSTICS_RELAY_REQUEST_TYPE_NAND "NAND" +#define DIAGNOSTICS_RELAY_REQUEST_TYPE_ALL "All" /**< Query all available diagnostics */ +#define DIAGNOSTICS_RELAY_REQUEST_TYPE_WIFI "WiFi" /**< Query WiFi diagnostics */ +#define DIAGNOSTICS_RELAY_REQUEST_TYPE_GAS_GAUGE "GasGauge" /**< Query GasGauge diagnostics */ +#define DIAGNOSTICS_RELAY_REQUEST_TYPE_NAND "NAND" /**< Query NAND diagnostics */ -typedef struct diagnostics_relay_client_private diagnostics_relay_client_private; +typedef struct diagnostics_relay_client_private diagnostics_relay_client_private; /**< \private */ typedef diagnostics_relay_client_private *diagnostics_relay_client_t; /**< The client handle. */ /** @@ -158,14 +160,13 @@ diagnostics_relay_error_t diagnostics_relay_restart(diagnostics_relay_client_t c diagnostics_relay_error_t diagnostics_relay_shutdown(diagnostics_relay_client_t client, diagnostics_relay_action_t flags); /** - * Shutdown of the device and optionally show a user notification. + * Request diagnostics information for a given type. * * @param client The diagnostics_relay client - * @param flags A binary flag combination of - * DIAGNOSTICS_RELAY_ACTION_FLAG_WAIT_FOR_DISCONNECT to wait until - * diagnostics_relay_client_free() disconnects before execution and - * DIAGNOSTICS_RELAY_ACTION_FLAG_DISPLAY_FAIL to show a "FAIL" dialog - * or DIAGNOSTICS_RELAY_ACTION_FLAG_DISPLAY_PASS to show an "OK" dialog + * @param type The type or domain to query for diagnostics. Some known values + * are "All", "WiFi", "GasGauge", and "NAND". + * @param diagnostics A pointer to plist_t that will receive the diagnostics information. + * The consumer has to free the allocated memory with plist_free() when no longer needed. * * @return DIAGNOSTICS_RELAY_E_SUCCESS on success, * DIAGNOSTICS_RELAY_E_INVALID_ARG when client is NULL, @@ -174,10 +175,50 @@ diagnostics_relay_error_t diagnostics_relay_shutdown(diagnostics_relay_client_t */ diagnostics_relay_error_t diagnostics_relay_request_diagnostics(diagnostics_relay_client_t client, const char* type, plist_t* diagnostics); +/** + * Query one or multiple MobileGestalt keys. + * + * @param client The diagnostics_relay client + * @param keys A PLIST_ARRAY with the keys to query. + * @param result A pointer to plist_t that will receive the result. The consumer + * has to free the allocated memory with plist_free() when no longer needed. + * + * @return DIAGNOSTICS_RELAY_E_SUCCESS on success, + * DIAGNOSTICS_RELAY_E_INVALID_ARG when client is NULL, + * DIAGNOSTICS_RELAY_E_PLIST_ERROR if the device did not acknowledge the + * request + */ diagnostics_relay_error_t diagnostics_relay_query_mobilegestalt(diagnostics_relay_client_t client, plist_t keys, plist_t* result); +/** + * Query an IORegistry entry of a given class. + * + * @param client The diagnostics_relay client + * @param entry_name The IORegistry entry name to query. + * @param entry_class The IORegistry class to query. + * @param result A pointer to plist_t that will receive the result. The consumer + * has to free the allocated memory with plist_free() when no longer needed. + * + * @return DIAGNOSTICS_RELAY_E_SUCCESS on success, + * DIAGNOSTICS_RELAY_E_INVALID_ARG when client is NULL, + * DIAGNOSTICS_RELAY_E_PLIST_ERROR if the device did not acknowledge the + * request + */ diagnostics_relay_error_t diagnostics_relay_query_ioregistry_entry(diagnostics_relay_client_t client, const char* entry_name, const char* entry_class, plist_t* result); +/** + * Query an IORegistry plane. + * + * @param client The diagnostics_relay client + * @param plane The IORegistry plane name to query. + * @param result A pointer to plist_t that will receive the result. The consumer + * has to free the allocated memory with plist_free() when no longer needed. + * + * @return DIAGNOSTICS_RELAY_E_SUCCESS on success, + * DIAGNOSTICS_RELAY_E_INVALID_ARG when client is NULL, + * DIAGNOSTICS_RELAY_E_PLIST_ERROR if the device did not acknowledge the + * request + */ diagnostics_relay_error_t diagnostics_relay_query_ioregistry_plane(diagnostics_relay_client_t client, const char* plane, plist_t* result); #ifdef __cplusplus diff --git a/include/libimobiledevice/file_relay.h b/include/libimobiledevice/file_relay.h index e41bb2d..6b30e65 100644 --- a/include/libimobiledevice/file_relay.h +++ b/include/libimobiledevice/file_relay.h @@ -32,6 +32,7 @@ extern "C" { #include <libimobiledevice/libimobiledevice.h> #include <libimobiledevice/lockdown.h> +/** Service identifier passed to lockdownd_start_service() to start the file relay service */ #define FILE_RELAY_SERVICE_NAME "com.apple.mobile.file_relay" /** Error Codes */ @@ -46,7 +47,7 @@ typedef enum { FILE_RELAY_E_UNKNOWN_ERROR = -256 } file_relay_error_t; -typedef struct file_relay_client_private file_relay_client_private; +typedef struct file_relay_client_private file_relay_client_private; /**< \private */ typedef file_relay_client_private *file_relay_client_t; /**< The client handle. */ /** @@ -110,8 +111,7 @@ file_relay_error_t file_relay_client_free(file_relay_client_t client); * data using idevice_connection_receive(). The connection will be closed * automatically by the device, but use file_relay_client_free() to clean * up properly. - * @param timeout Maximum time in milliseconds to wait for data. - * + * * @note WARNING: Don't call this function without reading the data afterwards. * A directory mobile_file_relay.XXXX used for creating the archive will * remain in the /tmp directory otherwise. @@ -144,6 +144,7 @@ file_relay_error_t file_relay_request_sources(file_relay_client_t client, const * data using idevice_connection_receive(). The connection will be closed * automatically by the device, but use file_relay_client_free() to clean * up properly. + * @param timeout Maximum time in milliseconds to wait for data. * * @note WARNING: Don't call this function without reading the data afterwards. * A directory mobile_file_relay.XXXX used for creating the archive will diff --git a/include/libimobiledevice/heartbeat.h b/include/libimobiledevice/heartbeat.h index 1f5344a..42b318d 100644 --- a/include/libimobiledevice/heartbeat.h +++ b/include/libimobiledevice/heartbeat.h @@ -30,6 +30,7 @@ extern "C" { #include <libimobiledevice/libimobiledevice.h> #include <libimobiledevice/lockdown.h> +/** Service identifier passed to lockdownd_start_service() to start the heartbeat service */ #define HEARTBEAT_SERVICE_NAME "com.apple.mobile.heartbeat" /** Error Codes */ @@ -44,7 +45,7 @@ typedef enum { HEARTBEAT_E_UNKNOWN_ERROR = -256 } heartbeat_error_t; -typedef struct heartbeat_client_private heartbeat_client_private; +typedef struct heartbeat_client_private heartbeat_client_private; /**< \private */ typedef heartbeat_client_private *heartbeat_client_t; /**< The client handle. */ /** @@ -116,7 +117,7 @@ heartbeat_error_t heartbeat_receive(heartbeat_client_t client, plist_t * plist); * @param client The heartbeat client to use for receiving * @param plist pointer to a plist_t that will point to the received plist * upon successful return - * @param timeout Maximum time in milliseconds to wait for data. + * @param timeout_ms Maximum time in milliseconds to wait for data. * * @return HEARTBEAT_E_SUCCESS on success, * HEARTBEAT_E_INVALID_ARG when client or *plist is NULL, diff --git a/include/libimobiledevice/house_arrest.h b/include/libimobiledevice/house_arrest.h index 5a42838..3785847 100644 --- a/include/libimobiledevice/house_arrest.h +++ b/include/libimobiledevice/house_arrest.h @@ -32,6 +32,7 @@ extern "C" { #include <libimobiledevice/lockdown.h> #include <libimobiledevice/afc.h> +/** Service identifier passed to lockdownd_start_service() to start the house arrest service */ #define HOUSE_ARREST_SERVICE_NAME "com.apple.mobile.house_arrest" /** Error Codes */ @@ -44,7 +45,7 @@ typedef enum { HOUSE_ARREST_E_UNKNOWN_ERROR = -256 } house_arrest_error_t; -typedef struct house_arrest_client_private house_arrest_client_private; +typedef struct house_arrest_client_private house_arrest_client_private; /**< \private */ typedef house_arrest_client_private *house_arrest_client_t; /**< The client handle. */ /* Interface */ diff --git a/include/libimobiledevice/installation_proxy.h b/include/libimobiledevice/installation_proxy.h index e96e224..87132b9 100644 --- a/include/libimobiledevice/installation_proxy.h +++ b/include/libimobiledevice/installation_proxy.h @@ -33,6 +33,7 @@ extern "C" { #include <libimobiledevice/libimobiledevice.h> #include <libimobiledevice/lockdown.h> +/** Service identifier passed to lockdownd_start_service() to start the installation proxy service */ #define INSTPROXY_SERVICE_NAME "com.apple.mobile.installation_proxy" /** Error Codes */ @@ -107,7 +108,7 @@ typedef enum { INSTPROXY_E_UNKNOWN_ERROR = -256 } instproxy_error_t; -typedef struct instproxy_client_private instproxy_client_private; +typedef struct instproxy_client_private instproxy_client_private; /**< \private */ typedef instproxy_client_private *instproxy_client_t; /**< The client handle. */ /** Reports the status response of the given command */ @@ -441,8 +442,8 @@ void instproxy_status_get_current_list(plist_t status, uint64_t* total, uint64_t * Gets progress in percentage from a status if available. * * @param status The dictionary status response to use. - * @param name Pointer to store the progress in percent (0-100) or -1 if not - * progress was found in the status. + * @param percent Pointer to an int to store the progress in percent (0-100) + * or -1 if no progress was found in the status. */ void instproxy_status_get_percent_complete(plist_t status, int *percent); @@ -487,7 +488,7 @@ void instproxy_client_options_free(plist_t client_options); * Queries the device for the path of an application. * * @param client The connected installation proxy client. - * @param appid ApplicationIdentifier of app to retrieve the path for. + * @param bundle_id ApplicationIdentifier of app to retrieve the path for. * @param path Pointer to store the device path for the application * which is set to NULL if it could not be determined. * diff --git a/include/libimobiledevice/libimobiledevice.h b/include/libimobiledevice/libimobiledevice.h index 40edd71..c3b87cd 100644 --- a/include/libimobiledevice/libimobiledevice.h +++ b/include/libimobiledevice/libimobiledevice.h @@ -47,10 +47,10 @@ typedef enum { IDEVICE_E_TIMEOUT = -7 } idevice_error_t; -typedef struct idevice_private idevice_private; +typedef struct idevice_private idevice_private; /**< \private */ typedef idevice_private *idevice_t; /**< The device handle. */ -typedef struct idevice_connection_private idevice_connection_private; +typedef struct idevice_connection_private idevice_connection_private; /**< \private */ typedef idevice_connection_private *idevice_connection_t; /**< The connection handle. */ /** Options for idevice_new_with_options() */ @@ -62,23 +62,24 @@ enum idevice_options { /** Type of connection a device is available on */ enum idevice_connection_type { - CONNECTION_USBMUXD = 1, - CONNECTION_NETWORK + CONNECTION_USBMUXD = 1, /**< device is available via USBMUX */ + CONNECTION_NETWORK /**< device is available via network */ }; +/** Device information returned by #idevice_get_device_list_extended API */ struct idevice_info { - char *udid; - enum idevice_connection_type conn_type; - void* conn_data; + char *udid; /**< UDID of the device */ + enum idevice_connection_type conn_type; /**< Type of connection the device is available on */ + void* conn_data; /**< Connection data, depending on the connection type */ }; typedef struct idevice_info* idevice_info_t; /* discovery (events/asynchronous) */ /** The event type for device add or removal */ enum idevice_event_type { - IDEVICE_DEVICE_ADD = 1, - IDEVICE_DEVICE_REMOVE, - IDEVICE_DEVICE_PAIRED + IDEVICE_DEVICE_ADD = 1, /**< device was added */ + IDEVICE_DEVICE_REMOVE, /**< device was removed */ + IDEVICE_DEVICE_PAIRED /**< device completed pairing process */ }; /* event data structure */ @@ -338,12 +339,22 @@ idevice_error_t idevice_connection_get_fd(idevice_connection_t connection, int * /* misc */ /** - * Gets the handle or (usbmux device id) of the device. + * Gets the handle or (USBMUX device id) of the device. + * + * @param device The device to get the USBMUX device id for. + * @param handle Pointer to a uint32_t that will be set to the USBMUX handle value. + * + * @return IDEVICE_E_SUCCESS on success, otherwise an error code. */ idevice_error_t idevice_get_handle(idevice_t device, uint32_t *handle); /** - * Gets the unique id for the device. + * Gets the Unique Device ID for the device. + * + * @param device The device to get the Unique Device ID for. + * @param udid Pointer that will be set to an allocated buffer with the device UDID. The consumer is responsible for releasing the allocated memory. + * + * @return IDEVICE_E_SUCCESS on success, otherwise an error code. */ idevice_error_t idevice_get_udid(idevice_t device, char **udid); diff --git a/include/libimobiledevice/lockdown.h b/include/libimobiledevice/lockdown.h index 1569f44..f22917a 100644 --- a/include/libimobiledevice/lockdown.h +++ b/include/libimobiledevice/lockdown.h @@ -80,7 +80,7 @@ typedef enum { LOCKDOWN_E_UNKNOWN_ERROR = -256 } lockdownd_error_t; -typedef struct lockdownd_client_private lockdownd_client_private; +typedef struct lockdownd_client_private lockdownd_client_private; /**< \private */ typedef lockdownd_client_private *lockdownd_client_t; /**< The client handle. */ struct lockdownd_pair_record { @@ -88,19 +88,20 @@ struct lockdownd_pair_record { char *host_certificate; /**< The host certificate */ char *root_certificate; /**< The root certificate */ char *host_id; /**< A unique HostID for the host computer */ - char *system_buid; /**< A unique system id */ + char *system_buid; /**< A unique system id */ }; -/** A pair record holding device, host and root certificates along the host_id */ -typedef struct lockdownd_pair_record *lockdownd_pair_record_t; +/** pair record holding device, host and root certificates along the host_id */ +typedef struct lockdownd_pair_record *lockdownd_pair_record_t; /**< pair record */ +/** service descriptor */ struct lockdownd_service_descriptor { - uint16_t port; - uint8_t ssl_enabled; - char* identifier; + uint16_t port; /**< port number the service was started on */ + uint8_t ssl_enabled; /**< an indicator if the service requires SSL */ + char* identifier; /**< identifier of the service */ }; typedef struct lockdownd_service_descriptor *lockdownd_service_descriptor_t; - +/** Callback types used in #lockdownd_cu_pairing_cb_t */ typedef enum { LOCKDOWN_CU_PAIRING_PIN_REQUESTED, /**< PIN requested: data_ptr is a char* buffer, and data_size points to the size of this buffer that must not be exceeded and has to be updated to the actual number of characters filled into the buffer. */ LOCKDOWN_CU_PAIRING_DEVICE_INFO, /**< device information available: data_ptr is a plist_t, and data_size is ignored. The plist_t has to be copied if required, since it is freed when the callback function returns. */ @@ -564,7 +565,7 @@ lockdownd_error_t lockdownd_service_descriptor_free(lockdownd_service_descriptor /** * Gets a readable error string for a given lockdown error code. * - * @params err A lockdownd error code + * @param err A lockdownd error code * * @returns A readable error string */ diff --git a/include/libimobiledevice/misagent.h b/include/libimobiledevice/misagent.h index 09af57a..394f5ce 100644 --- a/include/libimobiledevice/misagent.h +++ b/include/libimobiledevice/misagent.h @@ -31,6 +31,7 @@ extern "C" { #include <libimobiledevice/libimobiledevice.h> #include <libimobiledevice/lockdown.h> +/** Service identifier passed to lockdownd_start_service() to start the misagent service */ #define MISAGENT_SERVICE_NAME "com.apple.misagent" /** Error Codes */ @@ -43,7 +44,7 @@ typedef enum { MISAGENT_E_UNKNOWN_ERROR = -256 } misagent_error_t; -typedef struct misagent_client_private misagent_client_private; +typedef struct misagent_client_private misagent_client_private; /**< \private */ typedef misagent_client_private *misagent_client_t; /**< The client handle. */ /* Interface */ diff --git a/include/libimobiledevice/mobile_image_mounter.h b/include/libimobiledevice/mobile_image_mounter.h index e185ad5..891df40 100644 --- a/include/libimobiledevice/mobile_image_mounter.h +++ b/include/libimobiledevice/mobile_image_mounter.h @@ -31,6 +31,7 @@ extern "C" { #include <libimobiledevice/libimobiledevice.h> #include <libimobiledevice/lockdown.h> +/** Service identifier passed to lockdownd_start_service() to start the mobile image mounter service */ #define MOBILE_IMAGE_MOUNTER_SERVICE_NAME "com.apple.mobile.mobile_image_mounter" /** Error Codes */ @@ -44,7 +45,7 @@ typedef enum { MOBILE_IMAGE_MOUNTER_E_UNKNOWN_ERROR = -256 } mobile_image_mounter_error_t; -typedef struct mobile_image_mounter_client_private mobile_image_mounter_client_private; +typedef struct mobile_image_mounter_client_private mobile_image_mounter_client_private; /**< \private */ typedef mobile_image_mounter_client_private *mobile_image_mounter_client_t; /**< The client handle. */ /** callback for image upload */ diff --git a/include/libimobiledevice/mobileactivation.h b/include/libimobiledevice/mobileactivation.h index 51de205..774c116 100644 --- a/include/libimobiledevice/mobileactivation.h +++ b/include/libimobiledevice/mobileactivation.h @@ -30,6 +30,7 @@ extern "C" { #include <libimobiledevice/libimobiledevice.h> #include <libimobiledevice/lockdown.h> +/** Service identifier passed to lockdownd_start_service() to start the mobile activation service */ #define MOBILEACTIVATION_SERVICE_NAME "com.apple.mobileactivationd" /** Error Codes */ @@ -43,7 +44,7 @@ typedef enum { MOBILEACTIVATION_E_UNKNOWN_ERROR = -256 } mobileactivation_error_t; -typedef struct mobileactivation_client_private mobileactivation_client_private; +typedef struct mobileactivation_client_private mobileactivation_client_private; /**< \private */ typedef mobileactivation_client_private *mobileactivation_client_t; /**< The client handle. */ /** @@ -138,7 +139,7 @@ mobileactivation_error_t mobileactivation_create_activation_info(mobileactivatio * provided by mobileactivation_create_activation_session_info(). * * @param client The mobileactivation client - * @aram handshake_response The handshake response returned from drmHandshake + * @param handshake_response The handshake response returned from drmHandshake * @param info Pointer to a plist_t variable that will be set to the * activation info created by the mobileactivation service. The * consumer is responsible for freeing the returned object using diff --git a/include/libimobiledevice/mobilebackup.h b/include/libimobiledevice/mobilebackup.h index f22150d..d4c042e 100644 --- a/include/libimobiledevice/mobilebackup.h +++ b/include/libimobiledevice/mobilebackup.h @@ -31,6 +31,7 @@ extern "C" { #include <libimobiledevice/libimobiledevice.h> #include <libimobiledevice/lockdown.h> +/** Service identifier passed to lockdownd_start_service() to start the mobilebackup service */ #define MOBILEBACKUP_SERVICE_NAME "com.apple.mobilebackup" /** Error Codes */ @@ -46,9 +47,10 @@ typedef enum { MOBILEBACKUP_E_UNKNOWN_ERROR = -256 } mobilebackup_error_t; -typedef struct mobilebackup_client_private mobilebackup_client_private; +typedef struct mobilebackup_client_private mobilebackup_client_private; /**< \private */ typedef mobilebackup_client_private *mobilebackup_client_t; /**< The client handle. */ +/** Available flags passed to #mobilebackup_request_restore */ typedef enum { MB_RESTORE_NOTIFY_SPRINGBOARD = 1 << 0, MB_RESTORE_PRESERVE_SETTINGS = 1 << 1, diff --git a/include/libimobiledevice/mobilebackup2.h b/include/libimobiledevice/mobilebackup2.h index 239c807..1af4141 100644 --- a/include/libimobiledevice/mobilebackup2.h +++ b/include/libimobiledevice/mobilebackup2.h @@ -31,6 +31,7 @@ extern "C" { #include <libimobiledevice/libimobiledevice.h> #include <libimobiledevice/lockdown.h> +/** Service identifier passed to lockdownd_start_service() to start the mobilebackup2 service */ #define MOBILEBACKUP2_SERVICE_NAME "com.apple.mobilebackup2" /** Error Codes */ @@ -47,7 +48,7 @@ typedef enum { MOBILEBACKUP2_E_UNKNOWN_ERROR = -256 } mobilebackup2_error_t; -typedef struct mobilebackup2_client_private mobilebackup2_client_private; +typedef struct mobilebackup2_client_private mobilebackup2_client_private; /**< \private */ typedef mobilebackup2_client_private *mobilebackup2_client_t; /**< The client handle. */ @@ -156,7 +157,7 @@ mobilebackup2_error_t mobilebackup2_send_raw(mobilebackup2_client_t client, cons * @param data Pointer to a buffer that will be filled with the received data. * @param length Number of bytes to receive. The data buffer needs to be large * enough to store this amount of data. - * @paran bytes Number of bytes actually received. + * @param bytes Number of bytes actually received. * * @return MOBILEBACKUP2_E_SUCCESS if any or no data was received, * MOBILEBACKUP2_E_INVALID_ARG if one of the parameters is invalid, diff --git a/include/libimobiledevice/mobilesync.h b/include/libimobiledevice/mobilesync.h index 005ef3f..6b1af18 100644 --- a/include/libimobiledevice/mobilesync.h +++ b/include/libimobiledevice/mobilesync.h @@ -34,6 +34,7 @@ extern "C" { #include <libimobiledevice/libimobiledevice.h> #include <libimobiledevice/lockdown.h> +/** Service identifier passed to lockdownd_start_service() to start the mobilesync service */ #define MOBILESYNC_SERVICE_NAME "com.apple.mobilesync" /** Error Codes */ @@ -59,14 +60,16 @@ typedef enum { MOBILESYNC_SYNC_TYPE_RESET /**< Reset-sync signals that the computer should send all data again. */ } mobilesync_sync_type_t; -typedef struct mobilesync_client_private mobilesync_client_private; +typedef struct mobilesync_client_private mobilesync_client_private; /**< \private */ typedef mobilesync_client_private *mobilesync_client_t; /**< The client handle */ +/** Anchors used by the device and computer (structure) */ typedef struct { - char *device_anchor; - char *computer_anchor; + char *device_anchor; /**< device anchor */ + char *computer_anchor; /**< computer anchor */ } mobilesync_anchors; -typedef mobilesync_anchors *mobilesync_anchors_t; /**< Anchors used by the device and computer. */ +/** Anchors used by the device and computer */ +typedef mobilesync_anchors *mobilesync_anchors_t; /* Interface */ diff --git a/include/libimobiledevice/notification_proxy.h b/include/libimobiledevice/notification_proxy.h index a9d2d3f..872692c 100644 --- a/include/libimobiledevice/notification_proxy.h +++ b/include/libimobiledevice/notification_proxy.h @@ -31,6 +31,7 @@ extern "C" { #include <libimobiledevice/libimobiledevice.h> #include <libimobiledevice/lockdown.h> +/** Service identifier passed to lockdownd_start_service() to start the notification proxy service */ #define NP_SERVICE_NAME "com.apple.mobile.notification_proxy" /** Error Codes */ @@ -43,22 +44,26 @@ typedef enum { } np_error_t; /** - * @name Notifications that can be send + * @name Notifications that can be sent * * For use with np_post_notification() (client --> device) */ +/**@{*/ +//! @cond #define NP_SYNC_WILL_START "com.apple.itunes-mobdev.syncWillStart" #define NP_SYNC_DID_START "com.apple.itunes-mobdev.syncDidStart" #define NP_SYNC_DID_FINISH "com.apple.itunes-mobdev.syncDidFinish" #define NP_SYNC_LOCK_REQUEST "com.apple.itunes-mobdev.syncLockRequest" -/*@}*/ +//! @endcond +/**@}*/ /** * @name Notifications that can be received * * For use with np_observe_notification() (device --> client) */ -/*@{*/ +/**@{*/ +//! @cond #define NP_SYNC_CANCEL_REQUEST "com.apple.itunes-client.syncCancelRequest" #define NP_SYNC_SUSPEND_REQUEST "com.apple.itunes-client.syncSuspendRequest" #define NP_SYNC_RESUME_REQUEST "com.apple.itunes-client.syncResumeRequest" @@ -81,12 +86,13 @@ typedef enum { #define NP_ITDBPREP_DID_END "com.apple.itdbprep.notification.didEnd" #define NP_LANGUAGE_CHANGED "com.apple.language.changed" #define NP_ADDRESS_BOOK_PREF_CHANGED "com.apple.AddressBook.PreferenceChanged" -/*@}*/ +//! @endcond +/**@}*/ -typedef struct np_client_private np_client_private; +typedef struct np_client_private np_client_private; /**< \private */ typedef np_client_private *np_client_t; /**< The client handle. */ -/** Reports which notification was received. */ +/** Callback function that reports which notification was received. */ typedef void (*np_notify_cb_t) (const char *notification, void *user_data); /* Interface */ @@ -177,7 +183,7 @@ np_error_t np_observe_notifications(np_client_t client, const char **notificatio * @param client the NP client * @param notify_cb pointer to a callback function or NULL to de-register a * previously set callback function. - * @param user_data Pointer that will be passed to the callback function as + * @param userdata Pointer that will be passed to the callback function as * user data. If notify_cb is NULL, this parameter is ignored. * * @note Only one callback function can be registered at the same time; diff --git a/include/libimobiledevice/preboard.h b/include/libimobiledevice/preboard.h index 60b8e26..88e9806 100644 --- a/include/libimobiledevice/preboard.h +++ b/include/libimobiledevice/preboard.h @@ -30,6 +30,7 @@ extern "C" { #include <libimobiledevice/libimobiledevice.h> #include <libimobiledevice/lockdown.h> +/** Service identifier passed to lockdownd_start_service() to start the preboard service */ #define PREBOARD_SERVICE_NAME "com.apple.preboardservice_v2" /** Error Codes */ @@ -45,7 +46,7 @@ typedef enum { PREBOARD_E_UNKNOWN_ERROR = -256 } preboard_error_t; -typedef struct preboard_client_private preboard_client_private; +typedef struct preboard_client_private preboard_client_private; /**< \private */ typedef preboard_client_private *preboard_client_t; /**< The client handle. */ /** Reports the status response of the given command */ @@ -121,6 +122,7 @@ preboard_error_t preboard_receive(preboard_client_t client, plist_t * plist); * * @param client The preboard client * @param plist Pointer to a plist_t what will be set to the received plist + * @param timeout_ms Timeout in milliseconds * * @return PREBOARD_E_SUCCESS on success, * PREBOARD_E_INVALID_ARG when client or plist is NULL, @@ -148,7 +150,7 @@ preboard_error_t preboard_receive_with_timeout(preboard_client_t client, plist_t * { Timeout: true } * followed by { HideDialog: true } * If the user aborts the passcode entry, the device sends a dictionary: - * { Error: 1, ErrorString: <error string> } + * { Error: 1, ErrorString: \<error string\> } * followed by { HideDialog: true } * * @return PREBOARD_E_SUCCESS if the command was successfully submitted, @@ -170,7 +172,7 @@ preboard_error_t preboard_create_stashbag(preboard_client_t client, plist_t mani * receive a dictionary with: * { StashbagCommitComplete: true } * or in case of an error: - * { StashbagCommitComplete: 0, Error: 1, <optional> ErrorString: <error string> } + * { StashbagCommitComplete: 0, Error: 1, \<optional\> ErrorString: \<error string\> } * * @return PREBOARD_E_SUCCESS if the command was successfully submitted, * PREBOARD_E_INVALID_ARG when client is invalid, diff --git a/include/libimobiledevice/property_list_service.h b/include/libimobiledevice/property_list_service.h index 031d6f8..5205551 100644 --- a/include/libimobiledevice/property_list_service.h +++ b/include/libimobiledevice/property_list_service.h @@ -30,7 +30,7 @@ extern "C" { #include <libimobiledevice/lockdown.h> -/* Error Codes */ +/** Error Codes */ typedef enum { PROPERTY_LIST_SERVICE_E_SUCCESS = 0, PROPERTY_LIST_SERVICE_E_INVALID_ARG = -1, @@ -42,7 +42,7 @@ typedef enum { PROPERTY_LIST_SERVICE_E_UNKNOWN_ERROR = -256 } property_list_service_error_t; -typedef struct property_list_service_client_private property_list_service_private; +typedef struct property_list_service_client_private property_list_service_private; /**< \private */ typedef property_list_service_private* property_list_service_client_t; /**< The client handle. */ /* Interface */ diff --git a/include/libimobiledevice/restore.h b/include/libimobiledevice/restore.h index 950f8fd..0017cfd 100644 --- a/include/libimobiledevice/restore.h +++ b/include/libimobiledevice/restore.h @@ -42,7 +42,7 @@ typedef enum { RESTORE_E_UNKNOWN_ERROR = -256 } restored_error_t; -typedef struct restored_client_private restored_client_private; +typedef struct restored_client_private restored_client_private; /**< \private */ typedef restored_client_private *restored_client_t; /**< The client handle. */ /* Interface */ diff --git a/include/libimobiledevice/reverse_proxy.h b/include/libimobiledevice/reverse_proxy.h index 2539bd9..b7a93ff 100644 --- a/include/libimobiledevice/reverse_proxy.h +++ b/include/libimobiledevice/reverse_proxy.h @@ -2,6 +2,7 @@ * @file libimobiledevice/reverse_proxy.h * @brief Provide a reverse proxy to allow the device to communicate through, * which is used during firmware restore. + * \internal * * Copyright (c) 2021 Nikias Bassen, All Rights Reserved. * @@ -29,7 +30,7 @@ extern "C" { #include <libimobiledevice/libimobiledevice.h> -#define REVERSE_PROXY_DEFAULT_PORT 1082 +#define REVERSE_PROXY_DEFAULT_PORT 1082 /**< default port the reverse proxy is listening on */ /** Error Codes */ typedef enum { @@ -43,14 +44,16 @@ typedef enum { REVERSE_PROXY_E_UNKNOWN_ERROR = -256 } reverse_proxy_error_t; -typedef struct reverse_proxy_client_private reverse_proxy_client_private; +typedef struct reverse_proxy_client_private reverse_proxy_client_private; /**< \private */ typedef reverse_proxy_client_private *reverse_proxy_client_t; /**< The client handle. */ +/** reverse proxy client type */ typedef enum { RP_TYPE_CTRL = 1, /**< control connection */ RP_TYPE_CONN /**< proxy connection */ } reverse_proxy_client_type_t; +/** reverse proxy status for reverse_proxy_status_cb_t callback */ typedef enum { RP_STATUS_READY = 1, /**< proxy is ready */ RP_STATUS_TERMINATE, /**< proxy terminated */ @@ -60,6 +63,7 @@ typedef enum { RP_STATUS_DISCONNECTED, /**< connection closed (only RP_TYPE_CONN) */ } reverse_proxy_status_t; +/** reverse proxy data direction passed to reverse_proxy_data_cb_t callback */ typedef enum { RP_DATA_DIRECTION_OUT = 1, /**< data going out to remote host */ RP_DATA_DIRECTION_IN /**< data coming in from remote host */ diff --git a/include/libimobiledevice/sbservices.h b/include/libimobiledevice/sbservices.h index 0259d97..509d5b9 100644 --- a/include/libimobiledevice/sbservices.h +++ b/include/libimobiledevice/sbservices.h @@ -31,6 +31,7 @@ extern "C" { #include <libimobiledevice/libimobiledevice.h> #include <libimobiledevice/lockdown.h> +/** Service identifier passed to lockdownd_start_service() to start the springboardservices service */ #define SBSERVICES_SERVICE_NAME "com.apple.springboardservices" /** Error Codes */ @@ -42,8 +43,7 @@ typedef enum { SBSERVICES_E_UNKNOWN_ERROR = -256 } sbservices_error_t; -/** @name Orientation of the user interface on the device */ -/*@{*/ +/** Orientation of the user interface on the device */ typedef enum { SBSERVICES_INTERFACE_ORIENTATION_UNKNOWN = 0, SBSERVICES_INTERFACE_ORIENTATION_PORTRAIT = 1, @@ -51,9 +51,8 @@ typedef enum { SBSERVICES_INTERFACE_ORIENTATION_LANDSCAPE_RIGHT = 3, SBSERVICES_INTERFACE_ORIENTATION_LANDSCAPE_LEFT = 4 } sbservices_interface_orientation_t; -/*@}*/ -typedef struct sbservices_client_private sbservices_client_private; +typedef struct sbservices_client_private sbservices_client_private; /**< \private */ typedef sbservices_client_private *sbservices_client_t; /**< The client handle. */ /* Interface */ diff --git a/include/libimobiledevice/screenshotr.h b/include/libimobiledevice/screenshotr.h index 83ca96b..ecbbdbe 100644 --- a/include/libimobiledevice/screenshotr.h +++ b/include/libimobiledevice/screenshotr.h @@ -32,6 +32,7 @@ extern "C" { #include <libimobiledevice/libimobiledevice.h> #include <libimobiledevice/lockdown.h> +/** Service identifier passed to lockdownd_start_service() to start the screenshotr service */ #define SCREENSHOTR_SERVICE_NAME "com.apple.mobile.screenshotr" /** Error Codes */ @@ -46,7 +47,7 @@ typedef enum { SCREENSHOTR_E_UNKNOWN_ERROR = -256 } screenshotr_error_t; -typedef struct screenshotr_client_private screenshotr_client_private; +typedef struct screenshotr_client_private screenshotr_client_private; /**< \private */ typedef screenshotr_client_private *screenshotr_client_t; /**< The client handle. */ diff --git a/include/libimobiledevice/service.h b/include/libimobiledevice/service.h index 13d0e15..6842054 100644 --- a/include/libimobiledevice/service.h +++ b/include/libimobiledevice/service.h @@ -42,9 +42,10 @@ typedef enum { SERVICE_E_UNKNOWN_ERROR = -256 } service_error_t; -typedef struct service_client_private service_client_private; +typedef struct service_client_private service_client_private; /**< \private */ typedef service_client_private* service_client_t; /**< The client handle. */ +/** service constructor cast */ #define SERVICE_CONSTRUCTOR(x) (int32_t (*)(idevice_t, lockdownd_service_descriptor_t, void**))(x) /* Interface */ @@ -74,6 +75,8 @@ service_error_t service_client_new(idevice_t device, lockdownd_service_descripto * use. * @param label The label to use for communication. Usually the program name. * Pass NULL to disable sending the label in requests to lockdownd. + * @param constructor_func Constructor function for the service client to create (e.g. afc_client_new()) + * @param error_code Pointer to an int32_t that will receive the service start error code. * * @return SERVICE_E_SUCCESS on success, or a SERVICE_E_* error code * otherwise. @@ -160,7 +163,7 @@ service_error_t service_enable_ssl(service_client_t client); /** * Disable SSL for the given service client. * - * @param client The connected service client for that SSL should be disabled. + * @param client The connected service client for which SSL should be disabled. * * @return SERVICE_E_SUCCESS on success, * SERVICE_E_INVALID_ARG if client or client->connection is @@ -169,9 +172,11 @@ service_error_t service_enable_ssl(service_client_t client); service_error_t service_disable_ssl(service_client_t client); /** - * Disable SSL for the given service client without sending SSL terminate messages. + * Disable SSL for the given service client, optionally without sending SSL terminate messages. * - * @param client The connected service client for that SSL should be disabled. + * @param client The connected service client for which SSL should be disabled. + * @param sslBypass A boolean value indicating wether to disable SSL with a proper + * SSL shutdown (0), or bypass the shutdown (1). * * @return SERVICE_E_SUCCESS on success, * SERVICE_E_INVALID_ARG if client or client->connection is diff --git a/include/libimobiledevice/syslog_relay.h b/include/libimobiledevice/syslog_relay.h index 89d9489..aae5d11 100644 --- a/include/libimobiledevice/syslog_relay.h +++ b/include/libimobiledevice/syslog_relay.h @@ -31,6 +31,7 @@ extern "C" { #include <libimobiledevice/libimobiledevice.h> #include <libimobiledevice/lockdown.h> +/** Service identifier passed to lockdownd_start_service() to start the syslog relay service */ #define SYSLOG_RELAY_SERVICE_NAME "com.apple.syslog_relay" /** Error Codes */ @@ -44,7 +45,7 @@ typedef enum { SYSLOG_RELAY_E_UNKNOWN_ERROR = -256 } syslog_relay_error_t; -typedef struct syslog_relay_client_private syslog_relay_client_private; +typedef struct syslog_relay_client_private syslog_relay_client_private; /**< \private */ typedef syslog_relay_client_private *syslog_relay_client_t; /**< The client handle. */ /** Receives each character received from the device. */ @@ -170,7 +171,6 @@ syslog_relay_error_t syslog_relay_receive_with_timeout(syslog_relay_client_t cli * @param data Buffer that will be filled with the data received * @param size Number of bytes to receive * @param received Number of bytes received (can be NULL to ignore) - * @param timeout Maximum time in milliseconds to wait for data. * * @return SYSLOG_RELAY_E_SUCCESS on success, * SYSLOG_RELAY_E_INVALID_ARG when client or plist is NULL diff --git a/include/libimobiledevice/webinspector.h b/include/libimobiledevice/webinspector.h index da0759c..064ba91 100644 --- a/include/libimobiledevice/webinspector.h +++ b/include/libimobiledevice/webinspector.h @@ -31,6 +31,7 @@ extern "C" { #include <libimobiledevice/libimobiledevice.h> #include <libimobiledevice/lockdown.h> +/** Service identifier passed to lockdownd_start_service() to start the webinspector service */ #define WEBINSPECTOR_SERVICE_NAME "com.apple.webinspector" /** Error Codes */ @@ -45,7 +46,7 @@ typedef enum { WEBINSPECTOR_E_UNKNOWN_ERROR = -256 } webinspector_error_t; -typedef struct webinspector_client_private webinspector_client_private; +typedef struct webinspector_client_private webinspector_client_private; /**< \private */ typedef webinspector_client_private *webinspector_client_t; /**< The client handle. */ @@ -118,7 +119,7 @@ webinspector_error_t webinspector_receive(webinspector_client_t client, plist_t * @param client The webinspector client to use for receiving * @param plist pointer to a plist_t that will point to the received plist * upon successful return - * @param timeout Maximum time in milliseconds to wait for data. + * @param timeout_ms Maximum time in milliseconds to wait for data. * * @return WEBINSPECTOR_E_SUCCESS on success, * WEBINSPECTOR_E_INVALID_ARG when client or *plist is NULL, |