diff options
Diffstat (limited to 'include/libimobiledevice/afc.h')
| -rw-r--r-- | include/libimobiledevice/afc.h | 384 |
1 files changed, 323 insertions, 61 deletions
diff --git a/include/libimobiledevice/afc.h b/include/libimobiledevice/afc.h index 8d47696..4ad3dbd 100644 --- a/include/libimobiledevice/afc.h +++ b/include/libimobiledevice/afc.h @@ -1,9 +1,10 @@ /** * @file libimobiledevice/afc.h - * @brief Access the filesystem. + * @brief Access the filesystem on the device. * \internal * - * Copyright (c) 2009 Nikias Bassen All Rights Reserved. + * Copyright (c) 2010-2014 Martin Szulecki All Rights Reserved. + * Copyright (c) 2009-2010 Nikias Bassen 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 @@ -20,50 +21,51 @@ * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA */ -#ifndef AFC_H -#define AFC_H +#ifndef IAFC_H +#define IAFC_H #ifdef __cplusplus extern "C" { #endif #include <libimobiledevice/libimobiledevice.h> +#include <libimobiledevice/lockdown.h> -/** @name Error Codes */ -/*@{*/ -#define AFC_E_SUCCESS 0 -#define AFC_E_UNKNOWN_ERROR 1 -#define AFC_E_OP_HEADER_INVALID 2 -#define AFC_E_NO_RESOURCES 3 -#define AFC_E_READ_ERROR 4 -#define AFC_E_WRITE_ERROR 5 -#define AFC_E_UNKNOWN_PACKET_TYPE 6 -#define AFC_E_INVALID_ARG 7 -#define AFC_E_OBJECT_NOT_FOUND 8 -#define AFC_E_OBJECT_IS_DIR 9 -#define AFC_E_PERM_DENIED 10 -#define AFC_E_SERVICE_NOT_CONNECTED 11 -#define AFC_E_OP_TIMEOUT 12 -#define AFC_E_TOO_MUCH_DATA 13 -#define AFC_E_END_OF_DATA 14 -#define AFC_E_OP_NOT_SUPPORTED 15 -#define AFC_E_OBJECT_EXISTS 16 -#define AFC_E_OBJECT_BUSY 17 -#define AFC_E_NO_SPACE_LEFT 18 -#define AFC_E_OP_WOULD_BLOCK 19 -#define AFC_E_IO_ERROR 20 -#define AFC_E_OP_INTERRUPTED 21 -#define AFC_E_OP_IN_PROGRESS 22 -#define AFC_E_INTERNAL_ERROR 23 - -#define AFC_E_MUX_ERROR 30 -#define AFC_E_NO_MEM 31 -#define AFC_E_NOT_ENOUGH_DATA 32 -#define AFC_E_DIR_NOT_EMPTY 33 -/*@}*/ - -/** Represents an error code. */ -typedef int16_t afc_error_t; +/** Service identifier passed to lockdownd_start_service() to start the AFC service */ +#define AFC_SERVICE_NAME "com.apple.afc" + +/** Error Codes */ +typedef enum { + AFC_E_SUCCESS = 0, + AFC_E_UNKNOWN_ERROR = 1, + AFC_E_OP_HEADER_INVALID = 2, + AFC_E_NO_RESOURCES = 3, + AFC_E_READ_ERROR = 4, + AFC_E_WRITE_ERROR = 5, + AFC_E_UNKNOWN_PACKET_TYPE = 6, + AFC_E_INVALID_ARG = 7, + AFC_E_OBJECT_NOT_FOUND = 8, + AFC_E_OBJECT_IS_DIR = 9, + AFC_E_PERM_DENIED = 10, + AFC_E_SERVICE_NOT_CONNECTED = 11, + AFC_E_OP_TIMEOUT = 12, + AFC_E_TOO_MUCH_DATA = 13, + AFC_E_END_OF_DATA = 14, + AFC_E_OP_NOT_SUPPORTED = 15, + AFC_E_OBJECT_EXISTS = 16, + AFC_E_OBJECT_BUSY = 17, + AFC_E_NO_SPACE_LEFT = 18, + AFC_E_OP_WOULD_BLOCK = 19, + AFC_E_IO_ERROR = 20, + AFC_E_OP_INTERRUPTED = 21, + AFC_E_OP_IN_PROGRESS = 22, + AFC_E_INTERNAL_ERROR = 23, + AFC_E_MUX_ERROR = 30, + AFC_E_NO_MEM = 31, + AFC_E_NOT_ENOUGH_DATA = 32, + AFC_E_DIR_NOT_EMPTY = 33, + AFC_E_FORCE_SIGNED_TYPE = -1 +} afc_error_t; /** Flags for afc_file_open */ typedef enum { @@ -88,33 +90,293 @@ typedef enum { AFC_LOCK_UN = 8 | 4 /**< unlock */ } afc_lock_op_t; -typedef struct afc_client_private afc_client_private; +typedef struct afc_client_private afc_client_private; /**< \private */ typedef afc_client_private *afc_client_t; /**< The client handle. */ /* Interface */ -afc_error_t afc_client_new_from_connection(idevice_connection_t connection, afc_client_t *client); -afc_error_t afc_client_new(idevice_t device, uint16_t port, afc_client_t *client); -afc_error_t afc_client_free(afc_client_t client); -afc_error_t afc_get_device_info(afc_client_t client, char ***infos); -afc_error_t afc_read_directory(afc_client_t client, const char *dir, char ***list); -afc_error_t afc_get_file_info(afc_client_t client, const char *filename, char ***infolist); -afc_error_t afc_file_open(afc_client_t client, const char *filename, afc_file_mode_t file_mode, uint64_t *handle); -afc_error_t afc_file_close(afc_client_t client, uint64_t handle); -afc_error_t afc_file_lock(afc_client_t client, uint64_t handle, afc_lock_op_t operation); -afc_error_t afc_file_read(afc_client_t client, uint64_t handle, char *data, uint32_t length, uint32_t *bytes_read); -afc_error_t afc_file_write(afc_client_t client, uint64_t handle, const char *data, uint32_t length, uint32_t *bytes_written); -afc_error_t afc_file_seek(afc_client_t client, uint64_t handle, int64_t offset, int whence); -afc_error_t afc_file_tell(afc_client_t client, uint64_t handle, uint64_t *position); -afc_error_t afc_file_truncate(afc_client_t client, uint64_t handle, uint64_t newsize); -afc_error_t afc_remove_path(afc_client_t client, const char *path); -afc_error_t afc_rename_path(afc_client_t client, const char *from, const char *to); -afc_error_t afc_make_directory(afc_client_t client, const char *dir); -afc_error_t afc_truncate(afc_client_t client, const char *path, uint64_t newsize); -afc_error_t afc_make_link(afc_client_t client, afc_link_type_t linktype, const char *target, const char *linkname); -afc_error_t afc_set_file_time(afc_client_t client, const char *path, uint64_t mtime); + +/** + * Makes a connection to the AFC service on the 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 afc_client_t + * upon successful return. + * + * @return AFC_E_SUCCESS on success, AFC_E_INVALID_ARG if device or service is + * invalid, AFC_E_MUX_ERROR if the connection cannot be established, + * or AFC_E_NO_MEM if there is a memory allocation problem. + */ +LIBIMOBILEDEVICE_API afc_error_t afc_client_new(idevice_t device, lockdownd_service_descriptor_t service, afc_client_t *client); + +/** + * Starts a new AFC 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 afc_client_t upon + * successful return. Must be freed using afc_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 AFC_E_SUCCESS on success, or an AFC_E_* error code otherwise. + */ +LIBIMOBILEDEVICE_API afc_error_t afc_client_start_service(idevice_t device, afc_client_t* client, const char* label); + +/** + * Frees up an AFC client. If the connection was created by the client itself, + * the connection will be closed. + * + * @param client The client to free. + */ +LIBIMOBILEDEVICE_API afc_error_t afc_client_free(afc_client_t client); + +/** + * Get device information for a connected client. The device information + * returned is the device model as well as the free space, the total capacity + * and blocksize on the accessed disk partition. + * + * @param client The client to get device info for. + * @param device_information A char list of device information terminated by an + * empty string or NULL if there was an error. Free with + * afc_dictionary_free(). + * + * @return AFC_E_SUCCESS on success or an AFC_E_* error value. + */ +LIBIMOBILEDEVICE_API afc_error_t afc_get_device_info(afc_client_t client, char ***device_information); + +/** + * Gets a directory listing of the directory requested. + * + * @param client The client to get a directory listing from. + * @param path The directory for listing. (must be a fully-qualified path) + * @param directory_information A char list of files in the directory + * terminated by an empty string or NULL if there was an error. Free with + * afc_dictionary_free(). + * + * @return AFC_E_SUCCESS on success or an AFC_E_* error value. + */ +LIBIMOBILEDEVICE_API afc_error_t afc_read_directory(afc_client_t client, const char *path, char ***directory_information); + +/** + * Gets information about a specific file. + * + * @param client The client to use to get the information of the file. + * @param path The fully-qualified path to the file. + * @param file_information Pointer to a buffer that will be filled with a + * NULL-terminated list of strings with the file information. Set to NULL + * before calling this function. Free with afc_dictionary_free(). + * + * @return AFC_E_SUCCESS on success or an AFC_E_* error value. + */ +LIBIMOBILEDEVICE_API afc_error_t afc_get_file_info(afc_client_t client, const char *path, char ***file_information); + +/** + * Opens a file on the device. + * + * @param client The client to use to open the file. + * @param filename The file to open. (must be a fully-qualified path) + * @param file_mode The mode to use to open the file. + * @param handle Pointer to a uint64_t that will hold the handle of the file + * + * @return AFC_E_SUCCESS on success or an AFC_E_* error value. + */ +LIBIMOBILEDEVICE_API afc_error_t afc_file_open(afc_client_t client, const char *filename, afc_file_mode_t file_mode, uint64_t *handle); + +/** + * Closes a file on the device. + * + * @param client The client to close the file with. + * @param handle File handle of a previously opened file. + */ +LIBIMOBILEDEVICE_API afc_error_t afc_file_close(afc_client_t client, uint64_t handle); + +/** + * Locks or unlocks a file on the device. + * + * Makes use of flock on the device. + * @see http://developer.apple.com/documentation/Darwin/Reference/ManPages/man2/flock.2.html + * + * @param client The client to lock the file with. + * @param handle File handle of a previously opened file. + * @param operation the lock or unlock operation to perform, this is one of + * AFC_LOCK_SH (shared lock), AFC_LOCK_EX (exclusive lock), or + * AFC_LOCK_UN (unlock). + */ +LIBIMOBILEDEVICE_API afc_error_t afc_file_lock(afc_client_t client, uint64_t handle, afc_lock_op_t operation); + +/** + * Attempts to the read the given number of bytes from the given file. + * + * @param client The relevant AFC client + * @param handle File handle of a previously opened file + * @param data The pointer to the memory region to store the read data + * @param length The number of bytes to read + * @param bytes_read The number of bytes actually read. + * + * @return AFC_E_SUCCESS on success or an AFC_E_* error value. + */ +LIBIMOBILEDEVICE_API afc_error_t afc_file_read(afc_client_t client, uint64_t handle, char *data, uint32_t length, uint32_t *bytes_read); + +/** + * Writes a given number of bytes to a file. + * + * @param client The client to use to write to the file. + * @param handle File handle of previously opened file. + * @param data The data to write to the file. + * @param length How much data to write. + * @param bytes_written The number of bytes actually written to the file. + * + * @return AFC_E_SUCCESS on success or an AFC_E_* error value. + */ +LIBIMOBILEDEVICE_API afc_error_t afc_file_write(afc_client_t client, uint64_t handle, const char *data, uint32_t length, uint32_t *bytes_written); + +/** + * Seeks to a given position of a pre-opened file on the device. + * + * @param client The client to use to seek to the position. + * @param handle File handle of a previously opened. + * @param offset Seek offset. + * @param whence Seeking direction, one of SEEK_SET, SEEK_CUR, or SEEK_END. + * + * @return AFC_E_SUCCESS on success or an AFC_E_* error value. + */ +LIBIMOBILEDEVICE_API afc_error_t afc_file_seek(afc_client_t client, uint64_t handle, int64_t offset, int whence); + +/** + * Returns current position in a pre-opened file on the device. + * + * @param client The client to use. + * @param handle File handle of a previously opened file. + * @param position Position in bytes of indicator + * + * @return AFC_E_SUCCESS on success or an AFC_E_* error value. + */ +LIBIMOBILEDEVICE_API afc_error_t afc_file_tell(afc_client_t client, uint64_t handle, uint64_t *position); + +/** + * Sets the size of a file on the device. + * + * @param client The client to use to set the file size. + * @param handle File handle of a previously opened file. + * @param newsize The size to set the file to. + * + * @return AFC_E_SUCCESS on success or an AFC_E_* error value. + * + * @note This function is more akin to ftruncate than truncate, and truncate + * calls would have to open the file before calling this, sadly. + */ +LIBIMOBILEDEVICE_API afc_error_t afc_file_truncate(afc_client_t client, uint64_t handle, uint64_t newsize); + +/** + * Deletes a file or directory. + * + * @param client The client to use. + * @param path The path to delete. (must be a fully-qualified path) + * + * @return AFC_E_SUCCESS on success or an AFC_E_* error value. + */ +LIBIMOBILEDEVICE_API afc_error_t afc_remove_path(afc_client_t client, const char *path); + +/** + * Renames a file or directory on the device. + * + * @param client The client to have rename. + * @param from The name to rename from. (must be a fully-qualified path) + * @param to The new name. (must also be a fully-qualified path) + * + * @return AFC_E_SUCCESS on success or an AFC_E_* error value. + */ +LIBIMOBILEDEVICE_API afc_error_t afc_rename_path(afc_client_t client, const char *from, const char *to); + +/** + * Creates a directory on the device. + * + * @param client The client to use to make a directory. + * @param path The directory's path. (must be a fully-qualified path, I assume + * all other mkdir restrictions apply as well) + * + * @return AFC_E_SUCCESS on success or an AFC_E_* error value. + */ +LIBIMOBILEDEVICE_API afc_error_t afc_make_directory(afc_client_t client, const char *path); + +/** + * Sets the size of a file on the device without prior opening it. + * + * @param client The client to use to set the file size. + * @param path The path of the file to be truncated. + * @param newsize The size to set the file to. + * + * @return AFC_E_SUCCESS on success or an AFC_E_* error value. + */ +LIBIMOBILEDEVICE_API afc_error_t afc_truncate(afc_client_t client, const char *path, uint64_t newsize); + +/** + * Creates a hard link or symbolic link on the device. + * + * @param client The client to use for making a link + * @param linktype 1 = hard link, 2 = symlink + * @param target The file to be linked. + * @param linkname The name of link. + * + * @return AFC_E_SUCCESS on success or an AFC_E_* error value. + */ +LIBIMOBILEDEVICE_API afc_error_t afc_make_link(afc_client_t client, afc_link_type_t linktype, const char *target, const char *linkname); + +/** + * Sets the modification time of a file on the device. + * + * @param client The client to use to set the file size. + * @param path Path of the file for which the modification time should be set. + * @param mtime The modification time to set in nanoseconds since epoch. + * + * @return AFC_E_SUCCESS on success or an AFC_E_* error value. + */ +LIBIMOBILEDEVICE_API afc_error_t afc_set_file_time(afc_client_t client, const char *path, uint64_t mtime); + +/** + * Deletes a file or directory including possible contents. + * + * @param client The client to use. + * @param path The path to delete. (must be a fully-qualified path) + * @since libimobiledevice 1.1.7 + * @note Only available in iOS 6 and later. + * + * @return AFC_E_SUCCESS on success or an AFC_E_* error value. + */ +LIBIMOBILEDEVICE_API afc_error_t afc_remove_path_and_contents(afc_client_t client, const char *path); /* Helper functions */ -afc_error_t afc_get_device_info_key(afc_client_t client, const char *key, char **value); + +/** + * Get a specific key of the device info list for a client connection. + * Known key values are: Model, FSTotalBytes, FSFreeBytes and FSBlockSize. + * This is a helper function for afc_get_device_info(). + * + * @param client The client to get device info for. + * @param key The key to get the value of. + * @param value The value for the key if successful or NULL otherwise. + * + * @return AFC_E_SUCCESS on success or an AFC_E_* error value. + */ +LIBIMOBILEDEVICE_API afc_error_t afc_get_device_info_key(afc_client_t client, const char *key, char **value); + +/** + * Frees up a char dictionary as returned by some AFC functions. + * + * @param dictionary The char array terminated by an empty string. + * + * @return AFC_E_SUCCESS on success or an AFC_E_* error value. + */ +LIBIMOBILEDEVICE_API afc_error_t afc_dictionary_free(char **dictionary); + +/** + * Gets a readable error string for a given AFC error code. + * + * @param err An AFC error code + * + * @returns A readable error string + */ +LIBIMOBILEDEVICE_API const char* afc_strerror(afc_error_t err); #ifdef __cplusplus } |