1 files changed, 136 insertions, 29 deletions

diff --git a/include/libimobiledevice/restore.h b/include/libimobiledevice/restore.h
index 9c30b03..859dc98 100644
--- a/include/libimobiledevice/restore.h
+++ b/include/libimobiledevice/restore.h
@@ -1,8 +1,10 @@
 /**
  * @file libimobiledevice/restore.h
  * @brief Initiate restore process or reboot device.
+ * @note This service is only available if the device is in restore mode.
  * \internal
  *
+ * Copyright (c) 2010-2014 Martin Szulecki All Rights Reserved.
  * Copyright (c) 2010 Joshua Hill. All Rights Reserved.
  *
  * This library is free software; you can redistribute it and/or
@@ -20,8 +22,8 @@
  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
  */
 
-#ifndef RESTORE_H
-#define RESTORE_H
+#ifndef IRESTORE_H
+#define IRESTORE_H
 
 #ifdef __cplusplus
 extern "C" {
@@ -29,41 +31,146 @@ extern "C" {
 
 #include <libimobiledevice/libimobiledevice.h>
 
-/** @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
+/** Error Codes */
+typedef enum {
+        RESTORE_E_SUCCESS              =  0,
+        RESTORE_E_INVALID_ARG          = -1,
+        RESTORE_E_PLIST_ERROR          = -2,
+        RESTORE_E_MUX_ERROR            = -3,
+        RESTORE_E_NOT_ENOUGH_DATA      = -4,
+        RESTORE_E_RECEIVE_TIMEOUT      = -5,
+        RESTORE_E_UNKNOWN_ERROR        = -256
+} restored_error_t;
 
-#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 struct restored_client_private restored_client_private; /**< \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_get_value(restored_client_t client, const char *key, plist_t *value) ;
-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);
+/**
+ * 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, RESTORE_E_INVALID_ARG when client is NULL
+ */
+LIBIMOBILEDEVICE_API restored_error_t restored_client_new(idevice_t device, restored_client_t *client, const char *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, RESTORE_E_INVALID_ARG when client is NULL
+ */
+LIBIMOBILEDEVICE_API restored_error_t restored_client_free(restored_client_t client);
+
+
+/**
+ * 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, RESTORE_E_INVALID_ARG when client is NULL
+ */
+LIBIMOBILEDEVICE_API restored_error_t restored_query_type(restored_client_t client, char **type, uint64_t *version);
+
+/**
+ * Queries a value from the device specified by a key.
+ *
+ * @param client An initialized restored client.
+ * @param key The key name to request
+ * @param value A plist node representing the result value node
+ *
+ * @return RESTORE_E_SUCCESS on success, RESTORE_E_INVALID_ARG when client is NULL, RESTORE_E_PLIST_ERROR if value for key can't be found
+ */
+LIBIMOBILEDEVICE_API restored_error_t restored_query_value(restored_client_t client, const char *key, plist_t *value);
+
+/**
+ * Retrieves a value from information plist specified by a key.
+ *
+ * @param client An initialized restored client.
+ * @param key The key name to request or NULL to query for all keys
+ * @param value A plist node representing the result value node
+ *
+ * @return RESTORE_E_SUCCESS on success, RESTORE_E_INVALID_ARG when client is NULL, RESTORE_E_PLIST_ERROR if value for key can't be found
+ */
+LIBIMOBILEDEVICE_API restored_error_t restored_get_value(restored_client_t client, const char *key, plist_t *value) ;
+
+/**
+ * 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, RESTORE_E_INVALID_ARG when client or
+ *  plist is NULL
+ */
+LIBIMOBILEDEVICE_API restored_error_t restored_send(restored_client_t client, plist_t plist);
+
+/**
+ * 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, RESTORE_E_INVALID_ARG when client or
+ *  plist is NULL
+ */
+LIBIMOBILEDEVICE_API restored_error_t restored_receive(restored_client_t client, plist_t *plist);
+
+/**
+ * Sends the Goodbye request to restored signaling the end of communication.
+ *
+ * @param client The restore client
+ *
+ * @return RESTORE_E_SUCCESS on success, RESTORE_E_INVALID_ARG when client is NULL,
+ *  RESTORE_E_PLIST_ERROR if the device did not acknowledge the request
+ */
+LIBIMOBILEDEVICE_API 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);
+
+/**
+ * Requests to start a restore and retrieve it's port on success.
+ *
+ * @param client The restored client
+ * @param options PLIST_DICT with options for the restore process or NULL
+ * @param version the restore protocol version, see restored_query_type()
+ *
+ * @return RESTORE_E_SUCCESS on success, RESTORE_E_INVALID_ARG if a parameter
+ *  is NULL, RESTORE_E_START_RESTORE_FAILED if the request fails
+ */
+LIBIMOBILEDEVICE_API restored_error_t restored_start_restore(restored_client_t client, plist_t options, uint64_t version);
+
+/**
+ * Requests device to reboot.
+ *
+ * @param client The restored client
+ *
+ * @return RESTORE_E_SUCCESS on success, RESTORE_E_INVALID_ARG if a parameter
+ *  is NULL
+ */
+LIBIMOBILEDEVICE_API restored_error_t restored_reboot(restored_client_t client);
 
 /* Helper */
-void restored_client_set_label(restored_client_t client, const char *label);
+
+/**
+ * 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
+ *
+ */
+LIBIMOBILEDEVICE_API void restored_client_set_label(restored_client_t client, const char *label);
 
 #ifdef __cplusplus
 }