libimobiledevice: libimobiledevice/mobilesync.h File Reference

libimobiledevice 1.3.0

Data Structures | Macros | Typedefs | Enumerations | Functions
mobilesync.h File Reference

Synchronize data classes with a device and computer. More...

## Data Structures
struct | mobilesync_anchors

## Macros
#define | MOBILESYNC_SERVICE_NAME "com.apple.mobilesync"

## Typedefs
typedef struct mobilesync_client_private | mobilesync_client_private
typedef mobilesync_client_private * | mobilesync_client_t
| The client handle.
typedef mobilesync_anchors * | mobilesync_anchors_t
| Anchors used by the device and computer.

## Enumerations
enum | mobilesync_error_t { MOBILESYNC_E_SUCCESS = 0, MOBILESYNC_E_INVALID_ARG = -1, MOBILESYNC_E_PLIST_ERROR = -2, MOBILESYNC_E_MUX_ERROR = -3, MOBILESYNC_E_SSL_ERROR = -4, MOBILESYNC_E_RECEIVE_TIMEOUT = -5, MOBILESYNC_E_BAD_VERSION = -6, MOBILESYNC_E_SYNC_REFUSED = -7, MOBILESYNC_E_CANCELLED = -8, MOBILESYNC_E_WRONG_DIRECTION = -9, MOBILESYNC_E_NOT_READY = -10, MOBILESYNC_E_UNKNOWN_ERROR = -256 }
| Error Codes.
enum | mobilesync_sync_type_t { MOBILESYNC_SYNC_TYPE_FAST, MOBILESYNC_SYNC_TYPE_SLOW, MOBILESYNC_SYNC_TYPE_RESET }
| The sync type of the current sync session. More...

## Functions
mobilesync_error_t | mobilesync_client_new (idevice_t device, lockdownd_service_descriptor_t service, mobilesync_client_t *client)
| Connects to the mobilesync service on the specified device. More...
mobilesync_error_t | mobilesync_client_start_service (idevice_t device, mobilesync_client_t *client, const char *label)
| Starts a new mobilesync service on the specified device and connects to it. More...
mobilesync_error_t | mobilesync_client_free (mobilesync_client_t client)
| Disconnects a mobilesync client from the device and frees up the mobilesync client data. More...
mobilesync_error_t | mobilesync_receive (mobilesync_client_t client, plist_t *plist)
| Polls the device for mobilesync data. More...
mobilesync_error_t | mobilesync_send (mobilesync_client_t client, plist_t plist)
| Sends mobilesync data to the device. More...
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)
| Requests starting synchronization of a data class with the device. More...
mobilesync_error_t | mobilesync_cancel (mobilesync_client_t client, const char *reason)
| Cancels a running synchronization session with a device at any time. More...
mobilesync_error_t | mobilesync_finish (mobilesync_client_t client)
| Finish a synchronization session of a data class on the device. More...
mobilesync_error_t | mobilesync_get_all_records_from_device (mobilesync_client_t client)
| Requests to receive all records of the currently set data class from the device. More...
mobilesync_error_t | mobilesync_get_changes_from_device (mobilesync_client_t client)
| Requests to receive only changed records of the currently set data class from the device. More...
mobilesync_error_t | mobilesync_clear_all_records_on_device (mobilesync_client_t client)
| Requests the device to delete all records of the current data class. More...
mobilesync_error_t | mobilesync_receive_changes (mobilesync_client_t client, plist_t *entities, uint8_t *is_last_record, plist_t *actions)
| Receives changed entitites of the currently set data class from the device. More...
mobilesync_error_t | mobilesync_acknowledge_changes_from_device (mobilesync_client_t client)
| Acknowledges to the device that the changes have been merged on the computer. More...
mobilesync_error_t | mobilesync_ready_to_send_changes_from_computer (mobilesync_client_t client)
| Verifies if the device is ready to receive changes from the computer. More...
mobilesync_error_t | mobilesync_send_changes (mobilesync_client_t client, plist_t entities, uint8_t is_last_record, plist_t actions)
| Sends changed entities of the currently set data class to the device. More...
mobilesync_error_t | mobilesync_remap_identifiers (mobilesync_client_t client, plist_t *mapping)
| Receives any remapped identifiers reported after the device merged submitted changes. More...
mobilesync_anchors_t | mobilesync_anchors_new (const char *device_anchor, const char *computer_anchor)
| Allocates memory for a new anchors struct initialized with the passed anchors. More...
void | mobilesync_anchors_free (mobilesync_anchors_t anchors)
| Free memory used by anchors. More...
plist_t | mobilesync_actions_new (void)
| Create a new actions plist to use in mobilesync_send_changes(). More...
void | mobilesync_actions_add (plist_t actions,...)
| Add one or more new key:value pairs to the given actions plist. More...
void | mobilesync_actions_free (plist_t actions)
| Free actions plist. More...

## Detailed Description

Synchronize data classes with a device and computer.

## Enumeration Type Documentation

## ◆ mobilesync_sync_type_t

enum mobilesync_sync_type_t

The sync type of the current sync session.

Enumerator
MOBILESYNC_SYNC_TYPE_FAST | Fast-sync requires that only the changes made since the last synchronization should be reported by the computer.
MOBILESYNC_SYNC_TYPE_SLOW | Slow-sync requires that all data from the computer needs to be synchronized/sent.
MOBILESYNC_SYNC_TYPE_RESET | Reset-sync signals that the computer should send all data again.

## Function Documentation

## ◆ mobilesync_acknowledge_changes_from_device()

mobilesync_error_t mobilesync_acknowledge_changes_from_device | ( | mobilesync_client_t | client | ) |

Acknowledges to the device that the changes have been merged on the computer.

Parameters

  client | The mobilesync client

Return values

  MOBILESYNC_E_SUCCESS | on success
  MOBILESYNC_E_INVALID_ARG | if one of the parameters is invalid

## ◆ mobilesync_actions_add()

void mobilesync_actions_add | ( | plist_t | actions,
|  |  | ...
| ) |  |

Add one or more new key:value pairs to the given actions plist.

Parameters

  actions | The actions to modify.
  ... | 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.

## ◆ mobilesync_actions_free()

void mobilesync_actions_free | ( | plist_t | actions | ) |

Free actions plist.

Parameters

  actions | The actions plist to free. Does nothing if NULL is passed.

## ◆ mobilesync_actions_new()

plist_t mobilesync_actions_new | ( | void |  | ) |

Create a new actions plist to use in mobilesync_send_changes().

Returns
  A new plist_t of type PLIST_DICT.

## ◆ mobilesync_anchors_free()

void mobilesync_anchors_free | ( | mobilesync_anchors_t | anchors | ) |

Free memory used by anchors.

Parameters

  anchors | The anchors to free.

## ◆ mobilesync_anchors_new()

mobilesync_anchors_t mobilesync_anchors_new | ( | const char * | device_anchor,
|  | const char * | computer_anchor
| ) |  |

Allocates memory for a new anchors struct initialized with the passed anchors.

Parameters

  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.
  computer_anchor | An arbitrary string to use as anchor for the computer.

Returns
  A new mobilesync_anchors_t struct. Must be freed using mobilesync_anchors_free().

## ◆ mobilesync_cancel()

mobilesync_error_t mobilesync_cancel | ( | mobilesync_client_t | client,
|  | const char * | reason
| ) |  |

Cancels a running synchronization session with a device at any time.

Parameters

  client | The mobilesync client
  reason | The reason to supply to the device for cancelling

Return values

  MOBILESYNC_E_SUCCESS | on success
  MOBILESYNC_E_INVALID_ARG | if one of the parameters is invalid

## ◆ mobilesync_clear_all_records_on_device()

mobilesync_error_t mobilesync_clear_all_records_on_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.

Parameters

  client | The mobilesync client

Return values

  MOBILESYNC_E_SUCCESS | on success
  MOBILESYNC_E_INVALID_ARG | if one of the parameters is invalid
  MOBILESYNC_E_PLIST_ERROR | if the received plist is not of valid form

## ◆ mobilesync_client_free()

mobilesync_error_t mobilesync_client_free | ( | mobilesync_client_t | client | ) |

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

Parameters

  client | The mobilesync client to disconnect and free.

Return values

  MOBILESYNC_E_SUCCESS | on success
  MOBILESYNC_E_INVALID_ARG | if client is NULL.

## ◆ mobilesync_client_new()

mobilesync_error_t mobilesync_client_new | ( | idevice_t | device,
|  | lockdownd_service_descriptor_t | service,
|  | mobilesync_client_t * | client
| ) |  |

Connects to the mobilesync 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 mobilesync_client_t upon successful return.

Return values

  MOBILESYNC_E_SUCCESS | on success
  MOBILESYNC_E_INVALID_ARG | if one or more parameters are invalid
  DEVICE_LINK_SERVICE_E_BAD_VERSION | if the mobilesync version on the device is newer.

## ◆ mobilesync_client_start_service()

mobilesync_error_t mobilesync_client_start_service | ( | idevice_t | device,
|  | mobilesync_client_t * | client,
|  | const char * | label
| ) |  |

Starts a new mobilesync 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 mobilesync_client_t upon successful return. Must be freed using mobilesync_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
  MOBILESYNC_E_SUCCESS on success, or an MOBILESYNC_E_* error code otherwise.

## ◆ mobilesync_finish()

mobilesync_error_t mobilesync_finish | ( | mobilesync_client_t | client | ) |

Finish a synchronization session of a data class on the device.

A session must have previously been started using mobilesync_start().

Parameters

  client | The mobilesync client

Return values

  MOBILESYNC_E_SUCCESS | on success
  MOBILESYNC_E_INVALID_ARG | if one of the parameters is invalid
  MOBILESYNC_E_PLIST_ERROR | if the received plist is not of valid form

## ◆ mobilesync_get_all_records_from_device()

mobilesync_error_t mobilesync_get_all_records_from_device | ( | 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.

Parameters

  client | The mobilesync client

Return values

  MOBILESYNC_E_SUCCESS | on success
  MOBILESYNC_E_INVALID_ARG | if one of the parameters is invalid

## ◆ mobilesync_get_changes_from_device()

mobilesync_error_t mobilesync_get_changes_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.

Parameters

  client | The mobilesync client

Return values

  MOBILESYNC_E_SUCCESS | on success
  MOBILESYNC_E_INVALID_ARG | if one of the parameters is invalid

## ◆ mobilesync_ready_to_send_changes_from_computer()

mobilesync_error_t mobilesync_ready_to_send_changes_from_computer | ( | 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.

Parameters

  client | The mobilesync client

Return values

  MOBILESYNC_E_SUCCESS | on success
  MOBILESYNC_E_INVALID_ARG | if one of the parameters is invalid
  MOBILESYNC_E_PLIST_ERROR | if the received plist is not of valid form
  MOBILESYNC_E_WRONG_DIRECTION | if the current sync direction does not permit this call
  MOBILESYNC_E_CANCELLED | if the device explicitly cancelled the session
  MOBILESYNC_E_NOT_READY | if the device is not ready to start receiving any changes

## ◆ mobilesync_receive()

mobilesync_error_t mobilesync_receive | ( | mobilesync_client_t | client,
|  | plist_t * | plist
| ) |  |

Polls the device for mobilesync data.

Parameters

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

Returns
  an error code

## ◆ mobilesync_receive_changes()

mobilesync_error_t mobilesync_receive_changes | ( | mobilesync_client_t | client,
|  | plist_t * | entities,
|  | uint8_t * | is_last_record,
|  | plist_t * | actions
| ) |  |

Receives changed entitites of the currently set data class from the device.

Parameters

  client | The mobilesync client
  entities | A pointer to store the changed entity records as a PLIST_DICT
  is_last_record | A pointer to store a flag indicating if this submission is the last one
  actions | A pointer to additional flags the device is sending or NULL to ignore

Return values

  MOBILESYNC_E_SUCCESS | on success
  MOBILESYNC_E_INVALID_ARG | if one of the parameters is invalid
  MOBILESYNC_E_CANCELLED | if the device explicitly cancelled the session

## ◆ mobilesync_remap_identifiers()

mobilesync_error_t mobilesync_remap_identifiers | ( | mobilesync_client_t | client,
|  | plist_t * | mapping
| ) |  |

Receives any remapped identifiers reported after the device merged submitted changes.

Parameters

  client | The mobilesync client
  mapping | A pointer to an array plist containing a dict of identifier remappings

Return values

  MOBILESYNC_E_SUCCESS | on success
  MOBILESYNC_E_INVALID_ARG | if one of the parameters is invalid
  MOBILESYNC_E_PLIST_ERROR | if the received plist is not of valid form
  MOBILESYNC_E_WRONG_DIRECTION | if the current sync direction does not permit this call
  MOBILESYNC_E_CANCELLED | if the device explicitly cancelled the session

## ◆ mobilesync_send()

mobilesync_error_t mobilesync_send | ( | 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.

Parameters

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

Returns
  an error code

## ◆ mobilesync_send_changes()

mobilesync_error_t mobilesync_send_changes | ( | mobilesync_client_t | client,
|  | plist_t | entities,
|  | uint8_t | is_last_record,
|  | plist_t | actions
| ) |  |

Sends changed entities of the currently set data class to the device.

Parameters

  client | The mobilesync client
  entities | The changed entity records as a PLIST_DICT
  is_last_record | A flag indicating if this submission is the last one
  actions | Additional actions for the device created with mobilesync_actions_new() or NULL if no actions should be passed

Return values

  MOBILESYNC_E_SUCCESS | on success
  MOBILESYNC_E_INVALID_ARG | if one of the parameters is invalid,
  MOBILESYNC_E_WRONG_DIRECTION | if the current sync direction does not permit this call

## ◆ mobilesync_start()

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

Requests starting synchronization of a data class with the device.

Parameters

  client | The mobilesync client
  data_class | The data class identifier to sync
  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.
  computer_data_class_version | The version of the data class storage on the computer
  sync_type | A pointer to store the sync type reported by the device_anchor
  device_data_class_version | The version of the data class storage on the device
  error_description | A pointer to store an error message if reported by the device

Return values

  MOBILESYNC_E_SUCCESS | on success
  MOBILESYNC_E_INVALID_ARG | if one of the parameters is invalid
  MOBILESYNC_E_PLIST_ERROR | if the received plist is not of valid form
  MOBILESYNC_E_SYNC_REFUSED | if the device refused to sync
  MOBILESYNC_E_CANCELLED | if the device explicitly cancelled the sync request