libimobiledevice  1.2.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_anchorsmobilesync_anchors_t
 Anchors used by the device and computer. More...
 

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_BAD_VERSION = -4,
  MOBILESYNC_E_SYNC_REFUSED = -5,
  MOBILESYNC_E_CANCELLED = -6,
  MOBILESYNC_E_WRONG_DIRECTION = -7,
  MOBILESYNC_E_NOT_READY = -8,
  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.

Typedef Documentation

Anchors used by the device and computer.

Enumeration Type Documentation

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_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
clientThe mobilesync client
Return values
MOBILESYNC_E_SUCCESSon success
MOBILESYNC_E_INVALID_ARGif one of the parameters is invalid
void mobilesync_actions_add ( plist_t  actions,
  ... 
)

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

Parameters
actionsThe 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.
void mobilesync_actions_free ( plist_t  actions)

Free actions plist.

Parameters
actionsThe actions plist to free. Does nothing if NULL is passed.
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.
void mobilesync_anchors_free ( mobilesync_anchors_t  anchors)

Free memory used by anchors.

Parameters
anchorsThe anchors to free.
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_anchorAn anchor the device reported the last time or NULL if none is known yet which for instance is true on first synchronization.
computer_anchorAn arbitrary string to use as anchor for the computer.
Returns
A new mobilesync_anchors_t struct. Must be freed using mobilesync_anchors_free().
mobilesync_error_t mobilesync_cancel ( mobilesync_client_t  client,
const char *  reason 
)

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

Parameters
clientThe mobilesync client
reasonThe reason to supply to the device for cancelling
Return values
MOBILESYNC_E_SUCCESSon success
MOBILESYNC_E_INVALID_ARGif one of the parameters is invalid
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
clientThe mobilesync client
Return values
MOBILESYNC_E_SUCCESSon success
MOBILESYNC_E_INVALID_ARGif one of the parameters is invalid
MOBILESYNC_E_PLIST_ERRORif the received plist is not of valid form
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
clientThe mobilesync client to disconnect and free.
Return values
MOBILESYNC_E_SUCCESSon success
MOBILESYNC_E_INVALID_ARGif client is NULL.
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
deviceThe device to connect to.
serviceThe service descriptor returned by lockdownd_start_service.
clientPointer that will be set to a newly allocated mobilesync_client_t upon successful return.
Return values
MOBILESYNC_E_SUCCESSon success
MOBILESYNC_E_INVALID_ARGif one or more parameters are invalid
DEVICE_LINK_SERVICE_E_BAD_VERSIONif the mobilesync version on the device is newer.
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
deviceThe device to connect to.
clientPointer that will point to a newly allocated mobilesync_client_t upon successful return. Must be freed using mobilesync_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
MOBILESYNC_E_SUCCESS on success, or an MOBILESYNC_E_* error code otherwise.
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
clientThe mobilesync client
Return values
MOBILESYNC_E_SUCCESSon success
MOBILESYNC_E_INVALID_ARGif one of the parameters is invalid
MOBILESYNC_E_PLIST_ERRORif the received plist is not of valid form
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
clientThe mobilesync client
Return values
MOBILESYNC_E_SUCCESSon success
MOBILESYNC_E_INVALID_ARGif one of the parameters is invalid
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
clientThe mobilesync client
Return values
MOBILESYNC_E_SUCCESSon success
MOBILESYNC_E_INVALID_ARGif one of the parameters is invalid
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
clientThe mobilesync client
Return values
MOBILESYNC_E_SUCCESSon success
MOBILESYNC_E_INVALID_ARGif one of the parameters is invalid
MOBILESYNC_E_PLIST_ERRORif the received plist is not of valid form
MOBILESYNC_E_WRONG_DIRECTIONif the current sync direction does not permit this call
MOBILESYNC_E_CANCELLEDif the device explicitly cancelled the session
MOBILESYNC_E_NOT_READYif the device is not ready to start receiving any changes
mobilesync_error_t mobilesync_receive ( mobilesync_client_t  client,
plist_t *  plist 
)

Polls the device for mobilesync data.

Parameters
clientThe mobilesync client
plistA pointer to the location where the plist should be stored
Returns
an error code
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
clientThe mobilesync client
entitiesA pointer to store the changed entity records as a PLIST_DICT
is_last_recordA pointer to store a flag indicating if this submission is the last one
actionsA pointer to additional flags the device is sending or NULL to ignore
Return values
MOBILESYNC_E_SUCCESSon success
MOBILESYNC_E_INVALID_ARGif one of the parameters is invalid
MOBILESYNC_E_CANCELLEDif the device explicitly cancelled the session
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
clientThe mobilesync client
mappingA pointer to an array plist containing a dict of identifier remappings
Return values
MOBILESYNC_E_SUCCESSon success
MOBILESYNC_E_INVALID_ARGif one of the parameters is invalid
MOBILESYNC_E_PLIST_ERRORif the received plist is not of valid form
MOBILESYNC_E_WRONG_DIRECTIONif the current sync direction does not permit this call
MOBILESYNC_E_CANCELLEDif the device explicitly cancelled the session
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
clientThe mobilesync client
plistThe location of the plist to send
Returns
an error code
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
clientThe mobilesync client
entitiesThe changed entity records as a PLIST_DICT
is_last_recordA flag indicating if this submission is the last one
actionsAdditional actions for the device created with mobilesync_actions_new() or NULL if no actions should be passed
Return values
MOBILESYNC_E_SUCCESSon success
MOBILESYNC_E_INVALID_ARGif one of the parameters is invalid,
MOBILESYNC_E_WRONG_DIRECTIONif the current sync direction does not permit this call
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
clientThe mobilesync client
data_classThe data class identifier to sync
anchorsThe 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_versionThe version of the data class storage on the computer
sync_typeA pointer to store the sync type reported by the device_anchor
device_data_class_versionThe version of the data class storage on the device
error_descriptionA pointer to store an error message if reported by the device
Return values
MOBILESYNC_E_SUCCESSon success
MOBILESYNC_E_INVALID_ARGif one of the parameters is invalid
MOBILESYNC_E_PLIST_ERRORif the received plist is not of valid form
MOBILESYNC_E_SYNC_REFUSEDif the device refused to sync
MOBILESYNC_E_CANCELLEDif the device explicitly cancelled the sync request