1 files changed, 124 insertions, 17 deletions

diff --git a/include/libimobiledevice/file_relay.h b/include/libimobiledevice/file_relay.h
index 52d4758..00773b8 100644
--- a/include/libimobiledevice/file_relay.h
+++ b/include/libimobiledevice/file_relay.h
@@ -3,6 +3,8 @@
  * @brief Retrieve compressed CPIO archives.
  * \internal
  *
+ * Copyright (c) 2010-2014 Martin Szulecki All Rights Reserved.
+ * Copyright (c) 2014 Aaron Burghardt All Rights Reserved.
  * Copyright (c) 2010 Nikias Bassen All Rights Reserved.
  *
  * This library is free software; you can redistribute it and/or
@@ -28,29 +30,134 @@ extern "C" {
 #endif
 
 #include <libimobiledevice/libimobiledevice.h>
+#include <libimobiledevice/lockdown.h>
 
-/** @name Error Codes */
-/*@{*/
-#define FILE_RELAY_E_SUCCESS                0
-#define FILE_RELAY_E_INVALID_ARG           -1
-#define FILE_RELAY_E_PLIST_ERROR           -2
-#define FILE_RELAY_E_MUX_ERROR             -3
-#define FILE_RELAY_E_INVALID_SOURCE        -4
-#define FILE_RELAY_E_STAGING_EMPTY         -5
+/** Service identifier passed to lockdownd_start_service() to start the file relay service */
+#define FILE_RELAY_SERVICE_NAME "com.apple.mobile.file_relay"
 
-#define FILE_RELAY_E_UNKNOWN_ERROR       -256
-/*@}*/
+/** Error Codes */
+typedef enum {
+        FILE_RELAY_E_SUCCESS           =  0,
+        FILE_RELAY_E_INVALID_ARG       = -1,
+        FILE_RELAY_E_PLIST_ERROR       = -2,
+        FILE_RELAY_E_MUX_ERROR         = -3,
+        FILE_RELAY_E_INVALID_SOURCE    = -4,
+        FILE_RELAY_E_STAGING_EMPTY     = -5,
+        FILE_RELAY_E_PERMISSION_DENIED = -6,
+        FILE_RELAY_E_UNKNOWN_ERROR     = -256
+} file_relay_error_t;
 
-/** Represents an error code. */
-typedef int16_t file_relay_error_t;
-
-typedef struct file_relay_client_private file_relay_client_private;
+typedef struct file_relay_client_private file_relay_client_private; /**< \private */
 typedef file_relay_client_private *file_relay_client_t; /**< The client handle. */
 
-file_relay_error_t file_relay_client_new(idevice_t device, uint16_t port, file_relay_client_t *client);
-file_relay_error_t file_relay_client_free(file_relay_client_t client);
+/**
+ * Connects to the file_relay service on the specified device.
+ *
+ * @param device The device to connect to.
+ * @param service The service descriptor returned by lockdownd_start_service.
+ * @param client Reference that will point to a newly allocated
+ *     file_relay_client_t upon successful return.
+ *
+ * @return FILE_RELAY_E_SUCCESS on success,
+ *     FILE_RELAY_E_INVALID_ARG when one of the parameters is invalid,
+ *     or FILE_RELAY_E_MUX_ERROR when the connection failed.
+ */
+LIBIMOBILEDEVICE_API file_relay_error_t file_relay_client_new(idevice_t device, lockdownd_service_descriptor_t service, file_relay_client_t *client);
+
+/**
+ * Starts a new file_relay 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
+ *     file_relay_client_t upon successful return. Must be freed using
+ *     file_relay_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 FILE_RELAY_E_SUCCESS on success, or an FILE_RELAY_E_* error
+ *     code otherwise.
+ */
+LIBIMOBILEDEVICE_API file_relay_error_t file_relay_client_start_service(idevice_t device, file_relay_client_t* client, const char* label);
+
+/**
+ * Disconnects a file_relay client from the device and frees up the file_relay
+ * client data.
+ *
+ * @param client The file_relay client to disconnect and free.
+ *
+ * @return FILE_RELAY_E_SUCCESS on success,
+ *     FILE_RELAY_E_INVALID_ARG when one of client or client->parent
+ *     is invalid, or FILE_RELAY_E_UNKNOWN_ERROR when the was an error
+ *     freeing the parent property_list_service client.
+ */
+LIBIMOBILEDEVICE_API file_relay_error_t file_relay_client_free(file_relay_client_t client);
+
 
-file_relay_error_t file_relay_request_sources(file_relay_client_t client, const char **sources, idevice_connection_t *connection);
+/**
+ * Request data for the given sources.
+ *
+ * @param client The connected file_relay client.
+ * @param sources A NULL-terminated list of sources to retrieve.
+ *     Valid sources are:
+ *     - AppleSupport
+ *     - Network
+ *     - VPN
+ *     - WiFi
+ *     - UserDatabases
+ *     - CrashReporter
+ *     - tmp
+ *     - SystemConfiguration
+ * @param connection The connection that has to be used for receiving the
+ *     data using idevice_connection_receive(). The connection will be closed
+ *     automatically by the device, but use file_relay_client_free() to clean
+ *     up properly.
+  *
+ * @note WARNING: Don't call this function without reading the data afterwards.
+ *     A directory mobile_file_relay.XXXX used for creating the archive will
+ *     remain in the /tmp directory otherwise.
+ *
+ * @return FILE_RELAY_E_SUCCESS on succes, FILE_RELAY_E_INVALID_ARG when one or
+ *     more parameters are invalid, FILE_RELAY_E_MUX_ERROR if a communication
+ *     error occurs, FILE_RELAY_E_PLIST_ERROR when the received result is NULL
+ *     or is not a valid plist, FILE_RELAY_E_INVALID_SOURCE if one or more
+ *     sources are invalid, FILE_RELAY_E_STAGING_EMPTY if no data is available
+ *     for the given sources, or FILE_RELAY_E_UNKNOWN_ERROR otherwise.
+ */
+LIBIMOBILEDEVICE_API file_relay_error_t file_relay_request_sources(file_relay_client_t client, const char **sources, idevice_connection_t *connection);
+
+/**
+ * Request data for the given sources. Calls file_relay_request_sources_timeout() with
+ * a timeout of 60000 milliseconds (60 seconds).
+ *
+ * @param client The connected file_relay client.
+ * @param sources A NULL-terminated list of sources to retrieve.
+ *     Valid sources are:
+ *     - AppleSupport
+ *     - Network
+ *     - VPN
+ *     - WiFi
+ *     - UserDatabases
+ *     - CrashReporter
+ *     - tmp
+ *     - SystemConfiguration
+ * @param connection The connection that has to be used for receiving the
+ *     data using idevice_connection_receive(). The connection will be closed
+ *     automatically by the device, but use file_relay_client_free() to clean
+ *     up properly.
+ * @param timeout Maximum time in milliseconds to wait for data.
+ *
+ * @note WARNING: Don't call this function without reading the data afterwards.
+ *     A directory mobile_file_relay.XXXX used for creating the archive will
+ *     remain in the /tmp directory otherwise.
+ *
+ * @return FILE_RELAY_E_SUCCESS on succes, FILE_RELAY_E_INVALID_ARG when one or
+ *     more parameters are invalid, FILE_RELAY_E_MUX_ERROR if a communication
+ *     error occurs, FILE_RELAY_E_PLIST_ERROR when the received result is NULL
+ *     or is not a valid plist, FILE_RELAY_E_INVALID_SOURCE if one or more
+ *     sources are invalid, FILE_RELAY_E_STAGING_EMPTY if no data is available
+ *     for the given sources, or FILE_RELAY_E_UNKNOWN_ERROR otherwise.
+ */
+LIBIMOBILEDEVICE_API file_relay_error_t file_relay_request_sources_timeout(file_relay_client_t client, const char **sources, idevice_connection_t *connection, unsigned int timeout);
 
 #ifdef __cplusplus
 }