diff options
Diffstat (limited to 'include/libimobiledevice/afc.h')
| -rw-r--r-- | include/libimobiledevice/afc.h | 233 |
1 files changed, 233 insertions, 0 deletions
diff --git a/include/libimobiledevice/afc.h b/include/libimobiledevice/afc.h index 289c749..2f272e0 100644 --- a/include/libimobiledevice/afc.h +++ b/include/libimobiledevice/afc.h @@ -95,30 +95,263 @@ typedef struct afc_client_private afc_client_private; typedef afc_client_private *afc_client_t; /**< The client handle. */ /* Interface */ + +/** + * 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. + */ 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. + */ 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. + */ 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 infos A char ** list of parameters as given by AFC or NULL if there + * was an error. + * + * @return AFC_E_SUCCESS on success or an AFC_E_* error value. + */ afc_error_t afc_get_device_info(afc_client_t client, char ***infos); + +/** + * Gets a directory listing of the directory requested. + * + * @param client The client to get a directory listing from. + * @param dir The directory to list. (must be a fully-qualified path) + * @param list A char list of files in that directory, terminated by an empty + * string or NULL if there was an error. + * + * @return AFC_E_SUCCESS on success or an AFC_E_* error value. + */ afc_error_t afc_read_directory(afc_client_t client, const char *dir, char ***list); + +/** + * 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 infolist 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. + * + * @return AFC_E_SUCCESS on success or an AFC_E_* error value. + */ afc_error_t afc_get_file_info(afc_client_t client, const char *filename, char ***infolist); + +/** + * 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. Can be AFC_FILE_READ or + * AFC_FILE_WRITE; the former lets you read and write, + * however, and the second one will *create* the file, + * destroying anything previously there. + * @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. + */ 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. + */ 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). + */ 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. + */ 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. + */ 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. + */ 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. + */ 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. + */ 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. + */ 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. + */ 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 dir 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. + */ afc_error_t afc_make_directory(afc_client_t client, const char *dir); + +/** + * 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. + */ 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. + */ 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. + */ afc_error_t afc_set_file_time(afc_client_t client, const char *path, uint64_t mtime); /* Helper functions */ + +/** + * 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. + */ afc_error_t afc_get_device_info_key(afc_client_t client, const char *key, char **value); + afc_error_t afc_dictionary_free(char **dictionary); #ifdef __cplusplus |