libimobiledevice  1.1.5
Typedefs | Enumerations | Functions
mobilebackup.h File Reference

Backup and restore of all device data. More...

Typedefs

typedef int16_t mobilebackup_error_t
 Represents an error code.
typedef
mobilebackup_client_private
mobilebackup_client_t
 The client handle.

Enumerations

enum  mobilebackup_flags_t {
  MB_RESTORE_NOTIFY_SPRINGBOARD = 1 << 0,
  MB_RESTORE_PRESERVE_SETTINGS = 1 << 1,
  MB_RESTORE_PRESERVE_CAMERA_ROLL = 1 << 2
}

Functions

mobilebackup_error_t mobilebackup_client_new (idevice_t device, lockdownd_service_descriptor_t service, mobilebackup_client_t *client)
 Connects to the mobilebackup service on the specified device.
mobilebackup_error_t mobilebackup_client_free (mobilebackup_client_t client)
 Disconnects a mobilebackup client from the device and frees up the mobilebackup client data.
mobilebackup_error_t mobilebackup_receive (mobilebackup_client_t client, plist_t *plist)
 Polls the device for mobilebackup data.
mobilebackup_error_t mobilebackup_send (mobilebackup_client_t client, plist_t plist)
 Sends mobilebackup data to the device.
mobilebackup_error_t mobilebackup_request_backup (mobilebackup_client_t client, plist_t backup_manifest, const char *base_path, const char *proto_version)
 Request a backup from the connected device.
mobilebackup_error_t mobilebackup_send_backup_file_received (mobilebackup_client_t client)
 Sends a confirmation to the device that a backup file has been received.
mobilebackup_error_t mobilebackup_request_restore (mobilebackup_client_t client, plist_t backup_manifest, mobilebackup_flags_t flags, const char *proto_version)
 Request that a backup should be restored to the connected device.
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 a restore file.
mobilebackup_error_t mobilebackup_receive_restore_application_received (mobilebackup_client_t client, plist_t *result)
 Receive a confirmation from the device that it successfully received application data file.
mobilebackup_error_t mobilebackup_send_restore_complete (mobilebackup_client_t client)
 Tells the device that the restore process is complete and waits for the device to close the connection.
mobilebackup_error_t mobilebackup_send_error (mobilebackup_client_t client, const char *reason)
 Sends a backup error message to the device.

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
#define MOBILEBACKUP_E_UNKNOWN_ERROR   -256

Detailed Description

Backup and restore of all device data.


Typedef Documentation

The client handle.

typedef int16_t mobilebackup_error_t

Represents an error code.


Function Documentation

mobilebackup_error_t mobilebackup_client_free ( mobilebackup_client_t  client)

Disconnects a mobilebackup client from the device and frees up the mobilebackup client data.

Parameters:
clientThe mobilebackup client to disconnect and free.
Returns:
MOBILEBACKUP_E_SUCCESS on success, or MOBILEBACKUP_E_INVALID_ARG if client is NULL.
mobilebackup_error_t mobilebackup_client_new ( idevice_t  device,
lockdownd_service_descriptor_t  service,
mobilebackup_client_t client 
)

Connects to the mobilebackup service on the specified device.

Parameters:
deviceThe device to connect to.
serviceThe service descriptor returned by lockdownd_start_service.
clientPointer that will be set to a newly allocated mobilebackup_client_t upon successful return.
Returns:
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_receive ( mobilebackup_client_t  client,
plist_t *  plist 
)

Polls the device for mobilebackup data.

Parameters:
clientThe mobilebackup client
plistA pointer to the location where the plist should be stored
Returns:
an error code
mobilebackup_error_t mobilebackup_receive_restore_application_received ( mobilebackup_client_t  client,
plist_t *  result 
)

Receive a confirmation from the device that it successfully received application data file.

Parameters:
clientThe connected MobileBackup client to use.
resultPointer 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.
Returns:
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_file_received ( mobilebackup_client_t  client,
plist_t *  result 
)

Receive a confirmation from the device that it successfully received a restore file.

Parameters:
clientThe connected MobileBackup client to use.
resultPointer 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.
Returns:
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_request_backup ( mobilebackup_client_t  client,
plist_t  backup_manifest,
const char *  base_path,
const char *  proto_version 
)

Request a backup from the connected device.

Parameters:
clientThe connected MobileBackup client to use.
backup_manifestThe 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.
base_pathThe base path on the device to use for the backup operation, usually "/".
proto_versionA string denoting the version of the backup protocol to use. Latest known version is "1.6"
Returns:
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_restore ( mobilebackup_client_t  client,
plist_t  backup_manifest,
mobilebackup_flags_t  flags,
const char *  proto_version 
)

Request that a backup should be restored to the connected device.

Parameters:
clientThe connected MobileBackup client to use.
backup_manifestThe backup manifest, a plist_t of type PLIST_DICT containing the backup state to be restored.
flagsFlags 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
proto_versionA 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.
Returns:
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_send ( 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.
Parameters:
clientThe mobilebackup client
plistThe location of the plist to send
Returns:
an error code
mobilebackup_error_t mobilebackup_send_backup_file_received ( mobilebackup_client_t  client)

Sends a confirmation to the device that a backup file has been received.

Parameters:
clientThe connected MobileBackup client to use.
Returns:
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_error ( mobilebackup_client_t  client,
const char *  reason 
)

Sends a backup error message to the device.

Parameters:
clientThe connected MobileBackup client to use.
reasonA string describing the reason for the error message.
Returns:
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_restore_complete ( mobilebackup_client_t  client)

Tells the device that the restore process is complete and waits for the device to close the connection.

After that, the device should reboot.

Parameters:
clientThe connected MobileBackup client to use.
Returns:
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.