From d5e18975a3905682f5db090b4ddffeafb4f5fde4 Mon Sep 17 00:00:00 2001 From: Martin Szulecki Date: Wed, 19 May 2010 23:48:37 +0200 Subject: Implement restored API --- AUTHORS | 2 +- include/libimobiledevice/restore.h | 71 +++++++ src/Makefile.am | 3 +- src/restore.c | 408 +++++++++++++++++++++++++++++++++++++ src/restore.h | 36 ++++ 5 files changed, 518 insertions(+), 2 deletions(-) create mode 100644 include/libimobiledevice/restore.h create mode 100644 src/restore.c create mode 100644 src/restore.h diff --git a/AUTHORS b/AUTHORS index a8820b1..de03fac 100644 --- a/AUTHORS +++ b/AUTHORS @@ -2,8 +2,8 @@ Bastien Nocera Bryan Forbes Christophe Fergeau Ingmar Vanhassel -JonathanBeck Jonathan Beck +Joshua Hill Martin Aumueller Martin Szulecki Matt Colyer diff --git a/include/libimobiledevice/restore.h b/include/libimobiledevice/restore.h new file mode 100644 index 0000000..c4b5916 --- /dev/null +++ b/include/libimobiledevice/restore.h @@ -0,0 +1,71 @@ +/** + * @file libimobiledevice/restore.h + * @brief Implementation to communicate with the restore device daemon + * \internal + * + * Copyright (c) 2010 Joshua Hill. All Rights Reserved. + * + * This library is free software; you can redistribute it and/or + * modify it under the terms of the GNU Lesser General Public + * License as published by the Free Software Foundation; either + * version 2.1 of the License, or (at your option) any later version. + * + * This library is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + * Lesser General Public License for more details. + * + * You should have received a copy of the GNU Lesser General Public + * License along with this library; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +#ifndef RESTORE_H +#define RESTORE_H + +#ifdef __cplusplus +extern "C" { +#endif + +#include + +/** @name Error Codes */ +/*@{*/ +#define RESTORE_E_SUCCESS 0 +#define RESTORE_E_INVALID_ARG -1 +#define RESTORE_E_INVALID_CONF -2 +#define RESTORE_E_PLIST_ERROR -3 +#define RESTORE_E_DICT_ERROR -4 +#define RESTORE_E_NOT_ENOUGH_DATA -5 +#define RESTORE_E_MUX_ERROR -6 +#define RESTORE_E_START_RESTORE_FAILED -7 + +#define RESTORE_E_UNKNOWN_ERROR -256 +/*@}*/ + +/** Represents an error code. */ +typedef int16_t restored_error_t; + +typedef struct restored_client_private restored_client_private; +typedef restored_client_private *restored_client_t; /**< The client handle. */ + +/* Interface */ +restored_error_t restored_client_new(idevice_t device, restored_client_t *client, const char *label); +restored_error_t restored_client_free(restored_client_t client); + +restored_error_t restored_query_type(restored_client_t client, char **type, uint64_t *version); +restored_error_t restored_send(restored_client_t client, plist_t plist); +restored_error_t restored_receive(restored_client_t client, plist_t *plist); +restored_error_t restored_goodbye(restored_client_t client); + +restored_error_t restored_start_restore(restored_client_t client); +restored_error_t restored_reboot(restored_client_t client); + +/* Helper */ +void restored_client_set_label(restored_client_t client, const char *label); + +#ifdef __cplusplus +} +#endif + +#endif diff --git a/src/Makefile.am b/src/Makefile.am index 5fa37d7..338daf2 100644 --- a/src/Makefile.am +++ b/src/Makefile.am @@ -19,4 +19,5 @@ libimobiledevice_la_SOURCES = idevice.c idevice.h \ mobile_image_mounter.c mobile_image_mounter.h\ screenshotr.c screenshotr.h\ mobilesync.c mobilesync.h\ - mobilebackup.c mobilebackup.h + mobilebackup.c mobilebackup.h\ + restore.c restore.h diff --git a/src/restore.c b/src/restore.c new file mode 100644 index 0000000..8acefef --- /dev/null +++ b/src/restore.c @@ -0,0 +1,408 @@ +/* + * restore.c + * com.apple.mobile.restored service implementation. + * + * Copyright (c) 2010 Joshua Hill. All Rights Reserved. + * + * This library is free software; you can redistribute it and/or + * modify it under the terms of the GNU Lesser General Public + * License as published by the Free Software Foundation; either + * version 2.1 of the License, or (at your option) any later version. + * + * This library is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + * Lesser General Public License for more details. + * + * You should have received a copy of the GNU Lesser General Public + * License along with this library; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +#include +#include +#include +#include +#include +#include + +#include "property_list_service.h" +#include "restore.h" +#include "idevice.h" +#include "debug.h" + +#define RESULT_SUCCESS 0 +#define RESULT_FAILURE 1 + +/** + * Internally used function for checking the result from restore's answer + * plist to a previously sent request. + * + * @param dict The plist to evaluate. + * @param query_match Name of the request to match. + * + * @return RESULT_SUCCESS when the result is 'Success', + * RESULT_FAILURE when the result is 'Failure', + * or a negative value if an error occured during evaluation. + */ +static int restored_check_result(plist_t dict) +{ + int ret = -1; + plist_t result_node = plist_dict_get_item(dict, "Result"); + if (!result_node) { + return ret; + } + + plist_type result_type = plist_get_node_type(result_node); + + if (result_type == PLIST_STRING) { + + char *result_value = NULL; + + plist_get_string_val(result_node, &result_value); + + if (result_value) { + if (!strcmp(result_value, "Success")) { + ret = RESULT_SUCCESS; + } else if (!strcmp(result_value, "Failure")) { + ret = RESULT_FAILURE; + } else { + debug_info("ERROR: unknown result value '%s'", result_value); + } + } + if (result_value) + free(result_value); + } + return ret; +} + +/** + * Adds a label key with the passed value to a plist dict node. + * + * @param plist The plist to add the key to + * @param label The value for the label key + * + */ +static void plist_dict_add_label(plist_t plist, const char *label) +{ + if (plist && label) { + if (plist_get_node_type(plist) == PLIST_DICT) + plist_dict_insert_item(plist, "Label", plist_new_string(label)); + } +} + +/** + * Closes the restored client session if one is running and frees up the + * restored_client struct. + * + * @param client The restore client + * + * @return RESTORE_E_SUCCESS on success, NP_E_INVALID_ARG when client is NULL + */ +restored_error_t restored_client_free(restored_client_t client) +{ + if (!client) + return RESTORE_E_INVALID_ARG; + restored_error_t ret = RESTORE_E_UNKNOWN_ERROR; + + if (client->parent) { + restored_goodbye(client); + + if (property_list_service_client_free(client->parent) == PROPERTY_LIST_SERVICE_E_SUCCESS) { + ret = RESTORE_E_SUCCESS; + } + } + + if (client->uuid) { + free(client->uuid); + } + if (client->label) { + free(client->label); + } + + free(client); + return ret; +} + +/** + * Sets the label to send for requests to restored. + * + * @param client The restore client + * @param label The label to set or NULL to disable sending a label + * + */ +void restored_client_set_label(restored_client_t client, const char *label) +{ + if (client) { + if (client->label) + free(client->label); + + client->label = (label != NULL) ? strdup(label): NULL; + } +} + +/** + * Receives a plist from restored. + * + * @param client The restored client + * @param plist The plist to store the received data + * + * @return RESTORE_E_SUCCESS on success, NP_E_INVALID_ARG when client or + * plist is NULL + */ +restored_error_t restored_receive(restored_client_t client, plist_t *plist) +{ + if (!client || !plist || (plist && *plist)) + return RESTORE_E_INVALID_ARG; + restored_error_t ret = RESTORE_E_SUCCESS; + property_list_service_error_t err; + + err = property_list_service_receive_plist(client->parent, plist); + if (err != PROPERTY_LIST_SERVICE_E_SUCCESS) { + ret = RESTORE_E_UNKNOWN_ERROR; + } + + if (!*plist) + ret = RESTORE_E_PLIST_ERROR; + + return ret; +} + +/** + * Sends a plist to restored. + * + * @note This function is low-level and should only be used if you need to send + * a new type of message. + * + * @param client The restored client + * @param plist The plist to send + * + * @return RESTORE_E_SUCCESS on success, NP_E_INVALID_ARG when client or + * plist is NULL + */ +restored_error_t restored_send(restored_client_t client, plist_t plist) +{ + if (!client || !plist) + return RESTORE_E_INVALID_ARG; + + restored_error_t ret = RESTORE_E_SUCCESS; + idevice_error_t err; + + err = property_list_service_send_xml_plist(client->parent, plist); + if (err != PROPERTY_LIST_SERVICE_E_SUCCESS) { + ret = RESTORE_E_UNKNOWN_ERROR; + } + return ret; +} + +/** + * Query the type of the service daemon. Depending on whether the device is + * queried in normal mode or restore mode, different types will be returned. + * + * @param client The restored client + * @param type The type returned by the service daemon. Pass NULL to ignore. + * @param version The restore protocol version. Pass NULL to ignore. + * + * @return RESTORE_E_SUCCESS on success, NP_E_INVALID_ARG when client is NULL + */ +restored_error_t restored_query_type(restored_client_t client, char **type, uint64_t *version) +{ + if (!client) + return RESTORE_E_INVALID_ARG; + + restored_error_t ret = RESTORE_E_UNKNOWN_ERROR; + + plist_t dict = plist_new_dict(); + plist_dict_add_label(dict, client->label); + plist_dict_insert_item(dict,"Request", plist_new_string("QueryType")); + + debug_info("called"); + ret = restored_send(client, dict); + + plist_free(dict); + dict = NULL; + + ret = restored_receive(client, &dict); + + if (RESTORE_E_SUCCESS != ret) + return ret; + + ret = RESTORE_E_UNKNOWN_ERROR; + if (restored_check_result(dict) == RESULT_SUCCESS) { + /* return the type if requested */ + if (type != NULL) { + plist_t type_node = plist_dict_get_item(dict, "Type"); + plist_get_string_val(type_node, type); + } + debug_info("success with type %s", *type); + ret = RESTORE_E_SUCCESS; + + /* fetch the restore protocol version */ + plist_t version_node = plist_dict_get_item(dict, "RestoreProtocolVersion"); + if (version_node && version) { + plist_get_uint_val(version_node, version); + debug_info("restored protocol version %llu", *version); + ret = RESTORE_E_SUCCESS; + } else + ret = RESTORE_E_UNKNOWN_ERROR; + + } + plist_free(dict); + dict = NULL; + + return ret; +} + +/** + * Creates a new restored client for the device. + * + * @param device The device to create a restored client for + * @param client The pointer to the location of the new restored_client + * @param label The label to use for communication. Usually the program name. + * + * @return RESTORE_E_SUCCESS on success, NP_E_INVALID_ARG when client is NULL + */ +restored_error_t restored_client_new(idevice_t device, restored_client_t *client, const char *label) +{ + if (!client) + return RESTORE_E_INVALID_ARG; + + restored_error_t ret = RESTORE_E_SUCCESS; + + property_list_service_client_t plistclient = NULL; + if (property_list_service_client_new(device, 0xf27e, &plistclient) != PROPERTY_LIST_SERVICE_E_SUCCESS) { + debug_info("could not connect to restored (device %s)", device->uuid); + return RESTORE_E_MUX_ERROR; + } + + restored_client_t client_loc = (restored_client_t) malloc(sizeof(struct restored_client_private)); + client_loc->parent = plistclient; + client_loc->uuid = NULL; + client_loc->label = NULL; + if (label != NULL) + client_loc->label = strdup(label); + + ret = idevice_get_uuid(device, &client_loc->uuid); + if (RESTORE_E_SUCCESS != ret) { + debug_info("failed to get device uuid."); + } + debug_info("device uuid: %s", client_loc->uuid); + + if (RESTORE_E_SUCCESS == ret) { + *client = client_loc; + } else { + restored_client_free(client_loc); + } + + return ret; +} + +/** + * Sends the Goodbye request to restored signaling the end of communication. + * + * @param client The restore client + * + * @return RESTORE_E_SUCCESS on success, NP_E_INVALID_ARG when client is NULL, + * RESTORE_E_PLIST_ERROR if the device did not acknowledge the request + */ +restored_error_t restored_goodbye(restored_client_t client) +{ + if (!client) + return RESTORE_E_INVALID_ARG; + + restored_error_t ret = RESTORE_E_UNKNOWN_ERROR; + + plist_t dict = plist_new_dict(); + plist_dict_add_label(dict, client->label); + plist_dict_insert_item(dict,"Request", plist_new_string("Goodbye")); + + debug_info("called"); + + ret = restored_send(client, dict); + plist_free(dict); + dict = NULL; + + ret = restored_receive(client, &dict); + if (!dict) { + debug_info("did not get goodbye response back"); + return RESTORE_E_PLIST_ERROR; + } + + if (restored_check_result(dict) == RESULT_SUCCESS) { + debug_info("success"); + ret = RESTORE_E_SUCCESS; + } + plist_free(dict); + dict = NULL; + return ret; +} + +/** + * Requests to start a restore and retrieve it's port on success. + * + * @param client The restored client + * + * @return RESTORE_E_SUCCESS on success, NP_E_INVALID_ARG if a parameter + * is NULL, RESTORE_E_START_RESTORE_FAILED if the request fails + */ +restored_error_t restored_start_restore(restored_client_t client) +{ + if (!client) + return RESTORE_E_INVALID_ARG; + + plist_t dict = NULL; + restored_error_t ret = RESTORE_E_UNKNOWN_ERROR; + + dict = plist_new_dict(); + plist_dict_add_label(dict, client->label); + plist_dict_insert_item(dict,"Request", plist_new_string("StartRestore")); + plist_dict_insert_item(dict,"RestoreProtocolVersion", plist_new_uint(2)); + + /* send to device */ + ret = restored_send(client, dict); + plist_free(dict); + dict = NULL; + + return ret; +} + +/** + * Requests device to reboot. + * + * @param client The restored client + * + * @return RESTORE_E_SUCCESS on success, NP_E_INVALID_ARG if a parameter + * is NULL + */ +restored_error_t restored_reboot(restored_client_t client) +{ + if (!client) + return RESTORE_E_INVALID_ARG; + + plist_t dict = NULL; + restored_error_t ret = RESTORE_E_UNKNOWN_ERROR; + + dict = plist_new_dict(); + plist_dict_add_label(dict, client->label); + plist_dict_insert_item(dict,"Request", plist_new_string("Reboot")); + + /* send to device */ + ret = restored_send(client, dict); + plist_free(dict); + dict = NULL; + + if (RESTORE_E_SUCCESS != ret) + return ret; + + ret = restored_receive(client, &dict); + if (RESTORE_E_SUCCESS != ret) + return ret; + + if (!dict) + return RESTORE_E_PLIST_ERROR; + + plist_free(dict); + dict = NULL; + return ret; +} + diff --git a/src/restore.h b/src/restore.h new file mode 100644 index 0000000..8b4cbbb --- /dev/null +++ b/src/restore.h @@ -0,0 +1,36 @@ +/* + * restore.h + * Defines restore stuff, like the client struct. + * + * Copyright (c) 2010 Joshua Hill. All Rights Reserved. + * + * This library is free software; you can redistribute it and/or + * modify it under the terms of the GNU Lesser General Public + * License as published by the Free Software Foundation; either + * version 2.1 of the License, or (at your option) any later version. + * + * This library is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + * Lesser General Public License for more details. + * + * You should have received a copy of the GNU Lesser General Public + * License along with this library; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +#ifndef RESTORED_H +#define RESTORED_H + +#include + +#include "libimobiledevice/restore.h" +#include "property_list_service.h" + +struct restored_client_private { + property_list_service_client_t parent; + char *uuid; + char *label; +}; + +#endif -- cgit v1.1-32-gdbae