libimobiledevice 1.1.1
Data Structures | Typedefs | Enumerations | Functions

libimobiledevice/mobilesync.h File Reference

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

Data Structures

struct  mobilesync_anchors

Typedefs

typedef int16_t mobilesync_error_t
 Represents an error code.
typedef mobilesync_client_privatemobilesync_client_t
 The client handle.
typedef mobilesync_anchorsmobilesync_anchors_t
 Anchors used by the device and computer.

Enumerations

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, uint16_t port, mobilesync_client_t *client)
 Connects to the mobilesync service on the specified device.
mobilesync_error_t mobilesync_client_free (mobilesync_client_t client)
 Disconnects a mobilesync client from the device and frees up the mobilesync client data.
mobilesync_error_t mobilesync_receive (mobilesync_client_t client, plist_t *plist)
 Polls the device for mobilesync data.
mobilesync_error_t mobilesync_send (mobilesync_client_t client, plist_t plist)
 Sends mobilesync data to the device.
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)
 Requests starting synchronization of a data class with the device.
mobilesync_error_t mobilesync_cancel (mobilesync_client_t client, const char *reason)
 Cancels a running synchronization session with a device at any time.
mobilesync_error_t mobilesync_finish (mobilesync_client_t client)
 Finish a synchronization session of a data class on the 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.
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.
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.
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.
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.
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.
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.
mobilesync_error_t mobilesync_remap_identifiers (mobilesync_client_t client, plist_t *mapping)
 Receives any remapped identifiers reported after the device merged submitted changes.
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.
void mobilesync_anchors_free (mobilesync_anchors_t anchors)
 Free memory used by anchors.
plist_t mobilesync_actions_new ()
 Create a new actions plist to use in mobilesync_send_changes().
void mobilesync_actions_add (plist_t actions,...) G_GNUC_NULL_TERMINATED
 Add one or more new key:value pairs to the given actions plist.
void mobilesync_actions_free (plist_t actions)
 Free actions plist.

Error Codes

#define MOBILESYNC_E_SUCCESS   0
#define MOBILESYNC_E_INVALID_ARG   -1
#define MOBILESYNC_E_PLIST_ERROR   -2
#define MOBILESYNC_E_MUX_ERROR   -3
#define MOBILESYNC_E_BAD_VERSION   -4
#define MOBILESYNC_E_SYNC_REFUSED   -5
#define MOBILESYNC_E_CANCELLED   -6
#define MOBILESYNC_E_WRONG_DIRECTION   -7
#define MOBILESYNC_E_NOT_READY   -8
#define MOBILESYNC_E_UNKNOWN_ERROR   -256

Detailed Description

Synchronize data classes with a device and computer.


Typedef Documentation

Anchors used by the device and computer.

typedef int16_t mobilesync_error_t

Represents an error code.


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

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,
uint16_t  port,
mobilesync_client_t client 
)

Connects to the mobilesync service on the specified device.

Parameters:
deviceThe device to connect to.
portDestination port (usually given 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_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 
)

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

References MOBILESYNC_SYNC_TYPE_FAST, MOBILESYNC_SYNC_TYPE_RESET, and MOBILESYNC_SYNC_TYPE_SLOW.