summaryrefslogtreecommitdiffstats
path: root/include
diff options
context:
space:
mode:
Diffstat (limited to 'include')
-rw-r--r--include/libimobiledevice/afc.h233
-rw-r--r--include/libimobiledevice/diagnostics_relay.h111
-rw-r--r--include/libimobiledevice/file_relay.h102
-rw-r--r--include/libimobiledevice/heartbeat.h72
-rw-r--r--include/libimobiledevice/house_arrest.h114
-rw-r--r--include/libimobiledevice/installation_proxy.h247
-rw-r--r--include/libimobiledevice/libimobiledevice.h147
-rw-r--r--include/libimobiledevice/lockdown.h302
-rw-r--r--include/libimobiledevice/misagent.h82
-rw-r--r--include/libimobiledevice/mobile_image_mounter.h100
-rw-r--r--include/libimobiledevice/mobilebackup.h169
-rw-r--r--include/libimobiledevice/mobilebackup2.h144
-rw-r--r--include/libimobiledevice/mobilesync.h249
-rw-r--r--include/libimobiledevice/notification_proxy.h90
-rw-r--r--include/libimobiledevice/restore.h110
-rw-r--r--include/libimobiledevice/sbservices.h102
-rw-r--r--include/libimobiledevice/screenshotr.h55
-rw-r--r--include/libimobiledevice/service.h105
-rw-r--r--include/libimobiledevice/syslog_relay.h94
-rw-r--r--include/libimobiledevice/webinspector.h73
20 files changed, 2701 insertions, 0 deletions
diff --git a/include/libimobiledevice/afc.h b/include/libimobiledevice/afc.h
index 289c749..2f272e0 100644
--- a/include/libimobiledevice/afc.h
+++ b/include/libimobiledevice/afc.h
@@ -95,30 +95,263 @@ typedef struct afc_client_private afc_client_private;
typedef afc_client_private *afc_client_t; /**< The client handle. */
/* Interface */
+
+/**
+ * Makes a connection to the AFC service on the device.
+ *
+ * @param device The device to connect to.
+ * @param service The service descriptor returned by lockdownd_start_service.
+ * @param client Pointer that will be set to a newly allocated afc_client_t
+ * upon successful return.
+ *
+ * @return AFC_E_SUCCESS on success, AFC_E_INVALID_ARG if device or service is
+ * invalid, AFC_E_MUX_ERROR if the connection cannot be established,
+ * or AFC_E_NO_MEM if there is a memory allocation problem.
+ */
afc_error_t afc_client_new(idevice_t device, lockdownd_service_descriptor_t service, afc_client_t *client);
+
+/**
+ * Starts a new AFC 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
+ * afc_client_t upon successful return. Must be freed using
+ * afc_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 AFC_E_SUCCESS on success, or an AFC_E_* error
+ * code otherwise.
+ */
afc_error_t afc_client_start_service(idevice_t device, afc_client_t* client, const char* label);
+
+/**
+ * Frees up an AFC client. If the connection was created by the
+ * client itself, the connection will be closed.
+ *
+ * @param client The client to free.
+ */
afc_error_t afc_client_free(afc_client_t client);
+/**
+ * Get device information for a connected client. The device information
+ * returned is the device model as well as the free space, the total capacity
+ * and blocksize on the accessed disk partition.
+ *
+ * @param client The client to get device info for.
+ * @param infos A char ** list of parameters as given by AFC or NULL if there
+ * was an error.
+ *
+ * @return AFC_E_SUCCESS on success or an AFC_E_* error value.
+ */
afc_error_t afc_get_device_info(afc_client_t client, char ***infos);
+
+/**
+ * Gets a directory listing of the directory requested.
+ *
+ * @param client The client to get a directory listing from.
+ * @param dir The directory to list. (must be a fully-qualified path)
+ * @param list A char list of files in that directory, terminated by an empty
+ * string or NULL if there was an error.
+ *
+ * @return AFC_E_SUCCESS on success or an AFC_E_* error value.
+ */
afc_error_t afc_read_directory(afc_client_t client, const char *dir, char ***list);
+
+/**
+ * Gets information about a specific file.
+ *
+ * @param client The client to use to get the information of the file.
+ * @param path The fully-qualified path to the file.
+ * @param infolist Pointer to a buffer that will be filled with a NULL-terminated
+ * list of strings with the file information.
+ * Set to NULL before calling this function.
+ *
+ * @return AFC_E_SUCCESS on success or an AFC_E_* error value.
+ */
afc_error_t afc_get_file_info(afc_client_t client, const char *filename, char ***infolist);
+
+/**
+ * Opens a file on the device.
+ *
+ * @param client The client to use to open the file.
+ * @param filename The file to open. (must be a fully-qualified path)
+ * @param file_mode The mode to use to open the file. Can be AFC_FILE_READ or
+ * AFC_FILE_WRITE; the former lets you read and write,
+ * however, and the second one will *create* the file,
+ * destroying anything previously there.
+ * @param handle Pointer to a uint64_t that will hold the handle of the file
+ *
+ * @return AFC_E_SUCCESS on success or an AFC_E_* error value.
+ */
afc_error_t afc_file_open(afc_client_t client, const char *filename, afc_file_mode_t file_mode, uint64_t *handle);
+
+/**
+ * Closes a file on the device.
+ *
+ * @param client The client to close the file with.
+ * @param handle File handle of a previously opened file.
+ */
afc_error_t afc_file_close(afc_client_t client, uint64_t handle);
+
+/**
+ * Locks or unlocks a file on the device.
+ *
+ * makes use of flock on the device, see
+ * http://developer.apple.com/documentation/Darwin/Reference/ManPages/man2/flock.2.html
+ *
+ * @param client The client to lock the file with.
+ * @param handle File handle of a previously opened file.
+ * @param operation the lock or unlock operation to perform, this is one of
+ * AFC_LOCK_SH (shared lock), AFC_LOCK_EX (exclusive lock),
+ * or AFC_LOCK_UN (unlock).
+ */
afc_error_t afc_file_lock(afc_client_t client, uint64_t handle, afc_lock_op_t operation);
+
+/**
+ * Attempts to the read the given number of bytes from the given file.
+ *
+ * @param client The relevant AFC client
+ * @param handle File handle of a previously opened file
+ * @param data The pointer to the memory region to store the read data
+ * @param length The number of bytes to read
+ * @param bytes_read The number of bytes actually read.
+ *
+ * @return AFC_E_SUCCESS on success or an AFC_E_* error value.
+ */
afc_error_t afc_file_read(afc_client_t client, uint64_t handle, char *data, uint32_t length, uint32_t *bytes_read);
+
+/**
+ * Writes a given number of bytes to a file.
+ *
+ * @param client The client to use to write to the file.
+ * @param handle File handle of previously opened file.
+ * @param data The data to write to the file.
+ * @param length How much data to write.
+ * @param bytes_written The number of bytes actually written to the file.
+ *
+ * @return AFC_E_SUCCESS on success or an AFC_E_* error value.
+ */
afc_error_t afc_file_write(afc_client_t client, uint64_t handle, const char *data, uint32_t length, uint32_t *bytes_written);
+
+/**
+ * Seeks to a given position of a pre-opened file on the device.
+ *
+ * @param client The client to use to seek to the position.
+ * @param handle File handle of a previously opened.
+ * @param offset Seek offset.
+ * @param whence Seeking direction, one of SEEK_SET, SEEK_CUR, or SEEK_END.
+ *
+ * @return AFC_E_SUCCESS on success or an AFC_E_* error value.
+ */
afc_error_t afc_file_seek(afc_client_t client, uint64_t handle, int64_t offset, int whence);
+
+/**
+ * Returns current position in a pre-opened file on the device.
+ *
+ * @param client The client to use.
+ * @param handle File handle of a previously opened file.
+ * @param position Position in bytes of indicator
+ *
+ * @return AFC_E_SUCCESS on success or an AFC_E_* error value.
+ */
afc_error_t afc_file_tell(afc_client_t client, uint64_t handle, uint64_t *position);
+
+/**
+ * Sets the size of a file on the device.
+ *
+ * @param client The client to use to set the file size.
+ * @param handle File handle of a previously opened file.
+ * @param newsize The size to set the file to.
+ *
+ * @return AFC_E_SUCCESS on success or an AFC_E_* error value.
+ *
+ * @note This function is more akin to ftruncate than truncate, and truncate
+ * calls would have to open the file before calling this, sadly.
+ */
afc_error_t afc_file_truncate(afc_client_t client, uint64_t handle, uint64_t newsize);
+
+/**
+ * Deletes a file or directory.
+ *
+ * @param client The client to use.
+ * @param path The path to delete. (must be a fully-qualified path)
+ *
+ * @return AFC_E_SUCCESS on success or an AFC_E_* error value.
+ */
afc_error_t afc_remove_path(afc_client_t client, const char *path);
+
+/**
+ * Renames a file or directory on the device.
+ *
+ * @param client The client to have rename.
+ * @param from The name to rename from. (must be a fully-qualified path)
+ * @param to The new name. (must also be a fully-qualified path)
+ *
+ * @return AFC_E_SUCCESS on success or an AFC_E_* error value.
+ */
afc_error_t afc_rename_path(afc_client_t client, const char *from, const char *to);
+
+/**
+ * Creates a directory on the device.
+ *
+ * @param client The client to use to make a directory.
+ * @param dir The directory's path. (must be a fully-qualified path, I assume
+ * all other mkdir restrictions apply as well)
+ *
+ * @return AFC_E_SUCCESS on success or an AFC_E_* error value.
+ */
afc_error_t afc_make_directory(afc_client_t client, const char *dir);
+
+/**
+ * Sets the size of a file on the device without prior opening it.
+ *
+ * @param client The client to use to set the file size.
+ * @param path The path of the file to be truncated.
+ * @param newsize The size to set the file to.
+ *
+ * @return AFC_E_SUCCESS on success or an AFC_E_* error value.
+ */
afc_error_t afc_truncate(afc_client_t client, const char *path, uint64_t newsize);
+
+/**
+ * Creates a hard link or symbolic link on the device.
+ *
+ * @param client The client to use for making a link
+ * @param linktype 1 = hard link, 2 = symlink
+ * @param target The file to be linked.
+ * @param linkname The name of link.
+ *
+ * @return AFC_E_SUCCESS on success or an AFC_E_* error value.
+ */
afc_error_t afc_make_link(afc_client_t client, afc_link_type_t linktype, const char *target, const char *linkname);
+
+/**
+ * Sets the modification time of a file on the device.
+ *
+ * @param client The client to use to set the file size.
+ * @param path Path of the file for which the modification time should be set.
+ * @param mtime The modification time to set in nanoseconds since epoch.
+ *
+ * @return AFC_E_SUCCESS on success or an AFC_E_* error value.
+ */
afc_error_t afc_set_file_time(afc_client_t client, const char *path, uint64_t mtime);
/* Helper functions */
+
+/**
+ * Get a specific key of the device info list for a client connection.
+ * Known key values are: Model, FSTotalBytes, FSFreeBytes and FSBlockSize.
+ * This is a helper function for afc_get_device_info().
+ *
+ * @param client The client to get device info for.
+ * @param key The key to get the value of.
+ * @param value The value for the key if successful or NULL otherwise.
+ *
+ * @return AFC_E_SUCCESS on success or an AFC_E_* error value.
+ */
afc_error_t afc_get_device_info_key(afc_client_t client, const char *key, char **value);
+
afc_error_t afc_dictionary_free(char **dictionary);
#ifdef __cplusplus
diff --git a/include/libimobiledevice/diagnostics_relay.h b/include/libimobiledevice/diagnostics_relay.h
index 17e73dd..b25750b 100644
--- a/include/libimobiledevice/diagnostics_relay.h
+++ b/include/libimobiledevice/diagnostics_relay.h
@@ -58,17 +58,128 @@ typedef int16_t diagnostics_relay_error_t;
typedef struct diagnostics_relay_client_private diagnostics_relay_client_private;
typedef diagnostics_relay_client_private *diagnostics_relay_client_t; /**< The client handle. */
+/**
+ * Connects to the diagnostics_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 Reference that will point to a newly allocated
+ * diagnostics_relay_client_t upon successful return.
+ *
+ * @return DIAGNOSTICS_RELAY_E_SUCCESS on success,
+ * DIAGNOSTICS_RELAY_E_INVALID_ARG when one of the parameters is invalid,
+ * or DIAGNOSTICS_RELAY_E_MUX_ERROR when the connection failed.
+ */
diagnostics_relay_error_t diagnostics_relay_client_new(idevice_t device, lockdownd_service_descriptor_t service, diagnostics_relay_client_t *client);
+
+/**
+ * Starts a new diagnostics_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
+ * diagnostics_relay_client_t upon successful return. Must be freed using
+ * diagnostics_relay_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 DIAGNOSTICS_RELAY_E_SUCCESS on success, or an DIAGNOSTICS_RELAY_E_* error
+ * code otherwise.
+ */
diagnostics_relay_error_t diagnostics_relay_client_start_service(idevice_t device, diagnostics_relay_client_t* client, const char* label);
+
+/**
+ * Disconnects a diagnostics_relay client from the device and frees up the
+ * diagnostics_relay client data.
+ *
+ * @param client The diagnostics_relay client to disconnect and free.
+ *
+ * @return DIAGNOSTICS_RELAY_E_SUCCESS on success,
+ * DIAGNOSTICS_RELAY_E_INVALID_ARG when one of client or client->parent
+ * is invalid, or DIAGNOSTICS_RELAY_E_UNKNOWN_ERROR when the was an
+ * error freeing the parent property_list_service client.
+ */
diagnostics_relay_error_t diagnostics_relay_client_free(diagnostics_relay_client_t client);
+
+/**
+ * Sends the Goodbye request signaling the end of communication.
+ *
+ * @param client The diagnostics_relay client
+ *
+ * @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_goodbye(diagnostics_relay_client_t client);
+
+/**
+ * Puts the device into deep sleep mode and disconnects from host.
+ *
+ * @param client The diagnostics_relay client
+ *
+ * @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_sleep(diagnostics_relay_client_t client);
+
+/**
+ * Restart the device and optionally show a user notification.
+ *
+ * @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
+ *
+ * @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_restart(diagnostics_relay_client_t client, int flags);
+
+/**
+ * Shutdown of the device and optionally show a user notification.
+ *
+ * @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
+ *
+ * @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_shutdown(diagnostics_relay_client_t client, int flags);
+
+/**
+ * Shutdown of the device and optionally show a user notification.
+ *
+ * @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
+ *
+ * @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_request_diagnostics(diagnostics_relay_client_t client, const char* type, plist_t* diagnostics);
+
diagnostics_relay_error_t diagnostics_relay_query_mobilegestalt(diagnostics_relay_client_t client, plist_t keys, plist_t* result);
+
diagnostics_relay_error_t diagnostics_relay_query_ioregistry_entry(diagnostics_relay_client_t client, const char* name, const char* class, plist_t* result);
+
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 d197f2e..f9318bd 100644
--- a/include/libimobiledevice/file_relay.h
+++ b/include/libimobiledevice/file_relay.h
@@ -50,11 +50,113 @@ typedef int16_t file_relay_error_t;
typedef struct file_relay_client_private file_relay_client_private;
typedef file_relay_client_private *file_relay_client_t; /**< The client handle. */
+/**
+ * Connects to the file_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 Reference that will point to a newly allocated
+ * file_relay_client_t upon successful return.
+ *
+ * @return FILE_RELAY_E_SUCCESS on success,
+ * FILE_RELAY_E_INVALID_ARG when one of the parameters is invalid,
+ * or FILE_RELAY_E_MUX_ERROR when the connection failed.
+ */
file_relay_error_t file_relay_client_new(idevice_t device, lockdownd_service_descriptor_t service, file_relay_client_t *client);
+
+/**
+ * Starts a new file_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
+ * file_relay_client_t upon successful return. Must be freed using
+ * file_relay_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 FILE_RELAY_E_SUCCESS on success, or an FILE_RELAY_E_* error
+ * code otherwise.
+ */
file_relay_error_t file_relay_client_start_service(idevice_t device, file_relay_client_t* client, const char* label);
+
+/**
+ * Disconnects a file_relay client from the device and frees up the file_relay
+ * client data.
+ *
+ * @param client The file_relay client to disconnect and free.
+ *
+ * @return FILE_RELAY_E_SUCCESS on success,
+ * FILE_RELAY_E_INVALID_ARG when one of client or client->parent
+ * is invalid, or FILE_RELAY_E_UNKNOWN_ERROR when the was an error
+ * freeing the parent property_list_service client.
+ */
file_relay_error_t file_relay_client_free(file_relay_client_t client);
+
+/**
+ * Request data for the given sources.
+ *
+ * @param client The connected file_relay client.
+ * @param sources A NULL-terminated list of sources to retrieve.
+ * Valid sources are:
+ * - AppleSupport
+ * - Network
+ * - VPN
+ * - WiFi
+ * - UserDatabases
+ * - CrashReporter
+ * - tmp
+ * - SystemConfiguration
+ * @param connection The connection that has to be used for receiving the
+ * 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.
+ *
+ * @return FILE_RELAY_E_SUCCESS on succes, FILE_RELAY_E_INVALID_ARG when one or
+ * more parameters are invalid, FILE_RELAY_E_MUX_ERROR if a communication
+ * error occurs, FILE_RELAY_E_PLIST_ERROR when the received result is NULL
+ * or is not a valid plist, FILE_RELAY_E_INVALID_SOURCE if one or more
+ * sources are invalid, FILE_RELAY_E_STAGING_EMPTY if no data is available
+ * for the given sources, or FILE_RELAY_E_UNKNOWN_ERROR otherwise.
+ */
file_relay_error_t file_relay_request_sources(file_relay_client_t client, const char **sources, idevice_connection_t *connection);
+
+/**
+ * Request data for the given sources. Calls file_relay_request_sources_timeout() with
+ * a timeout of 60000 milliseconds (60 seconds).
+ *
+ * @param client The connected file_relay client.
+ * @param sources A NULL-terminated list of sources to retrieve.
+ * Valid sources are:
+ * - AppleSupport
+ * - Network
+ * - VPN
+ * - WiFi
+ * - UserDatabases
+ * - CrashReporter
+ * - tmp
+ * - SystemConfiguration
+ * @param connection The connection that has to be used for receiving the
+ * data using idevice_connection_receive(). The connection will be closed
+ * automatically by the device, but use file_relay_client_free() to clean
+ * up properly.
+ *
+ * @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.
+ *
+ * @return FILE_RELAY_E_SUCCESS on succes, FILE_RELAY_E_INVALID_ARG when one or
+ * more parameters are invalid, FILE_RELAY_E_MUX_ERROR if a communication
+ * error occurs, FILE_RELAY_E_PLIST_ERROR when the received result is NULL
+ * or is not a valid plist, FILE_RELAY_E_INVALID_SOURCE if one or more
+ * sources are invalid, FILE_RELAY_E_STAGING_EMPTY if no data is available
+ * for the given sources, or FILE_RELAY_E_UNKNOWN_ERROR otherwise.
+ */
file_relay_error_t file_relay_request_sources_timeout(file_relay_client_t client, const char **sources, idevice_connection_t *connection, unsigned int timeout);
#ifdef __cplusplus
diff --git a/include/libimobiledevice/heartbeat.h b/include/libimobiledevice/heartbeat.h
index 8db2941..c943e51 100644
--- a/include/libimobiledevice/heartbeat.h
+++ b/include/libimobiledevice/heartbeat.h
@@ -48,12 +48,84 @@ typedef int16_t heartbeat_error_t;
typedef struct heartbeat_client_private heartbeat_client_private;
typedef heartbeat_client_private *heartbeat_client_t; /**< The client handle. */
+/**
+ * Connects to the heartbeat 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
+ * heartbeat_client_t upon successful return. Must be freed using
+ * heartbeat_client_free() after use.
+ *
+ * @return HEARTBEAT_E_SUCCESS on success, HEARTBEAT_E_INVALID_ARG when
+ * client is NULL, or an HEARTBEAT_E_* error code otherwise.
+ */
heartbeat_error_t heartbeat_client_new(idevice_t device, lockdownd_service_descriptor_t service, heartbeat_client_t * client);
+
+/**
+ * Starts a new heartbeat 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
+ * heartbeat_client_t upon successful return. Must be freed using
+ * heartbeat_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 HEARTBEAT_E_SUCCESS on success, or an HEARTBEAT_E_* error
+ * code otherwise.
+ */
heartbeat_error_t heartbeat_client_start_service(idevice_t device, heartbeat_client_t * client, const char* label);
+
+/**
+ * Disconnects a heartbeat client from the device and frees up the
+ * heartbeat client data.
+ *
+ * @param client The heartbeat client to disconnect and free.
+ *
+ * @return HEARTBEAT_E_SUCCESS on success, HEARTBEAT_E_INVALID_ARG when
+ * client is NULL, or an HEARTBEAT_E_* error code otherwise.
+ */
heartbeat_error_t heartbeat_client_free(heartbeat_client_t client);
+
+/**
+ * Sends a plist to the service.
+ *
+ * @param client The heartbeat client
+ * @param plist The plist to send
+ *
+ * @return HEARTBEAT_E_SUCCESS on success,
+ * HEARTBEAT_E_INVALID_ARG when client or plist is NULL
+ */
heartbeat_error_t heartbeat_send(heartbeat_client_t client, plist_t plist);
+
+/**
+ * Receives a plist from the service.
+ *
+ * @param client The heartbeat client
+ * @param plist The plist to store the received data
+ *
+ * @return HEARTBEAT_E_SUCCESS on success,
+ * HEARTBEAT_E_INVALID_ARG when client or plist is NULL
+ */
heartbeat_error_t heartbeat_receive(heartbeat_client_t client, plist_t * plist);
+
+/**
+ * Receives a plist using the given heartbeat client.
+ *
+ * @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.
+ *
+ * @return HEARTBEAT_E_SUCCESS on success,
+ * HEARTBEAT_E_INVALID_ARG when client or *plist is NULL,
+ * HEARTBEAT_E_PLIST_ERROR when the received data cannot be
+ * converted to a plist, HEARTBEAT_E_MUX_ERROR when a
+ * communication error occurs, or HEARTBEAT_E_UNKNOWN_ERROR
+ * when an unspecified error occurs.
+ */
heartbeat_error_t heartbeat_receive_with_timeout(heartbeat_client_t client, plist_t * plist, uint32_t timeout_ms);
#ifdef __cplusplus
diff --git a/include/libimobiledevice/house_arrest.h b/include/libimobiledevice/house_arrest.h
index ccd6ac7..170cad2 100644
--- a/include/libimobiledevice/house_arrest.h
+++ b/include/libimobiledevice/house_arrest.h
@@ -51,14 +51,128 @@ typedef struct house_arrest_client_private house_arrest_client_private;
typedef house_arrest_client_private *house_arrest_client_t; /**< The client handle. */
/* Interface */
+
+/**
+ * Connects to the house_arrest 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
+ * housearrest_client_t upon successful return.
+ *
+ * @return HOUSE_ARREST_E_SUCCESS on success, HOUSE_ARREST_E_INVALID_ARG when
+ * client is NULL, or an HOUSE_ARREST_E_* error code otherwise.
+ */
house_arrest_error_t house_arrest_client_new(idevice_t device, lockdownd_service_descriptor_t service, house_arrest_client_t *client);
+
+/**
+ * Starts a new house_arrest 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
+ * house_arrest_client_t upon successful return. Must be freed using
+ * house_arrest_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 HOUSE_ARREST_E_SUCCESS on success, or an HOUSE_ARREST_E_* error
+ * code otherwise.
+ */
house_arrest_error_t house_arrest_client_start_service(idevice_t device, house_arrest_client_t* client, const char* label);
+
+/**
+ * Disconnects an house_arrest client from the device and frees up the
+ * house_arrest client data.
+ *
+ * @note After using afc_client_new_from_house_arrest_client(), make sure
+ * you call afc_client_free() before calling this function to ensure
+ * a proper cleanup. Do not call this function if you still need to
+ * perform AFC operations since it will close the connection.
+ *
+ * @param client The house_arrest client to disconnect and free.
+ *
+ * @return HOUSE_ARREST_E_SUCCESS on success, HOUSE_ARREST_E_INVALID_ARG when
+ * client is NULL, or an HOUSE_ARREST_E_* error code otherwise.
+ */
house_arrest_error_t house_arrest_client_free(house_arrest_client_t client);
+
+/**
+ * Sends a generic request to the connected house_arrest service.
+ *
+ * @param client The house_arrest client to use.
+ * @param dict The request to send as a plist of type PLIST_DICT.
+ *
+ * @note If this function returns HOUSE_ARREST_E_SUCCESS it does not mean
+ * that the request was successful. To check for success or failure you
+ * need to call house_arrest_get_result().
+ * @see house_arrest_get_result
+ *
+ * @return HOUSE_ARREST_E_SUCCESS if the request was successfully sent,
+ * HOUSE_ARREST_E_INVALID_ARG if client or dict is invalid,
+ * HOUSE_ARREST_E_PLIST_ERROR if dict is not a plist of type PLIST_DICT,
+ * HOUSE_ARREST_E_INVALID_MODE if the client is not in the correct mode,
+ * or HOUSE_ARREST_E_CONN_FAILED if a connection error occured.
+ */
house_arrest_error_t house_arrest_send_request(house_arrest_client_t client, plist_t dict);
+
+/**
+ * Send a command to the connected house_arrest service.
+ * Calls house_arrest_send_request() internally.
+ *
+ * @param client The house_arrest client to use.
+ * @param command The command to send. Currently, only VendContainer and
+ * VendDocuments are known.
+ * @param appid The application identifier to pass along with the .
+ *
+ * @note If this function returns HOUSE_ARREST_E_SUCCESS it does not mean
+ * that the command was successful. To check for success or failure you
+ * need to call house_arrest_get_result().
+ * @see house_arrest_get_result
+ *
+ * @return HOUSE_ARREST_E_SUCCESS if the command was successfully sent,
+ * HOUSE_ARREST_E_INVALID_ARG if client, command, or appid is invalid,
+ * HOUSE_ARREST_E_INVALID_MODE if the client is not in the correct mode,
+ * or HOUSE_ARREST_E_CONN_FAILED if a connection error occured.
+ */
house_arrest_error_t house_arrest_send_command(house_arrest_client_t client, const char *command, const char *appid);
+
+/**
+ * Retrieves the result of a previously sent house_arrest_request_* request.
+ *
+ * @param client The house_arrest client to use
+ * @param dict Pointer that will be set to a plist containing the result to
+ * the last performed operation. It holds a key 'Status' with the value
+ * 'Complete' on success or a key 'Error' with an error description as
+ * value. The caller is responsible for freeing the returned plist.
+ *
+ * @return HOUSE_ARREST_E_SUCCESS if a result plist was retrieved,
+ * HOUSE_ARREST_E_INVALID_ARG if client is invalid,
+ * HOUSE_ARREST_E_INVALID_MODE if the client is not in the correct mode,
+ * or HOUSE_ARREST_E_CONN_FAILED if a connection error occured.
+ */
house_arrest_error_t house_arrest_get_result(house_arrest_client_t client, plist_t *dict);
+
+/**
+ * Creates an AFC client using the given house_arrest client's connection
+ * allowing file access to a specific application directory requested by
+ * functions like house_arrest_request_vendor_documents().
+ *
+ * @param client The house_arrest client to use.
+ * @param afc_client Pointer that will be set to a newly allocated afc_client_t
+ * upon successful return.
+ *
+ * @note After calling this function the house_arrest client will go in an
+ * AFC mode that will only allow calling house_arrest_client_free().
+ * Only call house_arrest_client_free() if all AFC operations have
+ * completed since it will close the connection.
+ *
+ * @return AFC_E_SUCCESS if the afc client was successfully created,
+ * AFC_E_INVALID_ARG if client is invalid or was already used to create
+ * an afc client, or an AFC_E_* error code returned by
+ * afc_client_new_with_service_client().
+ */
afc_error_t afc_client_new_from_house_arrest_client(house_arrest_client_t client, afc_client_t *afc_client);
#ifdef __cplusplus
diff --git a/include/libimobiledevice/installation_proxy.h b/include/libimobiledevice/installation_proxy.h
index 18b7804..4740b20 100644
--- a/include/libimobiledevice/installation_proxy.h
+++ b/include/libimobiledevice/installation_proxy.h
@@ -55,24 +55,271 @@ typedef instproxy_client_private *instproxy_client_t; /**< The client handle. */
typedef void (*instproxy_status_cb_t) (const char *operation, plist_t status, void *user_data);
/* Interface */
+
+/**
+ * Connects to the installation_proxy 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 be set to a newly allocated
+ * instproxy_client_t upon successful return.
+ *
+ * @return INSTPROXY_E_SUCCESS on success, or an INSTPROXY_E_* error value
+ * when an error occured.
+ */
instproxy_error_t instproxy_client_new(idevice_t device, lockdownd_service_descriptor_t service, instproxy_client_t *client);
+
+/**
+ * Starts a new installation_proxy 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
+ * instproxy_client_t upon successful return. Must be freed using
+ * instproxy_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 INSTPROXY_E_SUCCESS on success, or an INSTPROXY_E_* error
+ * code otherwise.
+ */
instproxy_error_t instproxy_client_start_service(idevice_t device, instproxy_client_t * client, const char* label);
+
+/**
+ * Disconnects an installation_proxy client from the device and frees up the
+ * installation_proxy client data.
+ *
+ * @param client The installation_proxy client to disconnect and free.
+ *
+ * @return INSTPROXY_E_SUCCESS on success
+ * or INSTPROXY_E_INVALID_ARG if client is NULL.
+ */
instproxy_error_t instproxy_client_free(instproxy_client_t client);
+
+/**
+ * List installed applications. This function runs synchronously.
+ *
+ * @param client The connected installation_proxy client
+ * @param client_options The client options to use, as PLIST_DICT, or NULL.
+ * Valid client options include:
+ * "ApplicationType" -> "User"
+ * "ApplicationType" -> "System"
+ * @param result Pointer that will be set to a plist that will hold an array
+ * of PLIST_DICT holding information about the applications found.
+ *
+ * @return INSTPROXY_E_SUCCESS on success or an INSTPROXY_E_* error value if
+ * an error occured.
+ */
instproxy_error_t instproxy_browse(instproxy_client_t client, plist_t client_options, plist_t *result);
+
+/**
+ * Install an application on the device.
+ *
+ * @param client The connected installation_proxy client
+ * @param pkg_path Path of the installation package (inside the AFC jail)
+ * @param client_options The client options to use, as PLIST_DICT, or NULL.
+ * Valid options include:
+ * "iTunesMetadata" -> PLIST_DATA
+ * "ApplicationSINF" -> PLIST_DATA
+ * "PackageType" -> "Developer"
+ * If PackageType -> Developer is specified, then pkg_path points to
+ * an .app directory instead of an install package.
+ * @param status_cb Callback function for progress and status information. If
+ * NULL is passed, this function will run synchronously.
+ * @param user_data Callback data passed to status_cb.
+ *
+ * @return INSTPROXY_E_SUCCESS on success or an INSTPROXY_E_* error value if
+ * an error occured.
+ *
+ * @note If a callback function is given (async mode), this function returns
+ * INSTPROXY_E_SUCCESS immediately if the status updater thread has been
+ * created successfully; any error occuring during the operation has to be
+ * handled inside the specified callback function.
+ */
instproxy_error_t instproxy_install(instproxy_client_t client, const char *pkg_path, plist_t client_options, instproxy_status_cb_t status_cb, void *user_data);
+
+/**
+ * Upgrade an application on the device. This function is nearly the same as
+ * instproxy_install; the difference is that the installation progress on the
+ * device is faster if the application is already installed.
+ *
+ * @param client The connected installation_proxy client
+ * @param pkg_path Path of the installation package (inside the AFC jail)
+ * @param client_options The client options to use, as PLIST_DICT, or NULL.
+ * Valid options include:
+ * "iTunesMetadata" -> PLIST_DATA
+ * "ApplicationSINF" -> PLIST_DATA
+ * "PackageType" -> "Developer"
+ * If PackageType -> Developer is specified, then pkg_path points to
+ * an .app directory instead of an install package.
+ * @param status_cb Callback function for progress and status information. If
+ * NULL is passed, this function will run synchronously.
+ * @param user_data Callback data passed to status_cb.
+ *
+ * @return INSTPROXY_E_SUCCESS on success or an INSTPROXY_E_* error value if
+ * an error occured.
+ *
+ * @note If a callback function is given (async mode), this function returns
+ * INSTPROXY_E_SUCCESS immediately if the status updater thread has been
+ * created successfully; any error occuring during the operation has to be
+ * handled inside the specified callback function.
+ */
instproxy_error_t instproxy_upgrade(instproxy_client_t client, const char *pkg_path, plist_t client_options, instproxy_status_cb_t status_cb, void *user_data);
+
+/**
+ * Uninstall an application from the device.
+ *
+ * @param client The connected installation proxy client
+ * @param appid ApplicationIdentifier of the app to uninstall
+ * @param client_options The client options to use, as PLIST_DICT, or NULL.
+ * Currently there are no known client options, so pass NULL here.
+ * @param status_cb Callback function for progress and status information. If
+ * NULL is passed, this function will run synchronously.
+ * @param user_data Callback data passed to status_cb.
+ *
+ * @return INSTPROXY_E_SUCCESS on success or an INSTPROXY_E_* error value if
+ * an error occured.
+ *
+ * @note If a callback function is given (async mode), this function returns
+ * INSTPROXY_E_SUCCESS immediately if the status updater thread has been
+ * created successfully; any error occuring during the operation has to be
+ * handled inside the specified callback function.
+ */
instproxy_error_t instproxy_uninstall(instproxy_client_t client, const char *appid, plist_t client_options, instproxy_status_cb_t status_cb, void *user_data);
+
+/**
+ * List archived applications. This function runs synchronously.
+ *
+ * @see instproxy_archive
+ *
+ * @param client The connected installation_proxy client
+ * @param client_options The client options to use, as PLIST_DICT, or NULL.
+ * Currently there are no known client options, so pass NULL here.
+ * @param result Pointer that will be set to a plist containing a PLIST_DICT
+ * holding information about the archived applications found.
+ *
+ * @return INSTPROXY_E_SUCCESS on success or an INSTPROXY_E_* error value if
+ * an error occured.
+ */
instproxy_error_t instproxy_lookup_archives(instproxy_client_t client, plist_t client_options, plist_t *result);
+
+/**
+ * Archive an application on the device.
+ * This function tells the device to make an archive of the specified
+ * application. This results in the device creating a ZIP archive in the
+ * 'ApplicationArchives' directory and uninstalling the application.
+ *
+ * @param client The connected installation proxy client
+ * @param appid ApplicationIdentifier of the app to archive.
+ * @param client_options The client options to use, as PLIST_DICT, or NULL.
+ * Valid options include:
+ * "SkipUninstall" -> Boolean
+ * "ArchiveType" -> "ApplicationOnly"
+ * @param status_cb Callback function for progress and status information. If
+ * NULL is passed, this function will run synchronously.
+ * @param user_data Callback data passed to status_cb.
+ *
+ * @return INSTPROXY_E_SUCCESS on success or an INSTPROXY_E_* error value if
+ * an error occured.
+ *
+ * @note If a callback function is given (async mode), this function returns
+ * INSTPROXY_E_SUCCESS immediately if the status updater thread has been
+ * created successfully; any error occuring during the operation has to be
+ * handled inside the specified callback function.
+ */
instproxy_error_t instproxy_archive(instproxy_client_t client, const char *appid, plist_t client_options, instproxy_status_cb_t status_cb, void *user_data);
+
+/**
+ * Restore a previously archived application on the device.
+ * This function is the counterpart to instproxy_archive.
+ * @see instproxy_archive
+ *
+ * @param client The connected installation proxy client
+ * @param appid ApplicationIdentifier of the app to restore.
+ * @param client_options The client options to use, as PLIST_DICT, or NULL.
+ * Currently there are no known client options, so pass NULL here.
+ * @param status_cb Callback function for progress and status information. If
+ * NULL is passed, this function will run synchronously.
+ * @param user_data Callback data passed to status_cb.
+ *
+ * @return INSTPROXY_E_SUCCESS on success or an INSTPROXY_E_* error value if
+ * an error occured.
+ *
+ * @note If a callback function is given (async mode), this function returns
+ * INSTPROXY_E_SUCCESS immediately if the status updater thread has been
+ * created successfully; any error occuring during the operation has to be
+ * handled inside the specified callback function.
+ */
instproxy_error_t instproxy_restore(instproxy_client_t client, const char *appid, plist_t client_options, instproxy_status_cb_t status_cb, void *user_data);
+
+/**
+ * Removes a previously archived application from the device.
+ * This function removes the ZIP archive from the 'ApplicationArchives'
+ * directory.
+ *
+ * @param client The connected installation proxy client
+ * @param appid ApplicationIdentifier of the archived app to remove.
+ * @param client_options The client options to use, as PLIST_DICT, or NULL.
+ * Currently there are no known client options, so passing NULL is fine.
+ * @param status_cb Callback function for progress and status information. If
+ * NULL is passed, this function will run synchronously.
+ * @param user_data Callback data passed to status_cb.
+ *
+ * @return INSTPROXY_E_SUCCESS on success or an INSTPROXY_E_* error value if
+ * an error occured.
+ *
+ * @note If a callback function is given (async mode), this function returns
+ * INSTPROXY_E_SUCCESS immediately if the status updater thread has been
+ * created successfully; any error occuring during the operation has to be
+ * handled inside the specified callback function.
+ */
instproxy_error_t instproxy_remove_archive(instproxy_client_t client, const char *appid, plist_t client_options, instproxy_status_cb_t status_cb, void *user_data);
/* Helper */
+
+/**
+ * Create a new client_options plist.
+ *
+ * @return A new plist_t of type PLIST_DICT.
+ */
plist_t instproxy_client_options_new();
+
+/**
+ * Add one or more new key:value pairs to the given client_options.
+ *
+ * @param client_options The client options to modify.
+ * @param ... KEY, VALUE, [KEY, VALUE], NULL
+ *
+ * @note The keys and values passed are expected to be strings, except for the
+ * keys "ApplicationSINF", "iTunesMetadata", "ReturnAttributes" which are
+ * expecting a plist_t node as value and "SkipUninstall" expects int.
+ */
void instproxy_client_options_add(plist_t client_options, ...);
+
+/**
+ * Free client_options plist.
+ *
+ * @param client_options The client options plist to free. Does nothing if NULL
+ * is passed.
+ */
void instproxy_client_options_free(plist_t client_options);
+
+/**
+ * Query 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 path Pointer to store the device path for the application
+ * which is set to NULL if it could not be determined.
+ *
+ * @return INSTPROXY_E_SUCCESS on success, INSTPROXY_E_OP_FAILED if
+ * the path could not be determined or an INSTPROXY_E_* error
+ * value if an error occured.
+ *
+ * @note This implementation browses all applications and matches the
+ * right entry by the application identifier.
+ */
instproxy_error_t instproxy_client_get_path_for_bundle_identifier(instproxy_client_t client, const char* bundle_id, char** path);
#ifdef __cplusplus
diff --git a/include/libimobiledevice/libimobiledevice.h b/include/libimobiledevice/libimobiledevice.h
index e33715f..3cbb96b 100644
--- a/include/libimobiledevice/libimobiledevice.h
+++ b/include/libimobiledevice/libimobiledevice.h
@@ -75,30 +75,177 @@ typedef struct {
typedef void (*idevice_event_cb_t) (const idevice_event_t *event, void *user_data);
/* functions */
+
+/**
+ * Register a callback function that will be called when device add/remove
+ * events occur.
+ *
+ * @param callback Callback function to call.
+ * @param user_data Application-specific data passed as parameter
+ * to the registered callback function.
+ *
+ * @return IDEVICE_E_SUCCESS on success or an error value when an error occured.
+ */
idevice_error_t idevice_event_subscribe(idevice_event_cb_t callback, void *user_data);
+
+/**
+ * Release the event callback function that has been registered with
+ * idevice_event_subscribe().
+ *
+ * @return IDEVICE_E_SUCCESS on success or an error value when an error occured.
+ */
idevice_error_t idevice_event_unsubscribe();
/* discovery (synchronous) */
+
+/**
+ * Get a list of currently available devices.
+ *
+ * @param devices List of udids of devices that are currently available.
+ * This list is terminated by a NULL pointer.
+ * @param count Number of devices found.
+ *
+ * @return IDEVICE_E_SUCCESS on success or an error value when an error occured.
+ */
idevice_error_t idevice_get_device_list(char ***devices, int *count);
+
+/**
+ * Free a list of device udids.
+ *
+ * @param devices List of udids to free.
+ *
+ * @return Always returnes IDEVICE_E_SUCCESS.
+ */
idevice_error_t idevice_device_list_free(char **devices);
/* device structure creation and destruction */
+
+/**
+ * Creates an idevice_t structure for the device specified by udid,
+ * if the device is available.
+ *
+ * @note The resulting idevice_t structure has to be freed with
+ * idevice_free() if it is no longer used.
+ *
+ * @param device Upon calling this function, a pointer to a location of type
+ * idevice_t. On successful return, this location will be populated.
+ * @param udid The UDID to match.
+ *
+ * @return IDEVICE_E_SUCCESS if ok, otherwise an error code.
+ */
idevice_error_t idevice_new(idevice_t *device, const char *udid);
+
+/**
+ * Cleans up an idevice structure, then frees the structure itself.
+ * This is a library-level function; deals directly with the device to tear
+ * down relations, but otherwise is mostly internal.
+ *
+ * @param device idevice_t to free.
+ */
idevice_error_t idevice_free(idevice_t device);
/* connection/disconnection */
+
+/**
+ * Set up a connection to the given device.
+ *
+ * @param device The device to connect to.
+ * @param port The destination port to connect to.
+ * @param connection Pointer to an idevice_connection_t that will be filled
+ * with the necessary data of the connection.
+ *
+ * @return IDEVICE_E_SUCCESS if ok, otherwise an error code.
+ */
idevice_error_t idevice_connect(idevice_t device, uint16_t port, idevice_connection_t *connection);
+
+/**
+ * Disconnect from the device and clean up the connection structure.
+ *
+ * @param connection The connection to close.
+ *
+ * @return IDEVICE_E_SUCCESS if ok, otherwise an error code.
+ */
idevice_error_t idevice_disconnect(idevice_connection_t connection);
/* communication */
+
+/**
+ * Send data to a device via the given connection.
+ *
+ * @param connection The connection to send data over.
+ * @param data Buffer with data to send.
+ * @param len Size of the buffer to send.
+ * @param sent_bytes Pointer to an uint32_t that will be filled
+ * with the number of bytes actually sent.
+ *
+ * @return IDEVICE_E_SUCCESS if ok, otherwise an error code.
+ */
idevice_error_t idevice_connection_send(idevice_connection_t connection, const char *data, uint32_t len, uint32_t *sent_bytes);
+
+/**
+ * Receive data from a device via the given connection.
+ * This function will return after the given timeout even if no data has been
+ * received.
+ *
+ * @param connection The connection to receive data from.
+ * @param data Buffer that will be filled with the received data.
+ * This buffer has to be large enough to hold len bytes.
+ * @param len Buffer size or number of bytes to receive.
+ * @param recv_bytes Number of bytes actually received.
+ * @param timeout Timeout in milliseconds after which this function should
+ * return even if no data has been received.
+ *
+ * @return IDEVICE_E_SUCCESS if ok, otherwise an error code.
+ */
idevice_error_t idevice_connection_receive_timeout(idevice_connection_t connection, char *data, uint32_t len, uint32_t *recv_bytes, unsigned int timeout);
+
+/**
+ * Receive data from a device via the given connection.
+ * This function is like idevice_connection_receive_timeout, but with a
+ * predefined reasonable timeout.
+ *
+ * @param connection The connection to receive data from.
+ * @param data Buffer that will be filled with the received data.
+ * This buffer has to be large enough to hold len bytes.
+ * @param len Buffer size or number of bytes to receive.
+ * @param recv_bytes Number of bytes actually received.
+ *
+ * @return IDEVICE_E_SUCCESS if ok, otherwise an error code.
+ */
idevice_error_t idevice_connection_receive(idevice_connection_t connection, char *data, uint32_t len, uint32_t *recv_bytes);
+
+/**
+ * Enables SSL for the given connection.
+ *
+ * @param connection The connection to enable SSL for.
+ *
+ * @return IDEVICE_E_SUCCESS on success, IDEVICE_E_INVALID_ARG when connection
+ * is NULL or connection->ssl_data is non-NULL, or IDEVICE_E_SSL_ERROR when
+ * SSL initialization, setup, or handshake fails.
+ */
idevice_error_t idevice_connection_enable_ssl(idevice_connection_t connection);
+
+/**
+ * Disable SSL for the given connection.
+ *
+ * @param connection The connection to disable SSL for.
+ *
+ * @return IDEVICE_E_SUCCESS on success, IDEVICE_E_INVALID_ARG when connection
+ * is NULL. This function also returns IDEVICE_E_SUCCESS when SSL is not
+ * enabled and does no further error checking on cleanup.
+ */
idevice_error_t idevice_connection_disable_ssl(idevice_connection_t connection);
/* misc */
+
+/**
+ * Gets the handle of the device. Depends on the connection type.
+ */
idevice_error_t idevice_get_handle(idevice_t device, uint32_t *handle);
+
+/**
+ * Gets the unique id for the device.
+ */
idevice_error_t idevice_get_udid(idevice_t device, char **udid);
#ifdef __cplusplus
diff --git a/include/libimobiledevice/lockdown.h b/include/libimobiledevice/lockdown.h
index 233c796..d59c489 100644
--- a/include/libimobiledevice/lockdown.h
+++ b/include/libimobiledevice/lockdown.h
@@ -81,33 +81,335 @@ struct lockdownd_service_descriptor {
typedef struct lockdownd_service_descriptor *lockdownd_service_descriptor_t;
/* Interface */
+
+/**
+ * Creates a new lockdownd client for the device.
+ *
+ * @note This function does not pair with the device or start a session. This
+ * has to be done manually by the caller after the client is created.
+ * The device disconnects automatically if the lockdown connection idles
+ * for more than 10 seconds. Make sure to call lockdownd_client_free() as soon
+ * as the connection is no longer needed.
+ *
+ * @param device The device to create a lockdownd client for
+ * @param client The pointer to the location of the new lockdownd_client
+ * @param label The label to use for communication. Usually the program name.
+ *
+ * @return LOCKDOWN_E_SUCCESS on success, NP_E_INVALID_ARG when client is NULL
+ */
lockdownd_error_t lockdownd_client_new(idevice_t device, lockdownd_client_t *client, const char *label);
+
+/**
+ * Creates a new lockdownd client for the device and starts initial handshake.
+ * The handshake consists out of query_type, validate_pair, pair and
+ * start_session calls. It uses the internal pairing record management.
+ *
+ * @note The device disconnects automatically if the lockdown connection idles
+ * for more than 10 seconds. Make sure to call lockdownd_client_free() as soon
+ * as the connection is no longer needed.
+ *
+ * @param device The device to create a lockdownd client for
+ * @param client The pointer to the location of the new lockdownd_client
+ * @param label The label to use for communication. Usually the program name.
+ * Pass NULL to disable sending the label in requests to lockdownd.
+ *
+ * @return LOCKDOWN_E_SUCCESS on success, NP_E_INVALID_ARG when client is NULL,
+ * LOCKDOWN_E_INVALID_CONF if configuration data is wrong
+ */
lockdownd_error_t lockdownd_client_new_with_handshake(idevice_t device, lockdownd_client_t *client, const char *label);
+
+/**
+ * Closes the lockdownd client session if one is running and frees up the
+ * lockdownd_client struct.
+ *
+ * @param client The lockdown client
+ *
+ * @return LOCKDOWN_E_SUCCESS on success, NP_E_INVALID_ARG when client is NULL
+ */
lockdownd_error_t lockdownd_client_free(lockdownd_client_t client);
+
+/**
+ * Query the type of the service daemon. Depending on whether the device is
+ * queried in normal mode or restore mode, different types will be returned.
+ *
+ * @param client The lockdownd client
+ * @param type The type returned by the service daemon. Pass NULL to ignore.
+ *
+ * @return LOCKDOWN_E_SUCCESS on success, NP_E_INVALID_ARG when client is NULL
+ */
lockdownd_error_t lockdownd_query_type(lockdownd_client_t client, char **type);
+
+/**
+ * Retrieves a preferences plist using an optional domain and/or key name.
+ *
+ * @param client An initialized lockdownd client.
+ * @param domain The domain to query on or NULL for global domain
+ * @param key The key name to request or NULL to query for all keys
+ * @param value A plist node representing the result value node
+ *
+ * @return LOCKDOWN_E_SUCCESS on success, NP_E_INVALID_ARG when client is NULL
+ */
lockdownd_error_t lockdownd_get_value(lockdownd_client_t client, const char *domain, const char *key, plist_t *value);
+
+/**
+ * Sets a preferences value using a plist and optional by domain and/or key name.
+ *
+ * @param client an initialized lockdownd client.
+ * @param domain the domain to query on or NULL for global domain
+ * @param key the key name to set the value or NULL to set a value dict plist
+ * @param value a plist node of any node type representing the value to set
+ *
+ * @return LOCKDOWN_E_SUCCESS on success, NP_E_INVALID_ARG when client or
+ * value is NULL
+ */
lockdownd_error_t lockdownd_set_value(lockdownd_client_t client, const char *domain, const char *key, plist_t value);
+
+/**
+ * Removes a preference node by domain and/or key name.
+ *
+ * @note: Use with caution as this could remove vital information on the device
+ *
+ * @param client An initialized lockdownd client.
+ * @param domain The domain to query on or NULL for global domain
+ * @param key The key name to remove or NULL remove all keys for the current domain
+ *
+ * @return LOCKDOWN_E_SUCCESS on success, NP_E_INVALID_ARG when client is NULL
+ */
lockdownd_error_t lockdownd_remove_value(lockdownd_client_t client, const char *domain, const char *key);
+
+/**
+ * Requests to start a service and retrieve it's port on success.
+ *
+ * @param client The lockdownd client
+ * @param identifier The identifier of the service to start
+ * @param descriptor The service descriptor on success or NULL on failure
+
+ * @return LOCKDOWN_E_SUCCESS on success, NP_E_INVALID_ARG if a parameter
+ * is NULL, LOCKDOWN_E_INVALID_SERVICE if the requested service is not known
+ * by the device, LOCKDOWN_E_START_SERVICE_FAILED if the service could not because
+ * started by the device
+ */
lockdownd_error_t lockdownd_start_service(lockdownd_client_t client, const char *identifier, lockdownd_service_descriptor_t *service);
+
+/**
+ * Opens a session with lockdownd and switches to SSL mode if device wants it.
+ *
+ * @param client The lockdownd client
+ * @param host_id The HostID of the computer
+ * @param session_id The new session_id of the created session
+ * @param ssl_enabled Whether SSL communication is used in the session
+ *
+ * @return LOCKDOWN_E_SUCCESS on success, LOCKDOWN_E_INVALID_ARG when a client
+ * or host_id is NULL, LOCKDOWN_E_PLIST_ERROR if the response plist had errors,
+ * LOCKDOWN_E_INVALID_HOST_ID if the device does not know the supplied HostID,
+ * LOCKDOWN_E_SSL_ERROR if enabling SSL communication failed
+ */
lockdownd_error_t lockdownd_start_session(lockdownd_client_t client, const char *host_id, char **session_id, int *ssl_enabled);
+
+/**
+ * Closes the lockdownd session by sending the StopSession request.
+ *
+ * @see lockdownd_start_session
+ *
+ * @param client The lockdown client
+ * @param session_id The id of a running session
+ *
+ * @return LOCKDOWN_E_SUCCESS on success, NP_E_INVALID_ARG when client is NULL
+ */
lockdownd_error_t lockdownd_stop_session(lockdownd_client_t client, const char *session_id);
+
+/**
+ * Sends a plist to lockdownd.
+ *
+ * @note This function is low-level and should only be used if you need to send
+ * a new type of message.
+ *
+ * @param client The lockdownd client
+ * @param plist The plist to send
+ *
+ * @return LOCKDOWN_E_SUCCESS on success, NP_E_INVALID_ARG when client or
+ * plist is NULL
+ */
lockdownd_error_t lockdownd_send(lockdownd_client_t client, plist_t plist);
+
+/**
+ * Receives a plist from lockdownd.
+ *
+ * @param client The lockdownd client
+ * @param plist The plist to store the received data
+ *
+ * @return LOCKDOWN_E_SUCCESS on success, NP_E_INVALID_ARG when client or
+ * plist is NULL
+ */
lockdownd_error_t lockdownd_receive(lockdownd_client_t client, plist_t *plist);
+
+/**
+ * Pairs the device using the supplied pair record.
+ *
+ * @param client The lockdown client to pair with.
+ * @param pair_record The pair record to use for pairing. If NULL is passed, then
+ * the pair records from the current machine are used. New records will be
+ * generated automatically when pairing is done for the first time.
+ *
+ * @return LOCKDOWN_E_SUCCESS on success, NP_E_INVALID_ARG when client is NULL,
+ * LOCKDOWN_E_PLIST_ERROR if the pair_record certificates are wrong,
+ * LOCKDOWN_E_PAIRING_FAILED if the pairing failed,
+ * LOCKDOWN_E_PASSWORD_PROTECTED if the device is password protected,
+ * LOCKDOWN_E_INVALID_HOST_ID if the device does not know the caller's host id
+ */
lockdownd_error_t lockdownd_pair(lockdownd_client_t client, lockdownd_pair_record_t pair_record);
+
+/**
+ * Validates if the device is paired with the given HostID. If succeeded them
+ * specified host will become trusted host of the device indicated by the
+ * lockdownd preference named TrustedHostAttached. Otherwise the host must because
+ * paired using lockdownd_pair() first.
+ *
+ * @param client The lockdown client to pair with.
+ * @param pair_record The pair record to validate pairing with. If NULL is
+ * passed, then the pair record is read from the internal pairing record
+ * management.
+ *
+ * @return LOCKDOWN_E_SUCCESS on success, NP_E_INVALID_ARG when client is NULL,
+ * LOCKDOWN_E_PLIST_ERROR if the pair_record certificates are wrong,
+ * LOCKDOWN_E_PAIRING_FAILED if the pairing failed,
+ * LOCKDOWN_E_PASSWORD_PROTECTED if the device is password protected,
+ * LOCKDOWN_E_INVALID_HOST_ID if the device does not know the caller's host id
+ */
lockdownd_error_t lockdownd_validate_pair(lockdownd_client_t client, lockdownd_pair_record_t pair_record);
+
+/**
+ * Unpairs the device with the given HostID and removes the pairing records
+ * from the device and host if the internal pairing record management is used.
+ *
+ * @param client The lockdown client to pair with.
+ * @param pair_record The pair record to use for unpair. If NULL is passed, then
+ * the pair records from the current machine are used.
+ *
+ * @return LOCKDOWN_E_SUCCESS on success, NP_E_INVALID_ARG when client is NULL,
+ * LOCKDOWN_E_PLIST_ERROR if the pair_record certificates are wrong,
+ * LOCKDOWN_E_PAIRING_FAILED if the pairing failed,
+ * LOCKDOWN_E_PASSWORD_PROTECTED if the device is password protected,
+ * LOCKDOWN_E_INVALID_HOST_ID if the device does not know the caller's host id
+ */
lockdownd_error_t lockdownd_unpair(lockdownd_client_t client, lockdownd_pair_record_t pair_record);
+
+/**
+ * Activates the device. Only works within an open session.
+ * The ActivationRecord plist dictionary must be obtained using the
+ * activation protocol requesting from Apple's https webservice.
+ *
+ * @see http://iphone-docs.org/doku.php?id=docs:protocols:activation
+ *
+ * @param client The lockdown client
+ * @param activation_record The activation record plist dictionary
+ *
+ * @return LOCKDOWN_E_SUCCESS on success, NP_E_INVALID_ARG when client or
+ * activation_record is NULL, LOCKDOWN_E_NO_RUNNING_SESSION if no session is
+ * open, LOCKDOWN_E_PLIST_ERROR if the received plist is broken,
+ * LOCKDOWN_E_ACTIVATION_FAILED if the activation failed,
+ * LOCKDOWN_E_INVALID_ACTIVATION_RECORD if the device reports that the
+ * activation_record is invalid
+ */
lockdownd_error_t lockdownd_activate(lockdownd_client_t client, plist_t activation_record);
+
+/**
+ * Deactivates the device, returning it to the locked “Activate with iTunes”
+ * screen.
+ *
+ * @param client The lockdown client
+ *
+ * @return LOCKDOWN_E_SUCCESS on success, NP_E_INVALID_ARG when client is NULL,
+ * LOCKDOWN_E_NO_RUNNING_SESSION if no session is open,
+ * LOCKDOWN_E_PLIST_ERROR if the received plist is broken
+ */
lockdownd_error_t lockdownd_deactivate(lockdownd_client_t client);
+
+/**
+ * Tells the device to immediately enter recovery mode.
+ *
+ * @param client The lockdown client
+ *
+ * @return LOCKDOWN_E_SUCCESS on success, NP_E_INVALID_ARG when client is NULL
+ */
lockdownd_error_t lockdownd_enter_recovery(lockdownd_client_t client);
+
+/**
+ * Sends the Goodbye request to lockdownd signaling the end of communication.
+ *
+ * @param client The lockdown client
+ *
+ * @return LOCKDOWN_E_SUCCESS on success, LOCKDOWN_E_INVALID_ARG when client
+ * is NULL, LOCKDOWN_E_PLIST_ERROR if the device did not acknowledge the
+ * request
+ */
lockdownd_error_t lockdownd_goodbye(lockdownd_client_t client);
/* Helper */
+
+/**
+ * Sets the label to send for requests to lockdownd.
+ *
+ * @param client The lockdown client
+ * @param label The label to set or NULL to disable sending a label
+ *
+ */
void lockdownd_client_set_label(lockdownd_client_t client, const char *label);
+
+/**
+ * Returns the unique id of the device from lockdownd.
+ *
+ * @param client An initialized lockdownd client.
+ * @param udid Holds the unique id of the device. The caller is responsible
+ * for freeing the memory.
+ *
+ * @return LOCKDOWN_E_SUCCESS on success
+ */
lockdownd_error_t lockdownd_get_device_udid(lockdownd_client_t control, char **udid);
+
+/**
+ * Retrieves the name of the device from lockdownd set by the user.
+ *
+ * @param client An initialized lockdownd client.
+ * @param device_name Holds the name of the device. The caller is
+ * responsible for freeing the memory.
+ *
+ * @return LOCKDOWN_E_SUCCESS on success
+ */
lockdownd_error_t lockdownd_get_device_name(lockdownd_client_t client, char **device_name);
+
+/**
+ * Calculates and returns the data classes the device supports from lockdownd.
+ *
+ * @param client An initialized lockdownd client.
+ * @param classes A pointer to store an array of class names. The caller is responsible
+ * for freeing the memory which can be done using mobilesync_data_classes_free().
+ * @param count The number of items in the classes array.
+ *
+ * @return LOCKDOWN_E_SUCCESS on success,
+ * LOCKDOWN_E_INVALID_ARG when client is NULL,
+ * LOCKDOWN_E_NO_RUNNING_SESSION if no session is open,
+ * LOCKDOWN_E_PLIST_ERROR if the received plist is broken
+ */
lockdownd_error_t lockdownd_get_sync_data_classes(lockdownd_client_t client, char ***classes, int *count);
+
+/**
+ * Frees memory of an allocated array of data classes as returned by lockdownd_get_sync_data_classes()
+ *
+ * @param classes An array of class names to free.
+ *
+ * @return LOCKDOWN_E_SUCCESS on success
+ */
lockdownd_error_t lockdownd_data_classes_free(char **classes);
+
+/**
+ * Frees memory of a service descriptor as returned by lockdownd_start_service()
+ *
+ * @param sevice A service descriptor instance to free.
+ *
+ * @return LOCKDOWN_E_SUCCESS on success
+ */
lockdownd_error_t lockdownd_service_descriptor_free(lockdownd_service_descriptor_t service);
#ifdef __cplusplus
diff --git a/include/libimobiledevice/misagent.h b/include/libimobiledevice/misagent.h
index fe0acb2..7bb7333 100644
--- a/include/libimobiledevice/misagent.h
+++ b/include/libimobiledevice/misagent.h
@@ -50,13 +50,95 @@ typedef struct misagent_client_private misagent_client_private;
typedef misagent_client_private *misagent_client_t; /**< The client handle. */
/* Interface */
+
+/**
+ * Connects to the misagent 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
+ * misagent_client_t upon successful return.
+ *
+ * @return MISAGENT_E_SUCCESS on success, MISAGENT_E_INVALID_ARG when
+ * client is NULL, or an MISAGENT_E_* error code otherwise.
+ */
misagent_error_t misagent_client_new(idevice_t device, lockdownd_service_descriptor_t service, misagent_client_t *client);
+
+/**
+ * Starts a new misagent 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
+ * misagent_client_t upon successful return. Must be freed using
+ * misagent_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 MISAGENT_E_SUCCESS on success, or an MISAGENT_E_* error
+ * code otherwise.
+ */
misagent_error_t misagent_client_start_service(idevice_t device, misagent_client_t* client, const char* label);
+
+/**
+ * Disconnects an misagent client from the device and frees up the
+ * misagent client data.
+ *
+ * @param client The misagent client to disconnect and free.
+ *
+ * @return MISAGENT_E_SUCCESS on success, MISAGENT_E_INVALID_ARG when
+ * client is NULL, or an MISAGENT_E_* error code otherwise.
+ */
misagent_error_t misagent_client_free(misagent_client_t client);
+
+/**
+ * Installs the given provisioning profile. Only works with valid profiles.
+ *
+ * @param client The connected misagent to use for installation
+ * @param profile The valid provisioning profile to install. This has to be
+ * passed as a PLIST_DATA, otherwise the function will fail.
+ *
+ * @return MISAGENT_E_SUCCESS on success, MISAGENT_E_INVALID_ARG when
+ * client is invalid, or an MISAGENT_E_* error code otherwise.
+ */
misagent_error_t misagent_install(misagent_client_t client, plist_t profile);
+
+/**
+ * Retrieves an array of all installed provisioning profiles.
+ *
+ * @param client The connected misagent to use.
+ * @param profiles Pointer to a plist_t that will be set to a PLIST_ARRAY
+ * if the function is successful.
+ *
+ * @return MISAGENT_E_SUCCESS on success, MISAGENT_E_INVALID_ARG when
+ * client is invalid, or an MISAGENT_E_* error code otherwise.
+ *
+ * @note If no provisioning profiles are installed on the device, this function
+ * still returns MISAGENT_E_SUCCESS and profiles will just point to an
+ * empty array.
+ */
misagent_error_t misagent_copy(misagent_client_t client, plist_t* profiles);
+
+/**
+ * Removes a given provisioning profile.
+ *
+ * @param client The connected misagent to use.
+ * @param profileID Identifier of the provisioning profile to remove.
+ * This is a UUID that can be obtained from the provisioning profile data.
+ * @see misagent_copy
+ *
+ * @return MISAGENT_E_SUCCESS on success, MISAGENT_E_INVALID_ARG when
+ * client is invalid, or an MISAGENT_E_* error code otherwise.
+ */
misagent_error_t misagent_remove(misagent_client_t client, const char* profileID);
+
+/**
+ * Retrieves the status code from the last operation.
+ *
+ * @param client The misagent to use.
+ *
+ * @return -1 if client is invalid, or the status code from the last operation
+ */
int misagent_get_status_code(misagent_client_t client);
#ifdef __cplusplus
diff --git a/include/libimobiledevice/mobile_image_mounter.h b/include/libimobiledevice/mobile_image_mounter.h
index 560fec6..569b288 100644
--- a/include/libimobiledevice/mobile_image_mounter.h
+++ b/include/libimobiledevice/mobile_image_mounter.h
@@ -53,13 +53,113 @@ typedef mobile_image_mounter_client_private *mobile_image_mounter_client_t; /**<
typedef ssize_t (*mobile_image_mounter_upload_cb_t) (void* buffer, size_t length, void *user_data);
/* Interface */
+
+/**
+ * Connects to the mobile_image_mounter 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 be set to a newly allocated
+ * mobile_image_mounter_client_t upon successful return.
+ *
+ * @return MOBILE_IMAGE_MOUNTER_E_SUCCESS on success,
+ * MOBILE_IMAGE_MOUNTER_E_INVALID_ARG if device is NULL,
+ * or MOBILE_IMAGE_MOUNTER_E_CONN_FAILED if the connection to the
+ * device could not be established.
+ */
mobile_image_mounter_error_t mobile_image_mounter_new(idevice_t device, lockdownd_service_descriptor_t service, mobile_image_mounter_client_t *client);
+
+/**
+ * Starts a new mobile_image_mounter 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
+ * mobile_image_mounter_t upon successful return. Must be freed using
+ * mobile_image_mounter_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 MOBILE_IMAGE_MOUNTER_E_SUCCESS on success, or an MOBILE_IMAGE_MOUNTER_E_* error
+ * code otherwise.
+ */
mobile_image_mounter_error_t mobile_image_mounter_start_service(idevice_t device, mobile_image_mounter_client_t* client, const char* label);
+
+/**
+ * Disconnects a mobile_image_mounter client from the device and frees up the
+ * mobile_image_mounter client data.
+ *
+ * @param client The mobile_image_mounter client to disconnect and free.
+ *
+ * @return MOBILE_IMAGE_MOUNTER_E_SUCCESS on success,
+ * or MOBILE_IMAGE_MOUNTER_E_INVALID_ARG if client is NULL.
+ */
mobile_image_mounter_error_t mobile_image_mounter_free(mobile_image_mounter_client_t client);
+
+/**
+ * Tells if the image of ImageType is already mounted.
+ *
+ * @param client The client use
+ * @param image_type The type of the image to look up
+ * @param result Pointer to a plist that will receive the result of the
+ * operation.
+ *
+ * @note This function may return MOBILE_IMAGE_MOUNTER_E_SUCCESS even if the
+ * operation has failed. Check the resulting plist for further information.
+ *
+ * @return MOBILE_IMAGE_MOUNTER_E_SUCCESS on success, or an error code on error
+ */
mobile_image_mounter_error_t mobile_image_mounter_lookup_image(mobile_image_mounter_client_t client, const char *image_type, plist_t *result);
+
+/**
+ * Uploads an image to the device.
+ *
+ * @param client The connected mobile_image_mounter client.
+ * @param image_type Type of image that is being uploaded.
+ * @param image_size Total size of the image.
+ * @param upload_cb Callback function that gets the data chunks for uploading
+ * the image.
+ * @param userdata User defined data for the upload callback function.
+ *
+ * @return MOBILE_IMAGE_MOUNTER_E_SUCCESS on succes, or a
+ * MOBILE_IMAGE_MOUNTER_E_* error code otherwise.
+ */
mobile_image_mounter_error_t mobile_image_mounter_upload_image(mobile_image_mounter_client_t client, const char *image_type, size_t image_size, mobile_image_mounter_upload_cb_t upload_cb, void* userdata);
+
+/**
+ * Mounts an image on the device.
+ *
+ * @param client The connected mobile_image_mounter client.
+ * @param image_path The absolute path of the image to mount. The image must
+ * be present before calling this function.
+ * @param image_signature Pointer to a buffer holding the images' signature
+ * @param signature_length Length of the signature image_signature points to
+ * @param image_type Type of image to mount
+ * @param result Pointer to a plist that will receive the result of the
+ * operation.
+ *
+ * @note This function may return MOBILE_IMAGE_MOUNTER_E_SUCCESS even if the
+ * operation has failed. Check the resulting plist for further information.
+ * Note that there is no unmounting function. The mount persists until the
+ * device is rebooted.
+ *
+ * @return MOBILE_IMAGE_MOUNTER_E_SUCCESS on success,
+ * MOBILE_IMAGE_MOUNTER_E_INVALID_ARG if on ore more parameters are
+ * invalid, or another error code otherwise.
+ */
mobile_image_mounter_error_t mobile_image_mounter_mount_image(mobile_image_mounter_client_t client, const char *image_path, const char *image_signature, uint16_t signature_length, const char *image_type, plist_t *result);
+
+/**
+ * Hangs up the connection to the mobile_image_mounter service.
+ * This functions has to be called before freeing up a mobile_image_mounter
+ * instance. If not, errors appear in the device's syslog.
+ *
+ * @param client The client to hang up
+ *
+ * @return MOBILE_IMAGE_MOUNTER_E_SUCCESS on success,
+ * MOBILE_IMAGE_MOUNTER_E_INVALID_ARG if client is invalid,
+ * or another error code otherwise.
+ */
mobile_image_mounter_error_t mobile_image_mounter_hangup(mobile_image_mounter_client_t client);
#ifdef __cplusplus
diff --git a/include/libimobiledevice/mobilebackup.h b/include/libimobiledevice/mobilebackup.h
index c62e99e..c07ba68 100644
--- a/include/libimobiledevice/mobilebackup.h
+++ b/include/libimobiledevice/mobilebackup.h
@@ -56,18 +56,187 @@ typedef enum {
MB_RESTORE_PRESERVE_CAMERA_ROLL = 1 << 2
} mobilebackup_flags_t;
+
+/**
+ * Connects to the mobilebackup 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 be set to a newly allocated
+ * mobilebackup_client_t upon successful return.
+ *
+ * @return MOBILEBACKUP_E_SUCCESS on success, MOBILEBACKUP_E_INVALID ARG if one
+ * or more parameters are invalid, or DEVICE_LINK_SERVICE_E_BAD_VERSION if
+ * the mobilebackup version on the device is newer.
+ */
mobilebackup_error_t mobilebackup_client_new(idevice_t device, lockdownd_service_descriptor_t service, mobilebackup_client_t * client);
+
+/**
+ * Starts a new mobilebackup 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
+ * mobilebackup_client_t upon successful return. Must be freed using
+ * mobilebackup_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 MOBILEBACKUP_E_SUCCESS on success, or an MOBILEBACKUP_E_* error
+ * code otherwise.
+ */
mobilebackup_error_t mobilebackup_client_start_service(idevice_t device, mobilebackup_client_t* client, const char* label);
+
+/**
+ * Disconnects a mobilebackup client from the device and frees up the
+ * mobilebackup client data.
+ *
+ * @param client The mobilebackup client to disconnect and free.
+ *
+ * @return MOBILEBACKUP_E_SUCCESS on success, or MOBILEBACKUP_E_INVALID_ARG
+ * if client is NULL.
+ */
mobilebackup_error_t mobilebackup_client_free(mobilebackup_client_t client);
+
+/**
+ * Polls the device for mobilebackup data.
+ *
+ * @param client The mobilebackup client
+ * @param plist A pointer to the location where the plist should be stored
+ *
+ * @return an error code
+ */
mobilebackup_error_t mobilebackup_receive(mobilebackup_client_t client, plist_t *plist);
+
+/**
+ * Sends mobilebackup data to the device
+ *
+ * @note This function is low-level and should only be used if you need to send
+ * a new type of message.
+ *
+ * @param client The mobilebackup client
+ * @param plist The location of the plist to send
+ *
+ * @return an error code
+ */
mobilebackup_error_t mobilebackup_send(mobilebackup_client_t client, plist_t plist);
+
+/**
+ * Request a backup from the connected device.
+ *
+ * @param client The connected MobileBackup client to use.
+ * @param backup_manifest The backup manifest, a plist_t of type PLIST_DICT
+ * containing the backup state of the last backup. For a first-time backup
+ * set this parameter to NULL.
+ * @param base_path The base path on the device to use for the backup
+ * operation, usually "/".
+ * @param proto_version A string denoting the version of the backup protocol
+ * to use. Latest known version is "1.6"
+ *
+ * @return MOBILEBACKUP_E_SUCCESS on success, MOBILEBACKUP_E_INVALID_ARG if
+ * one of the parameters is invalid, MOBILEBACKUP_E_PLIST_ERROR if
+ * backup_manifest is not of type PLIST_DICT, MOBILEBACKUP_E_MUX_ERROR
+ * if a communication error occurs, MOBILEBACKUP_E_REPLY_NOT_OK
+ */
mobilebackup_error_t mobilebackup_request_backup(mobilebackup_client_t client, plist_t backup_manifest, const char *base_path, const char *proto_version);
+
+/**
+ * Sends a confirmation to the device that a backup file has been received.
+ *
+ * @param client The connected MobileBackup client to use.
+ *
+ * @return MOBILEBACKUP_E_SUCCESS on success, MOBILEBACKUP_E_INVALID_ARG if
+ * client is invalid, or MOBILEBACKUP_E_MUX_ERROR if a communication error
+ * occurs.
+ */
mobilebackup_error_t mobilebackup_send_backup_file_received(mobilebackup_client_t client);
+
+/**
+ * Request that a backup should be restored to the connected device.
+ *
+ * @param client The connected MobileBackup client to use.
+ * @param backup_manifest The backup manifest, a plist_t of type PLIST_DICT
+ * containing the backup state to be restored.
+ * @param flags Flags to send with the request. Currently this is a combination
+ * of the following mobilebackup_flags_t:
+ * MB_RESTORE_NOTIFY_SPRINGBOARD - let SpringBoard show a 'Restore' screen
+ * MB_RESTORE_PRESERVE_SETTINGS - do not overwrite any settings
+ * MB_RESTORE_PRESERVE_CAMERA_ROLL - preserve the photos of the camera roll
+ * @param proto_version A string denoting the version of the backup protocol
+ * to use. Latest known version is "1.6". Ideally this value should be
+ * extracted from the given manifest plist.
+ *
+ * @return MOBILEBACKUP_E_SUCCESS on success, MOBILEBACKUP_E_INVALID_ARG if
+ * one of the parameters is invalid, MOBILEBACKUP_E_PLIST_ERROR if
+ * backup_manifest is not of type PLIST_DICT, MOBILEBACKUP_E_MUX_ERROR
+ * if a communication error occurs, or MOBILEBACKUP_E_REPLY_NOT_OK
+ * if the device did not accept the request.
+ */
mobilebackup_error_t mobilebackup_request_restore(mobilebackup_client_t client, plist_t backup_manifest, mobilebackup_flags_t flags, const char *proto_version);
+
+/**
+ * Receive a confirmation from the device that it successfully received
+ * a restore file.
+ *
+ * @param client The connected MobileBackup client to use.
+ * @param result Pointer to a plist_t that will be set to the received plist
+ * for further processing. The caller has to free it using plist_free().
+ * Note that it will be set to NULL if the operation itself fails due to
+ * a communication or plist error.
+ * If this parameter is NULL, it will be ignored.
+ *
+ * @return MOBILEBACKUP_E_SUCCESS on success, MOBILEBACKUP_E_INVALID_ARG if
+ * client is invalid, MOBILEBACKUP_E_REPLY_NOT_OK if the expected
+ * 'BackupMessageRestoreFileReceived' message could not be received,
+ * MOBILEBACKUP_E_PLIST_ERROR if the received message is not a valid backup
+ * message plist, or MOBILEBACKUP_E_MUX_ERROR if a communication error
+ * occurs.
+ */
mobilebackup_error_t mobilebackup_receive_restore_file_received(mobilebackup_client_t client, plist_t *result);
+
+/**
+ * Receive a confirmation from the device that it successfully received
+ * application data file.
+ *
+ * @param client The connected MobileBackup client to use.
+ * @param result Pointer to a plist_t that will be set to the received plist
+ * for further processing. The caller has to free it using plist_free().
+ * Note that it will be set to NULL if the operation itself fails due to
+ * a communication or plist error.
+ * If this parameter is NULL, it will be ignored.
+ *
+ * @return MOBILEBACKUP_E_SUCCESS on success, MOBILEBACKUP_E_INVALID_ARG if
+ * client is invalid, MOBILEBACKUP_E_REPLY_NOT_OK if the expected
+ * 'BackupMessageRestoreApplicationReceived' message could not be received,
+ * MOBILEBACKUP_E_PLIST_ERROR if the received message is not a valid backup
+ * message plist, or MOBILEBACKUP_E_MUX_ERROR if a communication error
+ * occurs.
+ */
mobilebackup_error_t mobilebackup_receive_restore_application_received(mobilebackup_client_t client, plist_t *result);
+
+/**
+ * Tells the device that the restore process is complete and waits for the
+ * device to close the connection. After that, the device should reboot.
+ *
+ * @param client The connected MobileBackup client to use.
+ *
+ * @return MOBILEBACKUP_E_SUCCESS on success, MOBILEBACKUP_E_INVALID_ARG if
+ * client is invalid, MOBILEBACKUP_E_PLIST_ERROR if the received disconnect
+ * message plist is invalid, or MOBILEBACKUP_E_MUX_ERROR if a communication
+ * error occurs.
+ */
mobilebackup_error_t mobilebackup_send_restore_complete(mobilebackup_client_t client);
+
+/**
+ * Sends a backup error message to the device.
+ *
+ * @param client The connected MobileBackup client to use.
+ * @param reason A string describing the reason for the error message.
+ *
+ * @return MOBILEBACKUP_E_SUCCESS on success, MOBILEBACKUP_E_INVALID_ARG if
+ * one of the parameters is invalid, or MOBILEBACKUP_E_MUX_ERROR if a
+ * communication error occurs.
+ */
mobilebackup_error_t mobilebackup_send_error(mobilebackup_client_t client, const char *reason);
#ifdef __cplusplus
diff --git a/include/libimobiledevice/mobilebackup2.h b/include/libimobiledevice/mobilebackup2.h
index 65bbfc7..ad1dcea 100644
--- a/include/libimobiledevice/mobilebackup2.h
+++ b/include/libimobiledevice/mobilebackup2.h
@@ -51,16 +51,160 @@ typedef int16_t mobilebackup2_error_t;
typedef struct mobilebackup2_client_private mobilebackup2_client_private;
typedef mobilebackup2_client_private *mobilebackup2_client_t; /**< The client handle. */
+
+/**
+ * Connects to the mobilebackup2 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 be set to a newly allocated
+ * mobilebackup2_client_t upon successful return.
+ *
+ * @return MOBILEBACKUP2_E_SUCCESS on success, MOBILEBACKUP2_E_INVALID ARG
+ * if one or more parameter is invalid, or MOBILEBACKUP2_E_BAD_VERSION
+ * if the mobilebackup2 version on the device is newer.
+ */
mobilebackup2_error_t mobilebackup2_client_new(idevice_t device, lockdownd_service_descriptor_t service, mobilebackup2_client_t * client);
+
+/**
+ * Starts a new mobilebackup2 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
+ * mobilebackup2_client_t upon successful return. Must be freed using
+ * mobilebackup2_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 MOBILEBACKUP2_E_SUCCESS on success, or an MOBILEBACKUP2_E_* error
+ * code otherwise.
+ */
mobilebackup2_error_t mobilebackup2_client_start_service(idevice_t device, mobilebackup2_client_t* client, const char* label);
+
+/**
+ * Disconnects a mobilebackup2 client from the device and frees up the
+ * mobilebackup2 client data.
+ *
+ * @param client The mobilebackup2 client to disconnect and free.
+ *
+ * @return MOBILEBACKUP2_E_SUCCESS on success, or MOBILEBACKUP2_E_INVALID_ARG
+ * if client is NULL.
+ */
mobilebackup2_error_t mobilebackup2_client_free(mobilebackup2_client_t client);
+
+/**
+ * Sends a backup message plist.
+ *
+ * @param client The connected MobileBackup client to use.
+ * @param message The message to send. This will be inserted into the request
+ * plist as value for MessageName. If this parameter is NULL,
+ * the plist passed in the options parameter will be sent directly.
+ * @param options Additional options as PLIST_DICT to add to the request.
+ * The MessageName key with the value passed in the message parameter
+ * will be inserted into this plist before sending it. This parameter
+ * can be NULL if message is not NULL.
+ */
mobilebackup2_error_t mobilebackup2_send_message(mobilebackup2_client_t client, const char *message, plist_t options);
+
+/**
+ * Receives a DL* message plist from the device.
+ * This function is a wrapper around device_link_service_receive_message.
+ *
+ * @param client The connected MobileBackup client to use.
+ * @param msg_plist Pointer to a plist that will be set to the contents of the
+ * message plist upon successful return.
+ * @param dlmessage A pointer that will be set to a newly allocated char*
+ * containing the DL* string from the given plist. It is up to the caller
+ * to free the allocated memory. If this parameter is NULL
+ * it will be ignored.
+ *
+ * @return MOBILEBACKUP2_E_SUCCESS if a DL* message was received,
+ * MOBILEBACKUP2_E_INVALID_ARG if client or message is invalid,
+ * MOBILEBACKUP2_E_PLIST_ERROR if the received plist is invalid
+ * or is not a DL* message plist, or MOBILEBACKUP2_E_MUX_ERROR if
+ * receiving from the device failed.
+ */
mobilebackup2_error_t mobilebackup2_receive_message(mobilebackup2_client_t client, plist_t *msg_plist, char **dlmessage);
+
+/**
+ * Send binary data to the device.
+ *
+ * @note This function returns MOBILEBACKUP2_E_SUCCESS even if less than the
+ * requested length has been sent. The fourth parameter is required and
+ * must be checked to ensure if the whole data has been sent.
+ *
+ * @param client The MobileBackup client to send to.
+ * @param data Pointer to the data to send
+ * @param length Number of bytes to send
+ * @param bytes Number of bytes actually sent
+ *
+ * @return MOBILEBACKUP2_E_SUCCESS if any data was successfully sent,
+ * MOBILEBACKUP2_E_INVALID_ARG if one of the parameters is invalid,
+ * or MOBILEBACKUP2_E_MUX_ERROR if sending of the data failed.
+ */
mobilebackup2_error_t mobilebackup2_send_raw(mobilebackup2_client_t client, const char *data, uint32_t length, uint32_t *bytes);
+
+/**
+ * Receive binary from the device.
+ *
+ * @note This function returns MOBILEBACKUP2_E_SUCCESS even if no data
+ * has been received (unless a communication error occured).
+ * The fourth parameter is required and must be checked to know how
+ * many bytes were actually received.
+ *
+ * @param client The MobileBackup client to receive from.
+ * @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.
+ *
+ * @return MOBILEBACKUP2_E_SUCCESS if any or no data was received,
+ * MOBILEBACKUP2_E_INVALID_ARG if one of the parameters is invalid,
+ * or MOBILEBACKUP2_E_MUX_ERROR if receiving the data failed.
+ */
mobilebackup2_error_t mobilebackup2_receive_raw(mobilebackup2_client_t client, char *data, uint32_t length, uint32_t *bytes);
+
+/**
+ * Performs the mobilebackup2 protocol version exchange.
+ *
+ * @param client The MobileBackup client to use.
+ * @param local_versions An array of supported versions to send to the remote.
+ * @param count The number of items in local_versions.
+ * @param remote_version Holds the protocol version of the remote on success.
+ *
+ * @return MOBILEBACKUP2_E_SUCCESS on success, or a MOBILEBACKUP2_E_* error
+ * code otherwise.
+ */
mobilebackup2_error_t mobilebackup2_version_exchange(mobilebackup2_client_t client, double local_versions[], char count, double *remote_version);
+
+/**
+ * Send a request to the connected mobilebackup2 service.
+ *
+ * @param client
+ * @param request The request to send to the backup service.
+ * Currently, this is one of "Backup", "Restore", "Info", or "List".
+ * @param target_identifier UDID of the target device.
+ * @param source_identifier UDID of backup data?
+ * @param options Additional options in a plist of type PLIST_DICT.
+ *
+ * @return MOBILEBACKUP2_E_SUCCESS if the request was successfully sent,
+ * or a MOBILEBACKUP2_E_* error value otherwise.
+ */
mobilebackup2_error_t mobilebackup2_send_request(mobilebackup2_client_t client, const char *request, const char *target_identifier, const char *source_identifier, plist_t options);
+
+/**
+ * Sends a DLMessageStatusResponse to the device.
+ *
+ * @param client The MobileBackup client to use.
+ * @param status_code The status code to send.
+ * @param status1 A status message to send. Can be NULL if not required.
+ * @param status2 An additional status plist to attach to the response.
+ * Can be NULL if not required.
+ *
+ * @return MOBILEBACKUP2_E_SUCCESS on success, MOBILEBACKUP2_E_INVALID_ARG
+ * if client is invalid, or another MOBILEBACKUP2_E_* otherwise.
+ */
mobilebackup2_error_t mobilebackup2_send_status_response(mobilebackup2_client_t client, int status_code, const char *status1, plist_t status2);
#ifdef __cplusplus
diff --git a/include/libimobiledevice/mobilesync.h b/include/libimobiledevice/mobilesync.h
index 8e263ce..6ba197b 100644
--- a/include/libimobiledevice/mobilesync.h
+++ b/include/libimobiledevice/mobilesync.h
@@ -68,35 +68,284 @@ typedef struct {
typedef mobilesync_anchors *mobilesync_anchors_t; /**< Anchors used by the device and computer. */
/* Interface */
+
+/**
+ * Connects to the mobilesync 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 be set to a newly allocated
+ * #mobilesync_client_t upon successful return.
+ *
+ * @retval MOBILESYNC_E_SUCCESS on success
+ * @retval MOBILESYNC_E_INVALID_ARG if one or more parameters are invalid
+ * @retval DEVICE_LINK_SERVICE_E_BAD_VERSION if the mobilesync version on
+ * the device is newer.
+ */
mobilesync_error_t mobilesync_client_new(idevice_t device, lockdownd_service_descriptor_t service, mobilesync_client_t * client);
+
+/**
+ * Starts a new mobilesync 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
+ * mobilesync_client_t upon successful return. Must be freed using
+ * mobilesync_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 MOBILESYNC_E_SUCCESS on success, or an MOBILESYNC_E_* error
+ * code otherwise.
+ */
mobilesync_error_t mobilesync_client_start_service(idevice_t device, mobilesync_client_t* client, const char* label);
+
+/**
+ * Disconnects a mobilesync client from the device and frees up the
+ * mobilesync client data.
+ *
+ * @param client The mobilesync client to disconnect and free.
+ *
+ * @retval MOBILESYNC_E_SUCCESS on success
+ * @retval MOBILESYNC_E_INVALID_ARG if \a client is NULL.
+ */
mobilesync_error_t mobilesync_client_free(mobilesync_client_t client);
+
+/**
+ * Polls the device for mobilesync data.
+ *
+ * @param client The mobilesync client
+ * @param plist A pointer to the location where the plist should be stored
+ *
+ * @return an error code
+ */
mobilesync_error_t mobilesync_receive(mobilesync_client_t client, plist_t *plist);
+
+/**
+ * Sends mobilesync data to the device
+ *
+ * @note This function is low-level and should only be used if you need to send
+ * a new type of message.
+ *
+ * @param client The mobilesync client
+ * @param plist The location of the plist to send
+ *
+ * @return an error code
+ */
mobilesync_error_t mobilesync_send(mobilesync_client_t client, plist_t plist);
+
+/**
+ * Requests starting synchronization of a data class with the device
+ *
+ * @param client The mobilesync client
+ * @param data_class The data class identifier to sync
+ * @param anchors The anchors required to exchange with the device. The anchors
+ * allow the device to tell if the synchronization information on the computer
+ * and device are consistent to determine what sync type is required.
+ * @param computer_data_class_version The version of the data class storage on the computer
+ * @param sync_type A pointer to store the sync type reported by the device_anchor
+ * @param device_data_class_version The version of the data class storage on the device
+ * @param error_description A pointer to store an error message if reported by the device
+ *
+ * @retval MOBILESYNC_E_SUCCESS on success
+ * @retval MOBILESYNC_E_INVALID_ARG if one of the parameters is invalid
+ * @retval MOBILESYNC_E_PLIST_ERROR if the received plist is not of valid form
+ * @retval MOBILESYNC_E_SYNC_REFUSED if the device refused to sync
+ * @retval MOBILESYNC_E_CANCELLED if the device explicitly cancelled the
+ * sync request
+ */
mobilesync_error_t mobilesync_start(mobilesync_client_t client, const char *data_class, mobilesync_anchors_t anchors, uint64_t computer_data_class_version, mobilesync_sync_type_t *sync_type, uint64_t *device_data_class_version, char** error_description);
+
+/**
+ * Cancels a running synchronization session with a device at any time.
+ *
+ * @param client The mobilesync client
+ * @param reason The reason to supply to the device for cancelling
+ *
+ * @retval MOBILESYNC_E_SUCCESS on success
+ * @retval MOBILESYNC_E_INVALID_ARG if one of the parameters is invalid
+ */
mobilesync_error_t mobilesync_cancel(mobilesync_client_t client, const char* reason);
+
+/**
+ * Finish a synchronization session of a data class on the device.
+ * A session must have previously been started using mobilesync_start().
+ *
+ * @param client The mobilesync client
+ *
+ * @retval MOBILESYNC_E_SUCCESS on success
+ * @retval MOBILESYNC_E_INVALID_ARG if one of the parameters is invalid
+ * @retval MOBILESYNC_E_PLIST_ERROR if the received plist is not of valid
+ * form
+ */
mobilesync_error_t mobilesync_finish(mobilesync_client_t client);
+
+/**
+ * Requests to receive all records of the currently set data class from the device.
+ * The actually changes are retrieved using mobilesync_receive_changes() after this
+ * request has been successful.
+ *
+ * @param client The mobilesync client
+ *
+ * @retval MOBILESYNC_E_SUCCESS on success
+ * @retval MOBILESYNC_E_INVALID_ARG if one of the parameters is invalid
+ */
mobilesync_error_t mobilesync_get_all_records_from_device(mobilesync_client_t client);
+
+/**
+ * Requests to receive only changed records of the currently set data class from the device.
+ * The actually changes are retrieved using mobilesync_receive_changes() after this
+ * request has been successful.
+ *
+ * @param client The mobilesync client
+ *
+ * @retval MOBILESYNC_E_SUCCESS on success
+ * @retval MOBILESYNC_E_INVALID_ARG if one of the parameters is invalid
+ */
mobilesync_error_t mobilesync_get_changes_from_device(mobilesync_client_t client);
+
+/**
+ * Requests the device to delete all records of the current data class
+ *
+ * @note The operation must be called after starting synchronization.
+ *
+ * @param client The mobilesync client
+ *
+ * @retval MOBILESYNC_E_SUCCESS on success
+ * @retval MOBILESYNC_E_INVALID_ARG if one of the parameters is invalid
+ * @retval MOBILESYNC_E_PLIST_ERROR if the received plist is not of valid form
+ */
mobilesync_error_t mobilesync_clear_all_records_on_device(mobilesync_client_t client);
+
+/**
+ * Receives changed entitites of the currently set data class from the device
+ *
+ * @param client The mobilesync client
+ * @param entities A pointer to store the changed entity records as a PLIST_DICT
+ * @param is_last_record A pointer to store a flag indicating if this submission is the last one
+ * @param actions A pointer to additional flags the device is sending or NULL to ignore
+ *
+ * @retval MOBILESYNC_E_SUCCESS on success
+ * @retval MOBILESYNC_E_INVALID_ARG if one of the parameters is invalid
+ * @retval MOBILESYNC_E_CANCELLED if the device explicitly cancelled the
+ * session
+ */
mobilesync_error_t mobilesync_receive_changes(mobilesync_client_t client, plist_t *entities, uint8_t *is_last_record, plist_t *actions);
+
+/**
+ * Acknowledges to the device that the changes have been merged on the computer
+ *
+ * @param client The mobilesync client
+ *
+ * @retval MOBILESYNC_E_SUCCESS on success
+ * @retval MOBILESYNC_E_INVALID_ARG if one of the parameters is invalid
+ */
mobilesync_error_t mobilesync_acknowledge_changes_from_device(mobilesync_client_t client);
+
+/**
+ * Verifies if the device is ready to receive changes from the computer.
+ * This call changes the synchronization direction so that mobilesync_send_changes()
+ * can be used to send changes to the device.
+ *
+ * @param client The mobilesync client
+ *
+ * @retval MOBILESYNC_E_SUCCESS on success
+ * @retval MOBILESYNC_E_INVALID_ARG if one of the parameters is invalid
+ * @retval MOBILESYNC_E_PLIST_ERROR if the received plist is not of valid form
+ * @retval MOBILESYNC_E_WRONG_DIRECTION if the current sync direction does
+ * not permit this call
+ * @retval MOBILESYNC_E_CANCELLED if the device explicitly cancelled the
+ * session
+ * @retval MOBILESYNC_E_NOT_READY if the device is not ready to start
+ * receiving any changes
+ */
mobilesync_error_t mobilesync_ready_to_send_changes_from_computer(mobilesync_client_t client);
+
+/**
+ * Sends changed entities of the currently set data class to the device
+ *
+ * @param client The mobilesync client
+ * @param entities The changed entity records as a PLIST_DICT
+ * @param is_last_record A flag indicating if this submission is the last one
+ * @param actions Additional actions for the device created with mobilesync_actions_new()
+ * or NULL if no actions should be passed
+ *
+ * @retval MOBILESYNC_E_SUCCESS on success
+ * @retval MOBILESYNC_E_INVALID_ARG if one of the parameters is invalid,
+ * @retval MOBILESYNC_E_WRONG_DIRECTION if the current sync direction does
+ * not permit this call
+ */
mobilesync_error_t mobilesync_send_changes(mobilesync_client_t client, plist_t entities, uint8_t is_last_record, plist_t actions);
+
+/**
+ * Receives any remapped identifiers reported after the device merged submitted changes.
+ *
+ * @param client The mobilesync client
+ * @param mapping A pointer to an array plist containing a dict of identifier remappings
+ *
+ * @retval MOBILESYNC_E_SUCCESS on success
+ * @retval MOBILESYNC_E_INVALID_ARG if one of the parameters is invalid
+ * @retval MOBILESYNC_E_PLIST_ERROR if the received plist is not of valid
+ * form
+ * @retval MOBILESYNC_E_WRONG_DIRECTION if the current sync direction does
+ * not permit this call
+ * @retval MOBILESYNC_E_CANCELLED if the device explicitly cancelled the
+ * session
+ */
mobilesync_error_t mobilesync_remap_identifiers(mobilesync_client_t client, plist_t *mapping);
/* Helper */
+
+/**
+ * Allocates memory for a new anchors struct initialized with the passed anchors.
+ *
+ * @param device_anchor An anchor the device reported the last time or NULL
+ * if none is known yet which for instance is true on first synchronization.
+ * @param computer_anchor An arbitrary string to use as anchor for the computer.
+ *
+ * @return A new #mobilesync_anchors_t struct. Must be freed using mobilesync_anchors_free().
+ */
mobilesync_anchors_t mobilesync_anchors_new(const char *device_anchor, const char *computer_anchor);
+
+/**
+ * Free memory used by anchors.
+ *
+ * @param anchors The anchors to free.
+ */
void mobilesync_anchors_free(mobilesync_anchors_t anchors);
+
+/**
+ * Create a new actions plist to use in mobilesync_send_changes().
+ *
+ * @return A new plist_t of type PLIST_DICT.
+ */
plist_t mobilesync_actions_new();
+
+/**
+ * Add one or more new key:value pairs to the given actions plist.
+ *
+ * @param actions The actions to modify.
+ * @param ... KEY, VALUE, [KEY, VALUE], NULL
+ *
+ * @note The known keys so far are "SyncDeviceLinkEntityNamesKey" which expects
+ * an array of entity names, followed by a count paramter as well as
+ * "SyncDeviceLinkAllRecordsOfPulledEntityTypeSentKey" which expects an
+ * integer to use as a boolean value indicating that the device should
+ * link submitted changes and report remapped identifiers.
+ */
void mobilesync_actions_add(plist_t actions, ...);
+
+/**
+ * Free actions plist.
+ *
+ * @param actions The actions plist to free. Does nothing if NULL is passed.
+ */
void mobilesync_actions_free(plist_t actions);
#ifdef __cplusplus
diff --git a/include/libimobiledevice/notification_proxy.h b/include/libimobiledevice/notification_proxy.h
index 4f025ee..a66057b 100644
--- a/include/libimobiledevice/notification_proxy.h
+++ b/include/libimobiledevice/notification_proxy.h
@@ -93,13 +93,103 @@ typedef np_client_private *np_client_t; /**< The client handle. */
typedef void (*np_notify_cb_t) (const char *notification, void *user_data);
/* Interface */
+
+/**
+ * Connects to the notification_proxy 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 be set to a newly allocated np_client_t
+ * upon successful return.
+ *
+ * @return NP_E_SUCCESS on success, NP_E_INVALID_ARG when device is NULL,
+ * or NP_E_CONN_FAILED when the connection to the device could not be
+ * established.
+ */
np_error_t np_client_new(idevice_t device, lockdownd_service_descriptor_t service, np_client_t *client);
+
+/**
+ * Starts a new notification proxy 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
+ * np_client_t upon successful return. Must be freed using
+ * np_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 NP_E_SUCCESS on success, or an NP_E_* error
+ * code otherwise.
+ */
np_error_t np_client_start_service(idevice_t device, np_client_t* client, const char* label);
+
+/**
+ * Disconnects a notification_proxy client from the device and frees up the
+ * notification_proxy client data.
+ *
+ * @param client The notification_proxy client to disconnect and free.
+ *
+ * @return NP_E_SUCCESS on success, or NP_E_INVALID_ARG when client is NULL.
+ */
np_error_t np_client_free(np_client_t client);
+
+/**
+ * Sends a notification to the device's notification_proxy.
+ *
+ * @param client The client to send to
+ * @param notification The notification message to send
+ *
+ * @return NP_E_SUCCESS on success, or an error returned by np_plist_send
+ */
np_error_t np_post_notification(np_client_t client, const char *notification);
+
+/**
+ * Tells the device to send a notification on the specified event.
+ *
+ * @param client The client to send to
+ * @param notification The notifications that should be observed.
+ *
+ * @return NP_E_SUCCESS on success, NP_E_INVALID_ARG when client or
+ * notification are NULL, or an error returned by np_plist_send.
+ */
np_error_t np_observe_notification(np_client_t client, const char *notification);
+
+/**
+ * Tells the device to send a notification on specified events.
+ *
+ * @param client The client to send to
+ * @param notification_spec Specification of the notifications that should be
+ * observed. This is expected to be an array of const char* that MUST have a
+ * terminating NULL entry.
+ *
+ * @return NP_E_SUCCESS on success, NP_E_INVALID_ARG when client is null,
+ * or an error returned by np_observe_notification.
+ */
np_error_t np_observe_notifications(np_client_t client, const char **notification_spec);
+
+/**
+ * This function allows an application to define a callback function that will
+ * be called when a notification has been received.
+ * It will start a thread that polls for notifications and calls the callback
+ * function if a notification has been received.
+ * In case of an error condition when polling for notifications - e.g. device
+ * disconnect - the thread will call the callback function with an empty
+ * notification "" and terminate itself.
+ *
+ * @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
+ * user data. If notify_cb is NULL, this parameter is ignored.
+ *
+ * @note Only one callback function can be registered at the same time;
+ * any previously set callback function will be removed automatically.
+ *
+ * @return NP_E_SUCCESS when the callback was successfully registered,
+ * NP_E_INVALID_ARG when client is NULL, or NP_E_UNKNOWN_ERROR when
+ * the callback thread could no be created.
+ */
np_error_t np_set_notify_callback(np_client_t client, np_notify_cb_t notify_cb, void *userdata);
#ifdef __cplusplus
diff --git a/include/libimobiledevice/restore.h b/include/libimobiledevice/restore.h
index 584adb4..f4e8822 100644
--- a/include/libimobiledevice/restore.h
+++ b/include/libimobiledevice/restore.h
@@ -51,20 +51,130 @@ typedef struct restored_client_private restored_client_private;
typedef restored_client_private *restored_client_t; /**< The client handle. */
/* Interface */
+
+/**
+ * Creates a new restored client for the device.
+ *
+ * @param device The device to create a restored client for
+ * @param client The pointer to the location of the new restored_client
+ * @param label The label to use for communication. Usually the program name.
+ *
+ * @return RESTORE_E_SUCCESS on success, NP_E_INVALID_ARG when client is NULL
+ */
restored_error_t restored_client_new(idevice_t device, restored_client_t *client, const char *label);
+
+/**
+ * Closes the restored client session if one is running and frees up the
+ * restored_client struct.
+ *
+ * @param client The restore client
+ *
+ * @return RESTORE_E_SUCCESS on success, NP_E_INVALID_ARG when client is NULL
+ */
restored_error_t restored_client_free(restored_client_t client);
+
+/**
+ * Query the type of the service daemon. Depending on whether the device is
+ * queried in normal mode or restore mode, different types will be returned.
+ *
+ * @param client The restored client
+ * @param type The type returned by the service daemon. Pass NULL to ignore.
+ * @param version The restore protocol version. Pass NULL to ignore.
+ *
+ * @return RESTORE_E_SUCCESS on success, NP_E_INVALID_ARG when client is NULL
+ */
restored_error_t restored_query_type(restored_client_t client, char **type, uint64_t *version);
+
+/**
+ * Queries a value from the device specified by a key.
+ *
+ * @param client An initialized restored client.
+ * @param key The key name to request
+ * @param value A plist node representing the result value node
+ *
+ * @return RESTORE_E_SUCCESS on success, NP_E_INVALID_ARG when client is NULL, RESTORE_E_PLIST_ERROR if value for key can't be found
+ */
restored_error_t restored_query_value(restored_client_t client, const char *key, plist_t *value);
+
+/**
+ * Retrieves a value from information plist specified by a key.
+ *
+ * @param client An initialized restored client.
+ * @param key The key name to request or NULL to query for all keys
+ * @param value A plist node representing the result value node
+ *
+ * @return RESTORE_E_SUCCESS on success, NP_E_INVALID_ARG when client is NULL, RESTORE_E_PLIST_ERROR if value for key can't be found
+ */
restored_error_t restored_get_value(restored_client_t client, const char *key, plist_t *value) ;
+
+/**
+ * Sends a plist to restored.
+ *
+ * @note This function is low-level and should only be used if you need to send
+ * a new type of message.
+ *
+ * @param client The restored client
+ * @param plist The plist to send
+ *
+ * @return RESTORE_E_SUCCESS on success, NP_E_INVALID_ARG when client or
+ * plist is NULL
+ */
restored_error_t restored_send(restored_client_t client, plist_t plist);
+
+/**
+ * Receives a plist from restored.
+ *
+ * @param client The restored client
+ * @param plist The plist to store the received data
+ *
+ * @return RESTORE_E_SUCCESS on success, NP_E_INVALID_ARG when client or
+ * plist is NULL
+ */
restored_error_t restored_receive(restored_client_t client, plist_t *plist);
+
+/**
+ * Sends the Goodbye request to restored signaling the end of communication.
+ *
+ * @param client The restore client
+ *
+ * @return RESTORE_E_SUCCESS on success, NP_E_INVALID_ARG when client is NULL,
+ * RESTORE_E_PLIST_ERROR if the device did not acknowledge the request
+ */
restored_error_t restored_goodbye(restored_client_t client);
+
+/**
+ * Requests to start a restore and retrieve it's port on success.
+ *
+ * @param client The restored client
+ * @param options PLIST_DICT with options for the restore process or NULL
+ * @param version the restore protocol version, see restored_query_type()
+ *
+ * @return RESTORE_E_SUCCESS on success, NP_E_INVALID_ARG if a parameter
+ * is NULL, RESTORE_E_START_RESTORE_FAILED if the request fails
+ */
restored_error_t restored_start_restore(restored_client_t client, plist_t options, uint64_t version);
+
+/**
+ * Requests device to reboot.
+ *
+ * @param client The restored client
+ *
+ * @return RESTORE_E_SUCCESS on success, NP_E_INVALID_ARG if a parameter
+ * is NULL
+ */
restored_error_t restored_reboot(restored_client_t client);
/* Helper */
+
+/**
+ * Sets the label to send for requests to restored.
+ *
+ * @param client The restore client
+ * @param label The label to set or NULL to disable sending a label
+ *
+ */
void restored_client_set_label(restored_client_t client, const char *label);
#ifdef __cplusplus
diff --git a/include/libimobiledevice/sbservices.h b/include/libimobiledevice/sbservices.h
index f9d131b..f0bf2c4 100644
--- a/include/libimobiledevice/sbservices.h
+++ b/include/libimobiledevice/sbservices.h
@@ -60,14 +60,116 @@ typedef struct sbservices_client_private sbservices_client_private;
typedef sbservices_client_private *sbservices_client_t; /**< The client handle. */
/* Interface */
+
+/**
+ * Connects to the springboardservices 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
+ * sbservices_client_t upon successful return.
+ *
+ * @return SBSERVICES_E_SUCCESS on success, SBSERVICES_E_INVALID_ARG when
+ * client is NULL, or an SBSERVICES_E_* error code otherwise.
+ */
sbservices_error_t sbservices_client_new(idevice_t device, lockdownd_service_descriptor_t service, sbservices_client_t *client);
+
+/**
+ * Starts a new sbservices 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
+ * sbservices_client_t upon successful return. Must be freed using
+ * sbservices_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 SBSERVICES_E_SUCCESS on success, or an SBSERVICES_E_* error
+ * code otherwise.
+ */
sbservices_error_t sbservices_client_start_service(idevice_t device, sbservices_client_t* client, const char* label);
+
+/**
+ * Disconnects an sbservices client from the device and frees up the
+ * sbservices client data.
+ *
+ * @param client The sbservices client to disconnect and free.
+ *
+ * @return SBSERVICES_E_SUCCESS on success, SBSERVICES_E_INVALID_ARG when
+ * client is NULL, or an SBSERVICES_E_* error code otherwise.
+ */
sbservices_error_t sbservices_client_free(sbservices_client_t client);
+
+/**
+ * Gets the icon state of the connected device.
+ *
+ * @param client The connected sbservices client to use.
+ * @param state Pointer that will point to a newly allocated plist containing
+ * the current icon state. It is up to the caller to free the memory.
+ * @param format_version A string to be passed as formatVersion along with
+ * the request, or NULL if no formatVersion should be passed. This is only
+ * supported since iOS 4.0 so for older firmware versions this must be set
+ * to NULL.
+ *
+ * @return SBSERVICES_E_SUCCESS on success, SBSERVICES_E_INVALID_ARG when
+ * client or state is invalid, or an SBSERVICES_E_* error code otherwise.
+ */
sbservices_error_t sbservices_get_icon_state(sbservices_client_t client, plist_t *state, const char *format_version);
+
+/**
+ * Sets the icon state of the connected device.
+ *
+ * @param client The connected sbservices client to use.
+ * @param newstate A plist containing the new iconstate.
+ *
+ * @return SBSERVICES_E_SUCCESS on success, SBSERVICES_E_INVALID_ARG when
+ * client or newstate is NULL, or an SBSERVICES_E_* error code otherwise.
+ */
sbservices_error_t sbservices_set_icon_state(sbservices_client_t client, plist_t newstate);
+
+/**
+ * Get the icon of the specified app as PNG data.
+ *
+ * @param client The connected sbservices client to use.
+ * @param bundleId The bundle identifier of the app to retrieve the icon for.
+ * @param pngdata Pointer that will point to a newly allocated buffer
+ * containing the PNG data upon successful return. It is up to the caller
+ * to free the memory.
+ * @param pngsize Pointer to a uint64_t that will be set to the size of the
+ * buffer pngdata points to upon successful return.
+ *
+ * @return SBSERVICES_E_SUCCESS on success, SBSERVICES_E_INVALID_ARG when
+ * client, bundleId, or pngdata are invalid, or an SBSERVICES_E_* error
+ * code otherwise.
+ */
sbservices_error_t sbservices_get_icon_pngdata(sbservices_client_t client, const char *bundleId, char **pngdata, uint64_t *pngsize);
+
+/**
+ * Gets the interface orientation of the device.
+ *
+ * @param client The connected sbservices client to use.
+ * @param interface_orientation The interface orientation upon successful return.
+ *
+ * @return SBSERVICES_E_SUCCESS on success, SBSERVICES_E_INVALID_ARG when
+ * client or state is invalid, or an SBSERVICES_E_* error code otherwise.
+ */
sbservices_error_t sbservices_get_interface_orientation(sbservices_client_t client, sbservices_interface_orientation_t* interface_orientation);
+
+/**
+ * Get the home screen wallpaper as PNG data.
+ *
+ * @param client The connected sbservices client to use.
+ * @param pngdata Pointer that will point to a newly allocated buffer
+ * containing the PNG data upon successful return. It is up to the caller
+ * to free the memory.
+ * @param pngsize Pointer to a uint64_t that will be set to the size of the
+ * buffer pngdata points to upon successful return.
+ *
+ * @return SBSERVICES_E_SUCCESS on success, SBSERVICES_E_INVALID_ARG when
+ * client or pngdata are invalid, or an SBSERVICES_E_* error
+ * code otherwise.
+ */
sbservices_error_t sbservices_get_home_screen_wallpaper_pngdata(sbservices_client_t client, char **pngdata, uint64_t *pngsize);
#ifdef __cplusplus
diff --git a/include/libimobiledevice/screenshotr.h b/include/libimobiledevice/screenshotr.h
index c8679a9..3601172 100644
--- a/include/libimobiledevice/screenshotr.h
+++ b/include/libimobiledevice/screenshotr.h
@@ -50,10 +50,65 @@ typedef int16_t screenshotr_error_t;
typedef struct screenshotr_client_private screenshotr_client_private;
typedef screenshotr_client_private *screenshotr_client_t; /**< The client handle. */
+
+/**
+ * Connects to the screenshotr 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 be set to a newly allocated
+ * screenshotr_client_t upon successful return.
+ *
+ * @note This service is only available if a developer disk image has been
+ * mounted.
+ *
+ * @return SCREENSHOTR_E_SUCCESS on success, SCREENSHOTR_E_INVALID ARG if one
+ * or more parameters are invalid, or SCREENSHOTR_E_CONN_FAILED if the
+ * connection to the device could not be established.
+ */
screenshotr_error_t screenshotr_client_new(idevice_t device, lockdownd_service_descriptor_t service, screenshotr_client_t * client);
+
+/**
+ * Starts a new screenshotr 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
+ * screenshotr_client_t upon successful return. Must be freed using
+ * screenshotr_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 SCREENSHOTR_E_SUCCESS on success, or an SCREENSHOTR_E_* error
+ * code otherwise.
+ */
screenshotr_error_t screenshotr_client_start_service(idevice_t device, screenshotr_client_t* client, const char* label);
+
+/**
+ * Disconnects a screenshotr client from the device and frees up the
+ * screenshotr client data.
+ *
+ * @param client The screenshotr client to disconnect and free.
+ *
+ * @return SCREENSHOTR_E_SUCCESS on success, or SCREENSHOTR_E_INVALID_ARG
+ * if client is NULL.
+ */
screenshotr_error_t screenshotr_client_free(screenshotr_client_t client);
+
+/**
+ * Get a screen shot from the connected device.
+ *
+ * @param client The connection screenshotr service client.
+ * @param imgdata Pointer that will point to a newly allocated buffer
+ * containing TIFF image data upon successful return. It is up to the
+ * caller to free the memory.
+ * @param imgsize Pointer to a uint64_t that will be set to the size of the
+ * buffer imgdata points to upon successful return.
+ *
+ * @return SCREENSHOTR_E_SUCCESS on success, SCREENSHOTR_E_INVALID_ARG if
+ * one or more parameters are invalid, or another error code if an
+ * error occured.
+ */
screenshotr_error_t screenshotr_take_screenshot(screenshotr_client_t client, char **imgdata, uint64_t *imgsize);
#ifdef __cplusplus
diff --git a/include/libimobiledevice/service.h b/include/libimobiledevice/service.h
index 6585fe7..acf846b 100644
--- a/include/libimobiledevice/service.h
+++ b/include/libimobiledevice/service.h
@@ -49,15 +49,120 @@ typedef service_client_private* service_client_t; /**< The client handle. */
#define SERVICE_CONSTRUCTOR(x) (int16_t (*)(idevice_t, lockdownd_service_descriptor_t, void**))(x)
/* Interface */
+
+/**
+ * Creates a new service for the specified service descriptor.
+ *
+ * @param device The device to connect to.
+ * @param service The service descriptor returned by lockdownd_start_service.
+ * @param client Pointer that will be set to a newly allocated
+ * service_client_t upon successful return.
+ *
+ * @return SERVICE_E_SUCCESS on success,
+ * SERVICE_E_INVALID_ARG when one of the arguments is invalid,
+ * or SERVICE_E_MUX_ERROR when connecting to the device failed.
+ */
service_error_t service_client_new(idevice_t device, lockdownd_service_descriptor_t service, service_client_t *client);
+
+/**
+ * Starts a new service on the specified device with given name and
+ * connects to it.
+ *
+ * @param device The device to connect to.
+ * @param service_name The name of the service to start.
+ * @param client Pointer that will point to a newly allocated service_client_t
+ * upon successful return. Must be freed using service_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 SERVICE_E_SUCCESS on success, or a SERVICE_E_* error code
+ * otherwise.
+ */
service_error_t service_client_factory_start_service(idevice_t device, const char* service_name, void **client, const char* label, int16_t (*constructor_func)(idevice_t, lockdownd_service_descriptor_t, void**), int16_t *error_code);
+
+/**
+ * Frees a service instance.
+ *
+ * @param client The service instance to free.
+ *
+ * @return SERVICE_E_SUCCESS on success,
+ * SERVICE_E_INVALID_ARG when client is invalid, or a
+ * SERVICE_E_UNKNOWN_ERROR when another error occured.
+ */
service_error_t service_client_free(service_client_t client);
+
+/**
+ * Sends data using the given service client.
+ *
+ * @param client The service client to use for sending.
+ * @param data Data to send
+ * @param size Size of the data to send
+ * @param sent Number of bytes sent (can be NULL to ignore)
+ *
+ * @return SERVICE_E_SUCCESS on success,
+ * SERVICE_E_INVALID_ARG when one or more parameters are
+ * invalid, or SERVICE_E_UNKNOWN_ERROR when an unspecified
+ * error occurs.
+ */
service_error_t service_send(service_client_t client, const char *data, uint32_t size, uint32_t *sent);
+
+/**
+ * Receives data using the given service client with specified timeout.
+ *
+ * @param client The service client to use for receiving
+ * @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 SERVICE_E_SUCCESS on success,
+ * SERVICE_E_INVALID_ARG when one or more parameters are
+ * invalid, SERVICE_E_MUX_ERROR when a communication error
+ * occurs, or SERVICE_E_UNKNOWN_ERROR when an unspecified
+ * error occurs.
+ */
service_error_t service_receive_with_timeout(service_client_t client, char *data, uint32_t size, uint32_t *received, unsigned int timeout);
+
+/**
+ * Receives data using the given service client.
+ *
+ * @param client The service client to use for receiving
+ * @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)
+ *
+ * @return SERVICE_E_SUCCESS on success,
+ * SERVICE_E_INVALID_ARG when one or more parameters are
+ * invalid, SERVICE_E_MUX_ERROR when a communication error
+ * occurs, or SERVICE_E_UNKNOWN_ERROR when an unspecified
+ * error occurs.
+ */
service_error_t service_receive(service_client_t client, char *data, uint32_t size, uint32_t *received);
+
+/**
+ * Enable SSL for the given service client.
+ *
+ * @param client The connected service client for that SSL should be enabled.
+ *
+ * @return SERVICE_E_SUCCESS on success,
+ * SERVICE_E_INVALID_ARG if client or client->connection is
+ * NULL, SERVICE_E_SSL_ERROR when SSL could not be enabled,
+ * or SERVICE_E_UNKNOWN_ERROR otherwise.
+ */
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.
+ *
+ * @return SERVICE_E_SUCCESS on success,
+ * SERVICE_E_INVALID_ARG if client or client->connection is
+ * NULL, or SERVICE_E_UNKNOWN_ERROR otherwise.
+ */
service_error_t service_disable_ssl(service_client_t client);
#ifdef __cplusplus
diff --git a/include/libimobiledevice/syslog_relay.h b/include/libimobiledevice/syslog_relay.h
index 7ccfd74..952840e 100644
--- a/include/libimobiledevice/syslog_relay.h
+++ b/include/libimobiledevice/syslog_relay.h
@@ -51,15 +51,109 @@ typedef syslog_relay_client_private *syslog_relay_client_t; /**< The client hand
typedef void (*syslog_relay_receive_cb_t)(char c, void *user_data);
/* Interface */
+
+/**
+ * Connects to the syslog_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
+ * syslog_relay_client_t upon successful return. Must be freed using
+ * syslog_relay_client_free() after use.
+ *
+ * @return SYSLOG_RELAY_E_SUCCESS on success, SYSLOG_RELAY_E_INVALID_ARG when
+ * client is NULL, or an SYSLOG_RELAY_E_* error code otherwise.
+ */
syslog_relay_error_t syslog_relay_client_new(idevice_t device, lockdownd_service_descriptor_t service, syslog_relay_client_t * client);
+
+/**
+ * Starts a new syslog_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
+ * syslog_relay_client_t upon successful return. Must be freed using
+ * syslog_relay_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 SYSLOG_RELAY_E_SUCCESS on success, or an SYSLOG_RELAY_E_* error
+ * code otherwise.
+ */
syslog_relay_error_t syslog_relay_client_start_service(idevice_t device, syslog_relay_client_t * client, const char* label);
+
+/**
+ * Disconnects a syslog_relay client from the device and frees up the
+ * syslog_relay client data.
+ *
+ * @param client The syslog_relay client to disconnect and free.
+ *
+ * @return SYSLOG_RELAY_E_SUCCESS on success, SYSLOG_RELAY_E_INVALID_ARG when
+ * client is NULL, or an SYSLOG_RELAY_E_* error code otherwise.
+ */
syslog_relay_error_t syslog_relay_client_free(syslog_relay_client_t client);
+
+/**
+ * Starts capturing the syslog of the device using a callback.
+ *
+ * Use syslog_relay_stop_capture() to stop receiving the syslog.
+ *
+ * @param client The syslog_relay client to use
+ * @param callback Callback to receive each character from the syslog.
+ * @param user_data Custom pointer passed to the callback function.
+ *
+ * @return SYSLOG_RELAY_E_SUCCESS on success,
+ * SYSLOG_RELAY_E_INVALID_ARG when one or more parameters are
+ * invalid or SYSLOG_RELAY_E_UNKNOWN_ERROR when an unspecified
+ * error occurs or a syslog capture has already been started.
+ */
syslog_relay_error_t syslog_relay_start_capture(syslog_relay_client_t client, syslog_relay_receive_cb_t callback, void* user_data);
+
+/**
+ * Stops capturing the syslog of the device.
+ *
+ * Use syslog_relay_start_capture() to start receiving the syslog.
+ *
+ * @param client The syslog_relay client to use
+ *
+ * @return SYSLOG_RELAY_E_SUCCESS on success,
+ * SYSLOG_RELAY_E_INVALID_ARG when one or more parameters are
+ * invalid or SYSLOG_RELAY_E_UNKNOWN_ERROR when an unspecified
+ * error occurs or a syslog capture has already been started.
+ */
syslog_relay_error_t syslog_relay_stop_capture(syslog_relay_client_t client);
/* Receiving */
+
+/**
+ * Receives data using the given syslog_relay client with specified timeout.
+ *
+ * @param client The syslog_relay client to use for receiving
+ * @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 one or more parameters are
+ * invalid, SYSLOG_RELAY_E_MUX_ERROR when a communication error
+ * occurs, or SYSLOG_RELAY_E_UNKNOWN_ERROR when an unspecified
+ * error occurs.
+ */
syslog_relay_error_t syslog_relay_receive_with_timeout(syslog_relay_client_t client, char *data, uint32_t size, uint32_t *received, unsigned int timeout);
+
+/**
+ * Receives data from the service.
+ *
+ * @param client The syslog_relay client
+ * @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
+ */
syslog_relay_error_t syslog_relay_receive(syslog_relay_client_t client, char *data, uint32_t size, uint32_t *received);
#ifdef __cplusplus
diff --git a/include/libimobiledevice/webinspector.h b/include/libimobiledevice/webinspector.h
index dfd4dd2..499e7f0 100644
--- a/include/libimobiledevice/webinspector.h
+++ b/include/libimobiledevice/webinspector.h
@@ -48,12 +48,85 @@ typedef int16_t webinspector_error_t;
typedef struct webinspector_client_private webinspector_client_private;
typedef webinspector_client_private *webinspector_client_t; /**< The client handle. */
+
+/**
+ * Connects to the webinspector 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
+ * webinspector_client_t upon successful return. Must be freed using
+ * webinspector_client_free() after use.
+ *
+ * @return WEBINSPECTOR_E_SUCCESS on success, WEBINSPECTOR_E_INVALID_ARG when
+ * client is NULL, or an WEBINSPECTOR_E_* error code otherwise.
+ */
webinspector_error_t webinspector_client_new(idevice_t device, lockdownd_service_descriptor_t service, webinspector_client_t * client);
+
+/**
+ * Starts a new webinspector 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
+ * webinspector_client_t upon successful return. Must be freed using
+ * webinspector_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 WEBINSPECTOR_E_SUCCESS on success, or an WEBINSPECTOR_E_* error
+ * code otherwise.
+ */
webinspector_error_t webinspector_client_start_service(idevice_t device, webinspector_client_t * client, const char* label);
+
+/**
+ * Disconnects a webinspector client from the device and frees up the
+ * webinspector client data.
+ *
+ * @param client The webinspector client to disconnect and free.
+ *
+ * @return WEBINSPECTOR_E_SUCCESS on success, WEBINSPECTOR_E_INVALID_ARG when
+ * client is NULL, or an WEBINSPECTOR_E_* error code otherwise.
+ */
webinspector_error_t webinspector_client_free(webinspector_client_t client);
+
+/**
+ * Sends a plist to the service.
+ *
+ * @param client The webinspector client
+ * @param plist The plist to send
+ *
+ * @return DIAGNOSTICS_RELAY_E_SUCCESS on success,
+ * DIAGNOSTICS_RELAY_E_INVALID_ARG when client or plist is NULL
+ */
webinspector_error_t webinspector_send(webinspector_client_t client, plist_t plist);
+
+/**
+ * Receives a plist from the service.
+ *
+ * @param client The webinspector client
+ * @param plist The plist to store the received data
+ *
+ * @return DIAGNOSTICS_RELAY_E_SUCCESS on success,
+ * DIAGNOSTICS_RELAY_E_INVALID_ARG when client or plist is NULL
+ */
webinspector_error_t webinspector_receive(webinspector_client_t client, plist_t * plist);
+
+/**
+ * Receives a plist using the given webinspector client.
+ *
+ * @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.
+ *
+ * @return WEBINSPECTOR_E_SUCCESS on success,
+ * WEBINSPECTOR_E_INVALID_ARG when client or *plist is NULL,
+ * WEBINSPECTOR_E_PLIST_ERROR when the received data cannot be
+ * converted to a plist, WEBINSPECTOR_E_MUX_ERROR when a
+ * communication error occurs, or WEBINSPECTOR_E_UNKNOWN_ERROR
+ * when an unspecified error occurs.
+ */
webinspector_error_t webinspector_receive_with_timeout(webinspector_client_t client, plist_t * plist, uint32_t timeout_ms);
#ifdef __cplusplus