libimobiledevice  1.2.0
Macros | Typedefs | Enumerations | Functions
mobilebackup.h File Reference

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

Macros

#define MOBILEBACKUP_SERVICE_NAME   "com.apple.mobilebackup"
 

Typedefs

typedef struct
mobilebackup_client_private 
mobilebackup_client_private
 
typedef
mobilebackup_client_private * 
mobilebackup_client_t
 The client handle. More...
 

Enumerations

enum  mobilebackup_error_t {
  MOBILEBACKUP_E_SUCCESS = 0,
  MOBILEBACKUP_E_INVALID_ARG = -1,
  MOBILEBACKUP_E_PLIST_ERROR = -2,
  MOBILEBACKUP_E_MUX_ERROR = -3,
  MOBILEBACKUP_E_BAD_VERSION = -4,
  MOBILEBACKUP_E_REPLY_NOT_OK = -5,
  MOBILEBACKUP_E_UNKNOWN_ERROR = -256
}
 Error Codes.
 
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. More...
 
mobilebackup_error_t mobilebackup_client_start_service (idevice_t device, mobilebackup_client_t *client, const char *label)
 Starts a new mobilebackup service on the specified device and connects to it. More...
 
mobilebackup_error_t mobilebackup_client_free (mobilebackup_client_t client)
 Disconnects a mobilebackup client from the device and frees up the mobilebackup client data. More...
 
mobilebackup_error_t mobilebackup_receive (mobilebackup_client_t client, plist_t *plist)
 Polls the device for mobilebackup data. More...
 
mobilebackup_error_t mobilebackup_send (mobilebackup_client_t client, plist_t plist)
 Sends mobilebackup data to the device. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
mobilebackup_error_t mobilebackup_send_error (mobilebackup_client_t client, const char *reason)
 Sends a backup error message to the device. More...
 

Detailed Description

Backup and restore of all device data.

Typedef Documentation

typedef mobilebackup_client_private* mobilebackup_client_t

The client handle.

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_client_start_service ( idevice_t  device,
mobilebackup_client_t client,
const char *  label 
)

Starts a new mobilebackup service on the specified device and connects to it.

Parameters
deviceThe device to connect to.
clientPointer that will point to a newly allocated mobilebackup_client_t upon successful return. Must be freed using mobilebackup_client_free() after use.
labelThe label to use for communication. Usually the program name. Pass NULL to disable sending the label in requests to lockdownd.
Returns
MOBILEBACKUP_E_SUCCESS on success, or an MOBILEBACKUP_E_* error code otherwise.
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.