libimobiledevice: libimobiledevice/mobilebackup.h File Reference

libimobiledevice 1.3.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.

## 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_SSL_ERROR = -4, MOBILEBACKUP_E_RECEIVE_TIMEOUT = -5, MOBILEBACKUP_E_BAD_VERSION = -6, MOBILEBACKUP_E_REPLY_NOT_OK = -7, 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.

## Function Documentation

## ◆ mobilebackup_client_free()

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

  client | The mobilebackup client to disconnect and free.

Returns
  MOBILEBACKUP_E_SUCCESS on success, or MOBILEBACKUP_E_INVALID_ARG if client is NULL.

## ◆ mobilebackup_client_new()

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

  device | The device to connect to.
  service | The service descriptor returned by lockdownd_start_service.
  client | Pointer 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_client_start_service()

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

  device | The device to connect to.
  client | Pointer that will point to a newly allocated mobilebackup_client_t upon successful return. Must be freed using mobilebackup_client_free() after use.
  label | The 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_receive()

mobilebackup_error_t mobilebackup_receive | ( | mobilebackup_client_t | client,
|  | plist_t * | plist
| ) |  |

Polls the device for mobilebackup data.

Parameters

  client | The mobilebackup client
  plist | A pointer to the location where the plist should be stored

Returns
  an error code

## ◆ mobilebackup_receive_restore_application_received()

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

  client | The connected MobileBackup client to use.
  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.

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_receive_restore_file_received()

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

  client | The connected MobileBackup client to use.
  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.

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_request_backup()

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

  client | The connected MobileBackup client to use.
  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.
  base_path | The base path on the device to use for the backup operation, usually "/".
  proto_version | A 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_request_restore()

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

  client | The connected MobileBackup client to use.
  backup_manifest | The backup manifest, a plist_t of type PLIST_DICT containing the backup state to be restored.
  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
  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.

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_send()

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

  client | The mobilebackup client
  plist | The location of the plist to send

Returns
  an error code

## ◆ mobilebackup_send_backup_file_received()

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

  client | The 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_send_error()

mobilebackup_error_t mobilebackup_send_error | ( | mobilebackup_client_t | client,
|  | const char * | reason
| ) |  |

Sends a backup error message to the device.

Parameters

  client | The connected MobileBackup client to use.
  reason | A 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_send_restore_complete()

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

  client | The 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.