1 files changed, 200 insertions, 26 deletions

diff --git a/include/libimobiledevice/mobilebackup.h b/include/libimobiledevice/mobilebackup.h
index 8f31cc4..2ecb60c 100644
--- a/include/libimobiledevice/mobilebackup.h
+++ b/include/libimobiledevice/mobilebackup.h
@@ -3,7 +3,8 @@
  * @brief Backup and restore of all device data.
  * \internal
  *
- * Copyright (c) 2009 Martin Szulecki All Rights Reserved.
+ * Copyright (c) 2010-2019 Nikias Bassen, All Rights Reserved.
+ * Copyright (c) 2009-2014 Martin Szulecki, All Rights Reserved.
  *
  * This library is free software; you can redistribute it and/or
  * modify it under the terms of the GNU Lesser General Public
@@ -28,42 +29,215 @@ extern "C" {
 #endif
 
 #include <libimobiledevice/libimobiledevice.h>
+#include <libimobiledevice/lockdown.h>
 
-/** @name Error Codes */
-/*@{*/
-#define MOBILEBACKUP_E_SUCCESS                0
-#define MOBILEBACKUP_E_INVALID_ARG           -1
-#define MOBILEBACKUP_E_PLIST_ERROR           -2
-#define MOBILEBACKUP_E_MUX_ERROR             -3
-#define MOBILEBACKUP_E_BAD_VERSION           -4
-#define MOBILEBACKUP_E_REPLY_NOT_OK          -5
+/** Service identifier passed to lockdownd_start_service() to start the mobilebackup service */
+#define MOBILEBACKUP_SERVICE_NAME "com.apple.mobilebackup"
 
-#define MOBILEBACKUP_E_UNKNOWN_ERROR       -256
-/*@}*/
-
-/** Represents an error code. */
-typedef int16_t mobilebackup_error_t;
+/** Error Codes */
+typedef enum {
+        MOBILEBACKUP_E_SUCCESS         =  0,
+        MOBILEBACKUP_E_INVALID_ARG     = -1,
+        MOBILEBACKUP_E_PLIST_ERROR     = -2,
+        MOBILEBACKUP_E_MUX_ERROR       = -3,
+        MOBILEBACKUP_E_SSL_ERROR       = -4,
+        MOBILEBACKUP_E_RECEIVE_TIMEOUT = -5,
+        MOBILEBACKUP_E_BAD_VERSION     = -6,
+        MOBILEBACKUP_E_REPLY_NOT_OK    = -7,
+        MOBILEBACKUP_E_UNKNOWN_ERROR   = -256
+} mobilebackup_error_t;
 
-typedef struct mobilebackup_client_private mobilebackup_client_private;
+typedef struct mobilebackup_client_private mobilebackup_client_private; /**< \private */
 typedef mobilebackup_client_private *mobilebackup_client_t; /**< The client handle. */
 
+/** Available flags passed to #mobilebackup_request_restore */
 typedef enum {
         MB_RESTORE_NOTIFY_SPRINGBOARD = 1 << 0,
         MB_RESTORE_PRESERVE_SETTINGS = 1 << 1,
         MB_RESTORE_PRESERVE_CAMERA_ROLL = 1 << 2
 } mobilebackup_flags_t;
 
-mobilebackup_error_t mobilebackup_client_new(idevice_t device, uint16_t port, mobilebackup_client_t * client);
-mobilebackup_error_t mobilebackup_client_free(mobilebackup_client_t client);
-mobilebackup_error_t mobilebackup_receive(mobilebackup_client_t client, plist_t *plist);
-mobilebackup_error_t mobilebackup_send(mobilebackup_client_t client, plist_t plist);
-mobilebackup_error_t mobilebackup_request_backup(mobilebackup_client_t client, plist_t backup_manifest, const char *base_path, const char *proto_version);
-mobilebackup_error_t mobilebackup_send_backup_file_received(mobilebackup_client_t client);
-mobilebackup_error_t mobilebackup_request_restore(mobilebackup_client_t client, plist_t backup_manifest, mobilebackup_flags_t flags, const char *proto_version);
-mobilebackup_error_t mobilebackup_receive_restore_file_received(mobilebackup_client_t client, plist_t *result);
-mobilebackup_error_t mobilebackup_receive_restore_application_received(mobilebackup_client_t client, plist_t *result);
-mobilebackup_error_t mobilebackup_send_restore_complete(mobilebackup_client_t client);
-mobilebackup_error_t mobilebackup_send_error(mobilebackup_client_t client, const char *reason);
+/**
+ * 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.
+ */
+LIBIMOBILEDEVICE_API 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.
+ */
+LIBIMOBILEDEVICE_API 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.
+ */
+LIBIMOBILEDEVICE_API 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
+ */
+LIBIMOBILEDEVICE_API 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
+ */
+LIBIMOBILEDEVICE_API 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
+ */
+LIBIMOBILEDEVICE_API 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.
+ */
+LIBIMOBILEDEVICE_API 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.
+ */
+LIBIMOBILEDEVICE_API 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.
+ */
+LIBIMOBILEDEVICE_API 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.
+ */
+LIBIMOBILEDEVICE_API 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.
+ */
+LIBIMOBILEDEVICE_API 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.
+ */
+LIBIMOBILEDEVICE_API mobilebackup_error_t mobilebackup_send_error(mobilebackup_client_t client, const char *reason);
 
 #ifdef __cplusplus
 }