Documentation fixes
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 @@
#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 @@
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 @@
#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 @@
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 @@
* 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 @@
* @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 @@
#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 @@
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 @@
#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 @@
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_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_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 @@
#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 @@
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 @@
* 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 @@
* 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 @@
#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 @@
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 @@
* @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 @@
#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 @@
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 @@
#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 @@
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 @@
* 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 @@
* 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 @@
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 @@
/** 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 @@
/* 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 @@
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 @@
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 @@
/**
* 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 @@
#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 @@
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 @@
#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 @@
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 @@
#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 @@
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 @@
* 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 @@
#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 @@
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 @@
#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 @@
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 @@
* @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 @@
#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 @@
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 @@
#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 @@
} 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 @@
#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 @@
* @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 @@
#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 @@
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 @@
*
* @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 @@
* { 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 @@
* 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 @@
#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 @@
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 @@
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 @@
#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 @@
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 @@
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 @@
#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 @@
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 @@
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 @@
#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 @@
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 @@
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 @@
* 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 @@
/**
* 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_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 @@
#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 @@
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 @@
* @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 @@
#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 @@
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 @@
* @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,
