diff options
Diffstat (limited to 'include/libimobiledevice/mobilesync.h')
| -rw-r--r-- | include/libimobiledevice/mobilesync.h | 342 |
1 files changed, 299 insertions, 43 deletions
diff --git a/include/libimobiledevice/mobilesync.h b/include/libimobiledevice/mobilesync.h index 7658b7d..c3bc53d 100644 --- a/include/libimobiledevice/mobilesync.h +++ b/include/libimobiledevice/mobilesync.h @@ -3,6 +3,9 @@ * @brief Synchronize data classes with a device and computer. * \internal * + * Copyright (c) 2010-2019 Nikias Bassen, All Rights Reserved. + * Copyright (c) 2010-2014 Martin Szulecki All Rights Reserved. + * Copyright (c) 2014 Christophe Fergeau All Rights Reserved. * Copyright (c) 2010 Bryan Forbes All Rights Reserved. * Copyright (c) 2009 Jonathan Beck All Rights Reserved. * @@ -29,22 +32,26 @@ extern "C" { #endif #include <libimobiledevice/libimobiledevice.h> -#include <glib.h> - -/** @name 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 -/*@}*/ +#include <libimobiledevice/lockdown.h> + +/** Service identifier passed to lockdownd_start_service() to start the mobilesync service */ +#define MOBILESYNC_SERVICE_NAME "com.apple.mobilesync" + +/** Error Codes */ +typedef enum { + 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 +} mobilesync_error_t; /** The sync type of the current sync session. */ typedef enum { @@ -53,48 +60,297 @@ typedef enum { MOBILESYNC_SYNC_TYPE_RESET /**< Reset-sync signals that the computer should send all data again. */ } mobilesync_sync_type_t; -/** Represents an error code. */ -typedef int16_t mobilesync_error_t; - -typedef struct mobilesync_client_private mobilesync_client_private; +typedef struct mobilesync_client_private mobilesync_client_private; /**< \private */ typedef mobilesync_client_private *mobilesync_client_t; /**< The client handle */ +/** Anchors used by the device and computer (structure) */ typedef struct { - char *device_anchor; - char *computer_anchor; + char *device_anchor; /**< device anchor */ + char *computer_anchor; /**< computer anchor */ } mobilesync_anchors; -typedef mobilesync_anchors *mobilesync_anchors_t; /**< Anchors used by the device and computer. */ +/** Anchors used by the device and computer */ +typedef mobilesync_anchors *mobilesync_anchors_t; /* Interface */ -mobilesync_error_t mobilesync_client_new(idevice_t device, uint16_t port, mobilesync_client_t * client); -mobilesync_error_t mobilesync_client_free(mobilesync_client_t client); -mobilesync_error_t mobilesync_receive(mobilesync_client_t client, plist_t *plist); -mobilesync_error_t mobilesync_send(mobilesync_client_t client, plist_t plist); +/** + * Connects to the mobilesync service on the specified device. + * + * @param device The device to connect to. + * @param service The service descriptor returned by lockdownd_start_service. + * @param client Pointer that will be set to a newly allocated + * #mobilesync_client_t upon successful return. + * + * @retval MOBILESYNC_E_SUCCESS on success + * @retval MOBILESYNC_E_INVALID_ARG if one or more parameters are invalid + * @retval DEVICE_LINK_SERVICE_E_BAD_VERSION if the mobilesync version on + * the device is newer. + */ +LIBIMOBILEDEVICE_API mobilesync_error_t mobilesync_client_new(idevice_t device, lockdownd_service_descriptor_t service, mobilesync_client_t * client); + +/** + * Starts a new mobilesync service on the specified device and connects to it. + * + * @param device The device to connect to. + * @param client Pointer that will point to a newly allocated + * mobilesync_client_t upon successful return. Must be freed using + * mobilesync_client_free() after use. + * @param label The label to use for communication. Usually the program name. + * Pass NULL to disable sending the label in requests to lockdownd. + * + * @return MOBILESYNC_E_SUCCESS on success, or an MOBILESYNC_E_* error + * code otherwise. + */ +LIBIMOBILEDEVICE_API mobilesync_error_t mobilesync_client_start_service(idevice_t device, mobilesync_client_t* client, const char* label); + +/** + * Disconnects a mobilesync client from the device and frees up the + * mobilesync client data. + * + * @param client The mobilesync client to disconnect and free. + * + * @retval MOBILESYNC_E_SUCCESS on success + * @retval MOBILESYNC_E_INVALID_ARG if \a client is NULL. + */ +LIBIMOBILEDEVICE_API mobilesync_error_t mobilesync_client_free(mobilesync_client_t client); + + +/** + * Polls the device for mobilesync data. + * + * @param client The mobilesync client + * @param plist A pointer to the location where the plist should be stored + * + * @return an error code + */ +LIBIMOBILEDEVICE_API mobilesync_error_t mobilesync_receive(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. + * + * @param client The mobilesync client + * @param plist The location of the plist to send + * + * @return an error code + */ +LIBIMOBILEDEVICE_API mobilesync_error_t mobilesync_send(mobilesync_client_t client, plist_t plist); + + +/** + * Requests starting synchronization of a data class with the device + * + * @param client The mobilesync client + * @param data_class The data class identifier to sync + * @param 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. + * @param computer_data_class_version The version of the data class storage on the computer + * @param sync_type A pointer to store the sync type reported by the device_anchor + * @param device_data_class_version The version of the data class storage on the device + * @param error_description A pointer to store an error message if reported by the device + * + * @retval MOBILESYNC_E_SUCCESS on success + * @retval MOBILESYNC_E_INVALID_ARG if one of the parameters is invalid + * @retval MOBILESYNC_E_PLIST_ERROR if the received plist is not of valid form + * @retval MOBILESYNC_E_SYNC_REFUSED if the device refused to sync + * @retval MOBILESYNC_E_CANCELLED if the device explicitly cancelled the + * sync request + */ +LIBIMOBILEDEVICE_API 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); + +/** + * Cancels a running synchronization session with a device at any time. + * + * @param client The mobilesync client + * @param reason The reason to supply to the device for cancelling + * + * @retval MOBILESYNC_E_SUCCESS on success + * @retval MOBILESYNC_E_INVALID_ARG if one of the parameters is invalid + */ +LIBIMOBILEDEVICE_API mobilesync_error_t mobilesync_cancel(mobilesync_client_t client, const char* reason); + +/** + * Finish a synchronization session of a data class on the device. + * A session must have previously been started using mobilesync_start(). + * + * @param client The mobilesync client + * + * @retval MOBILESYNC_E_SUCCESS on success + * @retval MOBILESYNC_E_INVALID_ARG if one of the parameters is invalid + * @retval MOBILESYNC_E_PLIST_ERROR if the received plist is not of valid + * form + */ +LIBIMOBILEDEVICE_API mobilesync_error_t mobilesync_finish(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. + * + * @param client The mobilesync client + * + * @retval MOBILESYNC_E_SUCCESS on success + * @retval MOBILESYNC_E_INVALID_ARG if one of the parameters is invalid + */ +LIBIMOBILEDEVICE_API mobilesync_error_t mobilesync_get_all_records_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. + * + * @param client The mobilesync client + * + * @retval MOBILESYNC_E_SUCCESS on success + * @retval MOBILESYNC_E_INVALID_ARG if one of the parameters is invalid + */ +LIBIMOBILEDEVICE_API mobilesync_error_t mobilesync_get_changes_from_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. + * + * @param client The mobilesync client + * + * @retval MOBILESYNC_E_SUCCESS on success + * @retval MOBILESYNC_E_INVALID_ARG if one of the parameters is invalid + * @retval MOBILESYNC_E_PLIST_ERROR if the received plist is not of valid form + */ +LIBIMOBILEDEVICE_API mobilesync_error_t mobilesync_clear_all_records_on_device(mobilesync_client_t client); -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); -mobilesync_error_t mobilesync_cancel(mobilesync_client_t client, const char* reason); -mobilesync_error_t mobilesync_finish(mobilesync_client_t client); -mobilesync_error_t mobilesync_get_all_records_from_device(mobilesync_client_t client); -mobilesync_error_t mobilesync_get_changes_from_device(mobilesync_client_t client); -mobilesync_error_t mobilesync_clear_all_records_on_device(mobilesync_client_t client); +/** + * Receives changed entitites of the currently set data class from the device + * + * @param client The mobilesync client + * @param entities A pointer to store the changed entity records as a PLIST_DICT + * @param is_last_record A pointer to store a flag indicating if this submission is the last one + * @param actions A pointer to additional flags the device is sending or NULL to ignore + * + * @retval MOBILESYNC_E_SUCCESS on success + * @retval MOBILESYNC_E_INVALID_ARG if one of the parameters is invalid + * @retval MOBILESYNC_E_CANCELLED if the device explicitly cancelled the + * session + */ +LIBIMOBILEDEVICE_API mobilesync_error_t mobilesync_receive_changes(mobilesync_client_t client, plist_t *entities, uint8_t *is_last_record, plist_t *actions); + +/** + * Acknowledges to the device that the changes have been merged on the computer + * + * @param client The mobilesync client + * + * @retval MOBILESYNC_E_SUCCESS on success + * @retval MOBILESYNC_E_INVALID_ARG if one of the parameters is invalid + */ +LIBIMOBILEDEVICE_API mobilesync_error_t mobilesync_acknowledge_changes_from_device(mobilesync_client_t client); -mobilesync_error_t mobilesync_receive_changes(mobilesync_client_t client, plist_t *entities, uint8_t *is_last_record, plist_t *actions); -mobilesync_error_t mobilesync_acknowledge_changes_from_device(mobilesync_client_t client); -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. + * + * @param client The mobilesync client + * + * @retval MOBILESYNC_E_SUCCESS on success + * @retval MOBILESYNC_E_INVALID_ARG if one of the parameters is invalid + * @retval MOBILESYNC_E_PLIST_ERROR if the received plist is not of valid form + * @retval MOBILESYNC_E_WRONG_DIRECTION if the current sync direction does + * not permit this call + * @retval MOBILESYNC_E_CANCELLED if the device explicitly cancelled the + * session + * @retval MOBILESYNC_E_NOT_READY if the device is not ready to start + * receiving any changes + */ +LIBIMOBILEDEVICE_API mobilesync_error_t mobilesync_ready_to_send_changes_from_computer(mobilesync_client_t client); + + +/** + * Sends changed entities of the currently set data class to the device + * + * @param client The mobilesync client + * @param entities The changed entity records as a PLIST_DICT + * @param is_last_record A flag indicating if this submission is the last one + * @param actions Additional actions for the device created with mobilesync_actions_new() + * or NULL if no actions should be passed + * + * @retval MOBILESYNC_E_SUCCESS on success + * @retval MOBILESYNC_E_INVALID_ARG if one of the parameters is invalid, + * @retval MOBILESYNC_E_WRONG_DIRECTION if the current sync direction does + * not permit this call + */ +LIBIMOBILEDEVICE_API mobilesync_error_t mobilesync_send_changes(mobilesync_client_t client, plist_t entities, uint8_t is_last_record, plist_t actions); -mobilesync_error_t mobilesync_send_changes(mobilesync_client_t client, plist_t entities, uint8_t is_last_record, plist_t actions); -mobilesync_error_t mobilesync_remap_identifiers(mobilesync_client_t client, plist_t *mapping); +/** + * Receives any remapped identifiers reported after the device merged submitted changes. + * + * @param client The mobilesync client + * @param mapping A pointer to an array plist containing a dict of identifier remappings + * + * @retval MOBILESYNC_E_SUCCESS on success + * @retval MOBILESYNC_E_INVALID_ARG if one of the parameters is invalid + * @retval MOBILESYNC_E_PLIST_ERROR if the received plist is not of valid + * form + * @retval MOBILESYNC_E_WRONG_DIRECTION if the current sync direction does + * not permit this call + * @retval MOBILESYNC_E_CANCELLED if the device explicitly cancelled the + * session + */ +LIBIMOBILEDEVICE_API mobilesync_error_t mobilesync_remap_identifiers(mobilesync_client_t client, plist_t *mapping); /* Helper */ -mobilesync_anchors_t mobilesync_anchors_new(const char *device_anchor, const char *computer_anchor); -void mobilesync_anchors_free(mobilesync_anchors_t anchors); -plist_t mobilesync_actions_new(); -void mobilesync_actions_add(plist_t actions, ...) G_GNUC_NULL_TERMINATED; -void mobilesync_actions_free(plist_t actions); +/** + * Allocates memory for a new anchors struct initialized with the passed anchors. + * + * @param 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. + * @param computer_anchor An arbitrary string to use as anchor for the computer. + * + * @return A new #mobilesync_anchors_t struct. Must be freed using mobilesync_anchors_free(). + */ +LIBIMOBILEDEVICE_API mobilesync_anchors_t mobilesync_anchors_new(const char *device_anchor, const char *computer_anchor); + +/** + * Free memory used by anchors. + * + * @param anchors The anchors to free. + */ +LIBIMOBILEDEVICE_API void mobilesync_anchors_free(mobilesync_anchors_t anchors); + + +/** + * Create a new actions plist to use in mobilesync_send_changes(). + * + * @return A new plist_t of type PLIST_DICT. + */ +LIBIMOBILEDEVICE_API plist_t mobilesync_actions_new(void); + +/** + * Add one or more new key:value pairs to the given actions plist. + * + * @param actions The actions to modify. + * @param ... 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. + */ +LIBIMOBILEDEVICE_API void mobilesync_actions_add(plist_t actions, ...); + +/** + * Free actions plist. + * + * @param actions The actions plist to free. Does nothing if NULL is passed. + */ +LIBIMOBILEDEVICE_API void mobilesync_actions_free(plist_t actions); #ifdef __cplusplus } |