diff options
Diffstat (limited to 'include/libimobiledevice/file_relay.h')
| -rw-r--r-- | include/libimobiledevice/file_relay.h | 141 |
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 } |