From 08d2af5d611319748afba2aaba5e6c8a99f1b396 Mon Sep 17 00:00:00 2001 From: Martin Szulecki Date: Tue, 16 Mar 2010 03:13:38 +0100 Subject: Complete documentation of public interface and fix a lot of bogus comments This change unifies the documentation comment syntax, fixes a few bad documentation comments and completes documentation where it was missing. --- include/libimobiledevice/afc.h | 27 +-- include/libimobiledevice/file_relay.h | 5 +- include/libimobiledevice/installation_proxy.h | 6 +- include/libimobiledevice/libimobiledevice.h | 23 ++- include/libimobiledevice/lockdown.h | 16 +- include/libimobiledevice/mobile_image_mounter.h | 5 +- include/libimobiledevice/mobilebackup.h | 5 +- include/libimobiledevice/mobilesync.h | 5 +- include/libimobiledevice/notification_proxy.h | 20 +- include/libimobiledevice/sbservices.h | 5 +- include/libimobiledevice/screenshotr.h | 5 +- src/afc.c | 213 +++++++++++--------- src/afc.h | 58 +++--- src/device_link_service.h | 3 +- src/idevice.c | 17 +- src/lockdown.c | 247 ++++++++++++++++-------- src/mobilebackup.c | 31 ++- src/mobilesync.c | 31 ++- src/sbservices.c | 2 +- src/screenshotr.h | 2 +- src/userpref.c | 44 +++-- 21 files changed, 502 insertions(+), 268 deletions(-) diff --git a/include/libimobiledevice/afc.h b/include/libimobiledevice/afc.h index d800d19..c060eb7 100644 --- a/include/libimobiledevice/afc.h +++ b/include/libimobiledevice/afc.h @@ -29,7 +29,8 @@ extern "C" { #include -/* Error Codes */ +/** @name Error Codes */ +/*@{*/ #define AFC_E_SUCCESS 0 #define AFC_E_UNKNOWN_ERROR 1 #define AFC_E_OP_HEADER_INVALID 2 @@ -59,28 +60,32 @@ extern "C" { #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; -/* Flags */ +/** Flags for afc_file_open */ typedef enum { - AFC_FOPEN_RDONLY = 0x00000001, // r O_RDONLY - AFC_FOPEN_RW = 0x00000002, // r+ O_RDWR | O_CREAT - AFC_FOPEN_WRONLY = 0x00000003, // w O_WRONLY | O_CREAT | O_TRUNC - AFC_FOPEN_WR = 0x00000004, // w+ O_RDWR | O_CREAT | O_TRUNC - AFC_FOPEN_APPEND = 0x00000005, // a O_WRONLY | O_APPEND | O_CREAT - AFC_FOPEN_RDAPPEND = 0x00000006 // a+ O_RDWR | O_APPEND | O_CREAT + AFC_FOPEN_RDONLY = 0x00000001, /**< r O_RDONLY */ + AFC_FOPEN_RW = 0x00000002, /**< r+ O_RDWR | O_CREAT */ + AFC_FOPEN_WRONLY = 0x00000003, /**< w O_WRONLY | O_CREAT | O_TRUNC */ + AFC_FOPEN_WR = 0x00000004, /**< w+ O_RDWR | O_CREAT | O_TRUNC */ + AFC_FOPEN_APPEND = 0x00000005, /**< a O_WRONLY | O_APPEND | O_CREAT */ + AFC_FOPEN_RDAPPEND = 0x00000006 /**< a+ O_RDWR | O_APPEND | O_CREAT */ } afc_file_mode_t; +/** Type of link for afc_make_link() calls */ typedef enum { AFC_HARDLINK = 1, AFC_SYMLINK = 2 } afc_link_type_t; +/** Lock operation flags */ typedef enum { - AFC_LOCK_SH = 1 | 4, // shared lock - AFC_LOCK_EX = 2 | 4, // exclusive lock - AFC_LOCK_UN = 8 | 4 // unlock + AFC_LOCK_SH = 1 | 4, /**< shared lock */ + AFC_LOCK_EX = 2 | 4, /**< exclusive lock */ + AFC_LOCK_UN = 8 | 4 /**< unlock */ } afc_lock_op_t; typedef struct afc_client_private afc_client_private; diff --git a/include/libimobiledevice/file_relay.h b/include/libimobiledevice/file_relay.h index dd65b38..b3900db 100644 --- a/include/libimobiledevice/file_relay.h +++ b/include/libimobiledevice/file_relay.h @@ -29,7 +29,8 @@ extern "C" { #include -/* Error Codes */ +/** @name Error Codes */ +/*@{*/ #define FILE_RELAY_E_SUCCESS 0 #define FILE_RELAY_E_INVALID_ARG -1 #define FILE_RELAY_E_PLIST_ERROR -2 @@ -38,7 +39,9 @@ extern "C" { #define FILE_RELAY_E_STAGING_EMPTY -5 #define FILE_RELAY_E_UNKNOWN_ERROR -256 +/*@}*/ +/** Represents an error code. */ typedef int16_t file_relay_error_t; typedef struct file_relay_client_private file_relay_client_private; diff --git a/include/libimobiledevice/installation_proxy.h b/include/libimobiledevice/installation_proxy.h index 8a7cfb9..2bf738d 100644 --- a/include/libimobiledevice/installation_proxy.h +++ b/include/libimobiledevice/installation_proxy.h @@ -30,7 +30,8 @@ extern "C" { #include #include -/* Error Codes */ +/** @name Error Codes */ +/*@{*/ #define INSTPROXY_E_SUCCESS 0 #define INSTPROXY_E_INVALID_ARG -1 #define INSTPROXY_E_PLIST_ERROR -2 @@ -39,12 +40,15 @@ extern "C" { #define INSTPROXY_E_OP_FAILED -5 #define INSTPROXY_E_UNKNOWN_ERROR -256 +/*@}*/ +/** Represents an error code. */ typedef int16_t instproxy_error_t; typedef struct instproxy_client_private instproxy_client_private; typedef instproxy_client_private *instproxy_client_t; /**< The client handle. */ +/** Reports the status of the given operation */ typedef void (*instproxy_status_cb_t) (const char *operation, plist_t status); /* Interface */ diff --git a/include/libimobiledevice/libimobiledevice.h b/include/libimobiledevice/libimobiledevice.h index 73e82fe..0c6a08f 100644 --- a/include/libimobiledevice/libimobiledevice.h +++ b/include/libimobiledevice/libimobiledevice.h @@ -1,6 +1,6 @@ /** * @file libimobiledevice/libimobiledevice.h - * @brief Common code and device handling + * @brief Device/Connection handling and communication * \internal * * Copyright (c) 2008 Jonathan Beck All Rights Reserved. @@ -32,7 +32,8 @@ extern "C" { #include #include -/* Error Codes */ +/** @name Error Codes */ +/*@{*/ #define IDEVICE_E_SUCCESS 0 #define IDEVICE_E_INVALID_ARG -1 #define IDEVICE_E_UNKNOWN_ERROR -2 @@ -40,7 +41,9 @@ extern "C" { #define IDEVICE_E_NOT_ENOUGH_DATA -4 #define IDEVICE_E_BAD_HEADER -5 #define IDEVICE_E_SSL_ERROR -6 +/*@}*/ +/** Represents an error code. */ typedef int16_t idevice_error_t; typedef struct idevice_private idevice_private; @@ -53,23 +56,25 @@ typedef idevice_connection_private *idevice_connection_t; /**< The connection ha void idevice_set_debug_level(int level); /* discovery (events/asynchronous) */ -// event type +/** The event type for device add or removal */ enum idevice_event_type { IDEVICE_DEVICE_ADD = 1, IDEVICE_DEVICE_REMOVE }; -// event data structure +/* event data structure */ +/** Provides information about the occoured event. */ typedef struct { - enum idevice_event_type event; - const char *uuid; - int conn_type; + enum idevice_event_type event; /**< The event type. */ + const char *uuid; /**< The device unique id. */ + int conn_type; /**< The connection type. Currently only 1 for usbmuxd. */ } idevice_event_t; -// event callback function prototype +/* event callback function prototype */ +/** Callback to notifiy if a device was added or removed. */ typedef void (*idevice_event_cb_t) (const idevice_event_t *event, void *user_data); -// functions +/* functions */ idevice_error_t idevice_event_subscribe(idevice_event_cb_t callback, void *user_data); idevice_error_t idevice_event_unsubscribe(); diff --git a/include/libimobiledevice/lockdown.h b/include/libimobiledevice/lockdown.h index 6abf6d6..4504ef1 100644 --- a/include/libimobiledevice/lockdown.h +++ b/include/libimobiledevice/lockdown.h @@ -1,6 +1,6 @@ /** * @file libimobiledevice/lockdown.h - * @brief Communcation with the lockdown device daemon + * @brief Implementation to communicate with the lockdown device daemon * \internal * * Copyright (c) 2008 Zach C. All Rights Reserved. @@ -30,7 +30,8 @@ extern "C" { #include -/* Error Codes */ +/** @name Error Codes */ +/*@{*/ #define LOCKDOWN_E_SUCCESS 0 #define LOCKDOWN_E_INVALID_ARG -1 #define LOCKDOWN_E_INVALID_CONF -2 @@ -52,18 +53,21 @@ extern "C" { #define LOCKDOWN_E_INVALID_ACTIVATION_RECORD -18 #define LOCKDOWN_E_UNKNOWN_ERROR -256 +/*@}*/ +/** Represents an error code. */ typedef int16_t lockdownd_error_t; typedef struct lockdownd_client_private lockdownd_client_private; typedef lockdownd_client_private *lockdownd_client_t; /**< The client handle. */ struct lockdownd_pair_record { - char *device_certificate; - char *host_certificate; - char *host_id; - char *root_certificate; + char *device_certificate; /**< The device certificate */ + char *host_certificate; /**< The host certificate */ + char *host_id; /**< A unique HostID for the host computer */ + char *root_certificate; /**< The root certificate */ }; +/** A pair record holding device, host and root certificates along the host_id */ typedef struct lockdownd_pair_record *lockdownd_pair_record_t; /* Interface */ diff --git a/include/libimobiledevice/mobile_image_mounter.h b/include/libimobiledevice/mobile_image_mounter.h index 5681d8b..26a3666 100644 --- a/include/libimobiledevice/mobile_image_mounter.h +++ b/include/libimobiledevice/mobile_image_mounter.h @@ -29,14 +29,17 @@ extern "C" { #include -/* Error Codes */ +/** @name Error Codes */ +/*@{*/ #define MOBILE_IMAGE_MOUNTER_E_SUCCESS 0 #define MOBILE_IMAGE_MOUNTER_E_INVALID_ARG -1 #define MOBILE_IMAGE_MOUNTER_E_PLIST_ERROR -2 #define MOBILE_IMAGE_MOUNTER_E_CONN_FAILED -3 #define MOBILE_IMAGE_MOUNTER_E_UNKNOWN_ERROR -256 +/*@}*/ +/** Represents an error code. */ typedef int16_t mobile_image_mounter_error_t; typedef struct mobile_image_mounter_client_private mobile_image_mounter_client_private; diff --git a/include/libimobiledevice/mobilebackup.h b/include/libimobiledevice/mobilebackup.h index d6f9013..6f37a14 100644 --- a/include/libimobiledevice/mobilebackup.h +++ b/include/libimobiledevice/mobilebackup.h @@ -29,7 +29,8 @@ extern "C" { #include -/* Error Codes */ +/** @name Error Codes */ +/*@{*/ #define MOBILEBACKUP_E_SUCCESS 0 #define MOBILEBACKUP_E_INVALID_ARG -1 #define MOBILEBACKUP_E_PLIST_ERROR -2 @@ -38,7 +39,9 @@ extern "C" { #define MOBILEBACKUP_E_REPLY_NOT_OK -5 #define MOBILEBACKUP_E_UNKNOWN_ERROR -256 +/*@}*/ +/** Represents an error code. */ typedef int16_t mobilebackup_error_t; typedef struct mobilebackup_client_private mobilebackup_client_private; diff --git a/include/libimobiledevice/mobilesync.h b/include/libimobiledevice/mobilesync.h index 2e330ee..7af3aef 100644 --- a/include/libimobiledevice/mobilesync.h +++ b/include/libimobiledevice/mobilesync.h @@ -29,7 +29,8 @@ extern "C" { #include -/* Error Codes */ +/** @name Error Codes */ +/*@{*/ #define MOBILESYNC_E_SUCCESS 0 #define MOBILESYNC_E_INVALID_ARG -1 #define MOBILESYNC_E_PLIST_ERROR -2 @@ -37,7 +38,9 @@ extern "C" { #define MOBILESYNC_E_BAD_VERSION -4 #define MOBILESYNC_E_UNKNOWN_ERROR -256 +/*@}*/ +/** Represents an error code. */ typedef int16_t mobilesync_error_t; typedef struct mobilesync_client_private mobilesync_client_private; diff --git a/include/libimobiledevice/notification_proxy.h b/include/libimobiledevice/notification_proxy.h index 74b6b37..d85f56c 100644 --- a/include/libimobiledevice/notification_proxy.h +++ b/include/libimobiledevice/notification_proxy.h @@ -29,23 +29,36 @@ extern "C" { #include -/* Error Codes */ +/** @name Error Codes */ +/*@{*/ #define NP_E_SUCCESS 0 #define NP_E_INVALID_ARG -1 #define NP_E_PLIST_ERROR -2 #define NP_E_CONN_FAILED -3 #define NP_E_UNKNOWN_ERROR -256 +/*@}*/ +/** Represents an error code. */ typedef int16_t np_error_t; -/* Notification IDs for use with post_notification (client --> device) */ +/** + * @name Notifications that can be send + * + * For use with np_post_notification() (client --> device) + */ #define NP_SYNC_WILL_START "com.apple.itunes-mobdev.syncWillStart" #define NP_SYNC_DID_START "com.apple.itunes-mobdev.syncDidStart" #define NP_SYNC_DID_FINISH "com.apple.itunes-mobdev.syncDidFinish" #define NP_SYNC_LOCK_REQUEST "com.apple.itunes-mobdev.syncLockRequest" +/*@}*/ -/* Notification IDs for use with observe_notification (device --> client) */ +/** + * @name Notifications that can be received + * + * For use with np_observe_notification() (device --> client) + */ +/*@{*/ #define NP_SYNC_CANCEL_REQUEST "com.apple.itunes-client.syncCancelRequest" #define NP_SYNC_SUSPEND_REQUEST "com.apple.itunes-client.syncSuspendRequest" #define NP_SYNC_RESUME_REQUEST "com.apple.itunes-client.syncResumeRequest" @@ -67,6 +80,7 @@ typedef int16_t np_error_t; #define NP_ITDBPREP_DID_END "com.apple.itdbprep.notification.didEnd" #define NP_LANGUAGE_CHANGED "com.apple.language.changed" #define NP_ADDRESS_BOOK_PREF_CHANGED "com.apple.AddressBook.PreferenceChanged" +/*@}*/ typedef struct np_client_private np_client_private; typedef np_client_private *np_client_t; /**< The client handle. */ diff --git a/include/libimobiledevice/sbservices.h b/include/libimobiledevice/sbservices.h index 0fcec86..71e951e 100644 --- a/include/libimobiledevice/sbservices.h +++ b/include/libimobiledevice/sbservices.h @@ -29,14 +29,17 @@ extern "C" { #include -/* Error Codes */ +/** @name Error Codes */ +/*@{*/ #define SBSERVICES_E_SUCCESS 0 #define SBSERVICES_E_INVALID_ARG -1 #define SBSERVICES_E_PLIST_ERROR -2 #define SBSERVICES_E_CONN_FAILED -3 #define SBSERVICES_E_UNKNOWN_ERROR -256 +/*@}*/ +/** Represents an error code. */ typedef int16_t sbservices_error_t; typedef struct sbservices_client_private sbservices_client_private; diff --git a/include/libimobiledevice/screenshotr.h b/include/libimobiledevice/screenshotr.h index d9a3ffd..7e5c8a7 100644 --- a/include/libimobiledevice/screenshotr.h +++ b/include/libimobiledevice/screenshotr.h @@ -29,7 +29,8 @@ extern "C" { #include -/* Error Codes */ +/** @name Error Codes */ +/*@{*/ #define SCREENSHOTR_E_SUCCESS 0 #define SCREENSHOTR_E_INVALID_ARG -1 #define SCREENSHOTR_E_PLIST_ERROR -2 @@ -37,7 +38,9 @@ extern "C" { #define SCREENSHOTR_E_BAD_VERSION -4 #define SCREENSHOTR_E_UNKNOWN_ERROR -256 +/*@}*/ +/** Represents an error code. */ typedef int16_t screenshotr_error_t; typedef struct screenshotr_client_private screenshotr_client_private; diff --git a/src/afc.c b/src/afc.c index e966fa5..5def00c 100644 --- a/src/afc.c +++ b/src/afc.c @@ -27,10 +27,11 @@ #include "idevice.h" #include "debug.h" -// This is the maximum size an AFC data packet can be +/** The maximum size an AFC data packet can be */ static const int MAXIMUM_PACKET_SIZE = (2 << 15); -/** Locks an AFC client, done for thread safety stuff +/** + * Locks an AFC client, done for thread safety stuff * * @param client The AFC client connection to lock */ @@ -40,7 +41,8 @@ static void afc_lock(afc_client_t client) g_mutex_lock(client->mutex); } -/** Unlocks an AFC client, done for thread safety stuff. +/** + * Unlocks an AFC client, done for thread safety stuff. * * @param client The AFC */ @@ -50,7 +52,8 @@ static void afc_unlock(afc_client_t client) g_mutex_unlock(client->mutex); } -/** Makes a connection to the AFC service on the phone. +/** + * Makes a connection to the AFC service on the phone. * * @param device The device to connect to. * @param port The destination port. @@ -118,14 +121,15 @@ afc_error_t afc_client_free(afc_client_t client) return AFC_E_SUCCESS; } -/** Dispatches an AFC packet over a client. +/** + * Dispatches an AFC packet over a client. * * @param client The client to send data through. * @param data The data to send. * @param length The length to send. * @param bytes_sent The number of bytes actually sent. * - * @return AFC_E_SUCCESS on success, or an AFC_E_* error value on error. + * @return AFC_E_SUCCESS on success or an AFC_E_* error value. * * @warning set client->afc_packet->this_length and * client->afc_packet->entire_length to 0 before calling this. The @@ -153,9 +157,9 @@ static afc_error_t afc_dispatch_packet(afc_client_t client, const char *data, ui if (!client->afc_packet->this_length) { client->afc_packet->this_length = sizeof(AFCPacket); } - // We want to send two segments; buffer+sizeof(AFCPacket) to - // this_length is the parameters - // And everything beyond that is the next packet. (for writing) + /* We want to send two segments; buffer+sizeof(AFCPacket) to this_length + is the parameters and everything beyond that is the next packet. + (for writing) */ if (client->afc_packet->this_length != client->afc_packet->entire_length) { offset = client->afc_packet->this_length - sizeof(AFCPacket); @@ -222,14 +226,14 @@ static afc_error_t afc_dispatch_packet(afc_client_t client, const char *data, ui return AFC_E_INTERNAL_ERROR; } -/** Receives data through an AFC client and sets a variable to the received data. +/** + * Receives data through an AFC client and sets a variable to the received data. * * @param client The client to receive data on. * @param dump_here The char* to point to the newly-received data. * @param bytes_recv How much data was received. * - * @return AFC_E_SUCCESS when data has been received, or an AFC_E_* error value - * when an error occured. + * @return AFC_E_SUCCESS on success or an AFC_E_* error value. */ static afc_error_t afc_receive_data(afc_client_t client, char **dump_here, uint32_t *bytes_recv) { @@ -371,6 +375,9 @@ static afc_error_t afc_receive_data(afc_client_t client, char **dump_here, uint3 return AFC_E_SUCCESS; } +/** + * Returns counts of null characters within a string. + */ static uint32_t count_nullspaces(char *string, uint32_t number) { uint32_t i = 0, nulls = 0; @@ -412,13 +419,15 @@ static char **make_strings_list(char *tokens, uint32_t length) return list; } -/** Gets a directory listing of the directory requested. +/** + * 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 A char ** list of files in that directory, terminated by an empty - * string for now 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) { @@ -431,7 +440,7 @@ afc_error_t afc_read_directory(afc_client_t client, const char *dir, char ***lis afc_lock(client); - // Send the command + /* Send the command */ client->afc_packet->operation = AFC_OP_READ_DIR; client->afc_packet->entire_length = 0; client->afc_packet->this_length = 0; @@ -440,13 +449,13 @@ afc_error_t afc_read_directory(afc_client_t client, const char *dir, char ***lis afc_unlock(client); return AFC_E_NOT_ENOUGH_DATA; } - // Receive the data + /* Receive the data */ ret = afc_receive_data(client, &data, &bytes); if (ret != AFC_E_SUCCESS) { afc_unlock(client); return ret; } - // Parse the data + /* Parse the data */ list_loc = make_strings_list(data, bytes); if (data) free(data); @@ -457,12 +466,16 @@ afc_error_t afc_read_directory(afc_client_t client, const char *dir, char ***lis return ret; } -/** Get device info for a client connection to phone. (free space on disk, etc.) +/** + * Get device info for a client connection to phone. 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 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) { @@ -475,7 +488,7 @@ afc_error_t afc_get_device_info(afc_client_t client, char ***infos) afc_lock(client); - // Send the command + /* Send the command */ client->afc_packet->operation = AFC_OP_GET_DEVINFO; client->afc_packet->entire_length = client->afc_packet->this_length = 0; ret = afc_dispatch_packet(client, NULL, 0, &bytes); @@ -483,13 +496,13 @@ afc_error_t afc_get_device_info(afc_client_t client, char ***infos) afc_unlock(client); return AFC_E_NOT_ENOUGH_DATA; } - // Receive the data + /* Receive the data */ ret = afc_receive_data(client, &data, &bytes); if (ret != AFC_E_SUCCESS) { afc_unlock(client); return ret; } - // Parse the data + /* Parse the data */ list = make_strings_list(data, bytes); if (data) free(data); @@ -501,7 +514,8 @@ afc_error_t afc_get_device_info(afc_client_t client, char ***infos) return ret; } -/** Get a specific key of the device info list for a client connection. +/** + * 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(). * @@ -536,7 +550,8 @@ afc_error_t afc_get_device_info_key(afc_client_t client, const char *key, char * return ret; } -/** Deletes a file or directory. +/** + * Deletes a file or directory. * * @param client The client to use. * @param path The path to delete. (must be a fully-qualified path) @@ -554,7 +569,7 @@ afc_error_t afc_remove_path(afc_client_t client, const char *path) afc_lock(client); - // Send command + /* Send command */ client->afc_packet->this_length = client->afc_packet->entire_length = 0; client->afc_packet->operation = AFC_OP_REMOVE_PATH; ret = afc_dispatch_packet(client, path, strlen(path)+1, &bytes); @@ -562,7 +577,7 @@ afc_error_t afc_remove_path(afc_client_t client, const char *path) afc_unlock(client); return AFC_E_NOT_ENOUGH_DATA; } - // Receive response + /* Receive response */ ret = afc_receive_data(client, &response, &bytes); if (response) free(response); @@ -576,7 +591,8 @@ afc_error_t afc_remove_path(afc_client_t client, const char *path) return ret; } -/** Renames a file or directory on the phone. +/** + * Renames a file or directory on the phone. * * @param client The client to have rename. * @param from The name to rename from. (must be a fully-qualified path) @@ -596,7 +612,7 @@ afc_error_t afc_rename_path(afc_client_t client, const char *from, const char *t afc_lock(client); - // Send command + /* Send command */ memcpy(send, from, strlen(from) + 1); memcpy(send + strlen(from) + 1, to, strlen(to) + 1); client->afc_packet->entire_length = client->afc_packet->this_length = 0; @@ -607,7 +623,7 @@ afc_error_t afc_rename_path(afc_client_t client, const char *from, const char *t afc_unlock(client); return AFC_E_NOT_ENOUGH_DATA; } - // Receive response + /* Receive response */ ret = afc_receive_data(client, &response, &bytes); if (response) free(response); @@ -617,7 +633,8 @@ afc_error_t afc_rename_path(afc_client_t client, const char *from, const char *t return ret; } -/** Creates a directory on the phone. +/** + * Creates a directory on the phone. * * @param client The client to use to make a directory. * @param dir The directory's path. (must be a fully-qualified path, I assume @@ -636,7 +653,7 @@ afc_error_t afc_make_directory(afc_client_t client, const char *dir) afc_lock(client); - // Send command + /* Send command */ client->afc_packet->operation = AFC_OP_MAKE_DIR; client->afc_packet->this_length = client->afc_packet->entire_length = 0; ret = afc_dispatch_packet(client, dir, strlen(dir)+1, &bytes); @@ -644,7 +661,7 @@ afc_error_t afc_make_directory(afc_client_t client, const char *dir) afc_unlock(client); return AFC_E_NOT_ENOUGH_DATA; } - // Receive response + /* Receive response */ ret = afc_receive_data(client, &response, &bytes); if (response) free(response); @@ -654,7 +671,8 @@ afc_error_t afc_make_directory(afc_client_t client, const char *dir) return ret; } -/** Gets information about a specific file. +/** + * 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. @@ -662,8 +680,7 @@ afc_error_t afc_make_directory(afc_client_t client, const char *dir) * 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 - * when something went wrong. + * @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 *path, char ***infolist) { @@ -676,7 +693,7 @@ afc_error_t afc_get_file_info(afc_client_t client, const char *path, char ***inf afc_lock(client); - // Send command + /* Send command */ client->afc_packet->operation = AFC_OP_GET_FILE_INFO; client->afc_packet->entire_length = client->afc_packet->this_length = 0; ret = afc_dispatch_packet(client, path, strlen(path)+1, &bytes); @@ -685,7 +702,7 @@ afc_error_t afc_get_file_info(afc_client_t client, const char *path, char ***inf return AFC_E_NOT_ENOUGH_DATA; } - // Receive data + /* Receive data */ ret = afc_receive_data(client, &received, &bytes); if (received) { *infolist = make_strings_list(received, bytes); @@ -697,7 +714,8 @@ afc_error_t afc_get_file_info(afc_client_t client, const char *path, char ***inf return ret; } -/** Opens a file on the phone. +/** + * Opens a file on the phone. * * @param client The client to use to open the file. * @param filename The file to open. (must be a fully-qualified path) @@ -707,7 +725,7 @@ afc_error_t afc_get_file_info(afc_client_t client, const char *path, char ***inf * 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 on failure. + * @return AFC_E_SUCCESS on success or an AFC_E_* error value. */ idevice_error_t afc_file_open(afc_client_t client, const char *filename, @@ -718,7 +736,7 @@ afc_file_open(afc_client_t client, const char *filename, char *data = (char *) malloc(sizeof(char) * (8 + strlen(filename) + 1)); afc_error_t ret = AFC_E_UNKNOWN_ERROR; - // set handle to 0 so in case an error occurs, the handle is invalid + /* set handle to 0 so in case an error occurs, the handle is invalid */ *handle = 0; if (!client || !client->connection || !client->afc_packet) @@ -726,7 +744,7 @@ afc_file_open(afc_client_t client, const char *filename, afc_lock(client); - // Send command + /* Send command */ memcpy(data, &file_mode_loc, 8); memcpy(data + 8, filename, strlen(filename)); data[8 + strlen(filename)] = '\0'; @@ -740,12 +758,12 @@ afc_file_open(afc_client_t client, const char *filename, afc_unlock(client); return AFC_E_NOT_ENOUGH_DATA; } - // Receive the data + /* Receive the data */ ret = afc_receive_data(client, &data, &bytes); if ((ret == AFC_E_SUCCESS) && (bytes > 0) && data) { afc_unlock(client); - // Get the file handle + /* Get the file handle */ memcpy(handle, data, sizeof(uint64_t)); free(data); return ret; @@ -758,7 +776,8 @@ afc_file_open(afc_client_t client, const char *filename, return ret; } -/** Attempts to the read the given number of bytes from the given file. +/** + * 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 @@ -766,7 +785,7 @@ afc_file_open(afc_client_t client, const char *filename, * @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 on error. + * @return AFC_E_SUCCESS on success or an AFC_E_* error value. */ idevice_error_t afc_file_read(afc_client_t client, uint64_t handle, char *data, uint32_t length, uint32_t *bytes_read) @@ -782,12 +801,12 @@ afc_file_read(afc_client_t client, uint64_t handle, char *data, uint32_t length, afc_lock(client); - // Looping here to get around the maximum amount of data that - // afc_receive_data can handle + /* Looping here to get around the maximum amount of data that + afc_receive_data can handle */ while (current_count < length) { debug_info("current count is %i but length is %i", current_count, length); - // Send the read command + /* Send the read command */ AFCFilePacket *packet = (AFCFilePacket *) malloc(sizeof(AFCFilePacket)); packet->filehandle = handle; packet->size = GUINT64_TO_LE(((length - current_count) < MAXIMUM_READ_SIZE) ? (length - current_count) : MAXIMUM_READ_SIZE); @@ -800,7 +819,7 @@ afc_file_read(afc_client_t client, uint64_t handle, char *data, uint32_t length, afc_unlock(client); return AFC_E_NOT_ENOUGH_DATA; } - // Receive the data + /* Receive the data */ ret = afc_receive_data(client, &input, &bytes_loc); debug_info("afc_receive_data returned error: %d", ret); debug_info("bytes returned: %i", bytes_loc); @@ -831,7 +850,8 @@ afc_file_read(afc_client_t client, uint64_t handle, char *data, uint32_t length, return ret; } -/** Writes a given number of bytes to a file. +/** + * 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. @@ -839,7 +859,7 @@ afc_file_read(afc_client_t client, uint64_t handle, char *data, uint32_t length, * @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 on error. + * @return AFC_E_SUCCESS on success or an AFC_E_* error value. */ idevice_error_t afc_file_write(afc_client_t client, uint64_t handle, const char *data, uint32_t length, uint32_t *bytes_written) @@ -859,9 +879,9 @@ afc_file_write(afc_client_t client, uint64_t handle, const char *data, uint32_t debug_info("Write length: %i", length); - // Divide the file into segments. + /* Divide the file into segments. */ for (i = 0; i < segments; i++) { - // Send the segment + /* Send the segment */ client->afc_packet->this_length = sizeof(AFCPacket) + 8; client->afc_packet->entire_length = client->afc_packet->this_length + MAXIMUM_WRITE_SIZE; client->afc_packet->operation = AFC_OP_WRITE; @@ -886,10 +906,9 @@ afc_file_write(afc_client_t client, uint64_t handle, const char *data, uint32_t } } - // By this point, we should be at the end. i.e. the last segment that - // didn't get sent in the for loop - // this length is fine because it's always sizeof(AFCPacket) + 8, but - // to be sure we do it again + /* By this point, we should be at the end. i.e. the last segment that didn't + get sent in the for loop. This length is fine because it's always + sizeof(AFCPacket) + 8, but to be sure we do it again */ if (current_count == length) { afc_unlock(client); *bytes_written = current_count; @@ -925,7 +944,8 @@ afc_file_write(afc_client_t client, uint64_t handle, const char *data, uint32_t return ret; } -/** Closes a file on the phone. +/** + * Closes a file on the phone. * * @param client The client to close the file with. * @param handle File handle of a previously opened file. @@ -943,7 +963,7 @@ afc_error_t afc_file_close(afc_client_t client, uint64_t handle) debug_info("File handle %i", handle); - // Send command + /* Send command */ memcpy(buffer, &handle, sizeof(uint64_t)); client->afc_packet->operation = AFC_OP_FILE_CLOSE; client->afc_packet->entire_length = client->afc_packet->this_length = 0; @@ -956,7 +976,7 @@ afc_error_t afc_file_close(afc_client_t client, uint64_t handle) return AFC_E_UNKNOWN_ERROR; } - // Receive the response + /* Receive the response */ ret = afc_receive_data(client, &buffer, &bytes); if (buffer) free(buffer); @@ -966,7 +986,8 @@ afc_error_t afc_file_close(afc_client_t client, uint64_t handle) return ret; } -/** Locks or unlocks a file on the phone. +/** + * Locks or unlocks a file on the phone. * * makes use of flock on the device, see * http://developer.apple.com/documentation/Darwin/Reference/ManPages/man2/flock.2.html @@ -991,7 +1012,7 @@ afc_error_t afc_file_lock(afc_client_t client, uint64_t handle, afc_lock_op_t op debug_info("file handle %i", handle); - // Send command + /* Send command */ memcpy(buffer, &handle, sizeof(uint64_t)); memcpy(buffer + 8, &op, 8); @@ -1006,7 +1027,7 @@ afc_error_t afc_file_lock(afc_client_t client, uint64_t handle, afc_lock_op_t op debug_info("could not send lock command"); return AFC_E_UNKNOWN_ERROR; } - // Receive the response + /* Receive the response */ ret = afc_receive_data(client, &buffer, &bytes); if (buffer) { debug_buffer(buffer, bytes); @@ -1017,14 +1038,15 @@ afc_error_t afc_file_lock(afc_client_t client, uint64_t handle, afc_lock_op_t op return ret; } -/** Seeks to a given position of a pre-opened file on the phone. +/** + * Seeks to a given position of a pre-opened file on the phone. * * @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, AFC_E_NOT_ENOUGH_DATA on failure. + * @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) { @@ -1039,10 +1061,10 @@ afc_error_t afc_file_seek(afc_client_t client, uint64_t handle, int64_t offset, afc_lock(client); - // Send the command - memcpy(buffer, &handle, sizeof(uint64_t)); // handle - memcpy(buffer + 8, &whence_loc, sizeof(uint64_t)); // fromwhere - memcpy(buffer + 16, &offset_loc, sizeof(uint64_t)); // offset + /* Send the command */ + memcpy(buffer, &handle, sizeof(uint64_t)); /* handle */ + memcpy(buffer + 8, &whence_loc, sizeof(uint64_t)); /* fromwhere */ + memcpy(buffer + 16, &offset_loc, sizeof(uint64_t)); /* offset */ client->afc_packet->operation = AFC_OP_FILE_SEEK; client->afc_packet->this_length = client->afc_packet->entire_length = 0; ret = afc_dispatch_packet(client, buffer, 24, &bytes); @@ -1053,7 +1075,7 @@ afc_error_t afc_file_seek(afc_client_t client, uint64_t handle, int64_t offset, afc_unlock(client); return AFC_E_NOT_ENOUGH_DATA; } - // Receive response + /* Receive response */ ret = afc_receive_data(client, &buffer, &bytes); if (buffer) free(buffer); @@ -1063,13 +1085,14 @@ afc_error_t afc_file_seek(afc_client_t client, uint64_t handle, int64_t offset, return ret; } -/** Returns current position in a pre-opened file on the phone. +/** + * Returns current position in a pre-opened file on the phone. * * @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, AFC_E_NOT_ENOUGH_DATA on failure. + * @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) { @@ -1082,8 +1105,8 @@ afc_error_t afc_file_tell(afc_client_t client, uint64_t handle, uint64_t *positi afc_lock(client); - // Send the command - memcpy(buffer, &handle, sizeof(uint64_t)); // handle + /* Send the command */ + memcpy(buffer, &handle, sizeof(uint64_t)); /* handle */ client->afc_packet->operation = AFC_OP_FILE_TELL; client->afc_packet->this_length = client->afc_packet->entire_length = 0; ret = afc_dispatch_packet(client, buffer, 8, &bytes); @@ -1095,7 +1118,7 @@ afc_error_t afc_file_tell(afc_client_t client, uint64_t handle, uint64_t *positi return AFC_E_NOT_ENOUGH_DATA; } - // Receive the data + /* Receive the data */ ret = afc_receive_data(client, &buffer, &bytes); if (bytes > 0 && buffer) { /* Get the position */ @@ -1110,13 +1133,14 @@ afc_error_t afc_file_tell(afc_client_t client, uint64_t handle, uint64_t *positi return ret; } -/** Sets the size of a file on the phone. +/** + * Sets the size of a file on the phone. * * @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 0 on success, -1 on failure. + * @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. @@ -1133,9 +1157,9 @@ afc_error_t afc_file_truncate(afc_client_t client, uint64_t handle, uint64_t new afc_lock(client); - // Send command - memcpy(buffer, &handle, sizeof(uint64_t)); // handle - memcpy(buffer + 8, &newsize_loc, sizeof(uint64_t)); // newsize + /* Send command */ + memcpy(buffer, &handle, sizeof(uint64_t)); /* handle */ + memcpy(buffer + 8, &newsize_loc, sizeof(uint64_t)); /* newsize */ client->afc_packet->operation = AFC_OP_FILE_SET_SIZE; client->afc_packet->this_length = client->afc_packet->entire_length = 0; ret = afc_dispatch_packet(client, buffer, 16, &bytes); @@ -1146,7 +1170,7 @@ afc_error_t afc_file_truncate(afc_client_t client, uint64_t handle, uint64_t new afc_unlock(client); return AFC_E_NOT_ENOUGH_DATA; } - // Receive response + /* Receive response */ ret = afc_receive_data(client, &buffer, &bytes); if (buffer) free(buffer); @@ -1156,7 +1180,8 @@ afc_error_t afc_file_truncate(afc_client_t client, uint64_t handle, uint64_t new return ret; } -/** Sets the size of a file on the phone without prior opening it. +/** + * Sets the size of a file on the phone 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. @@ -1177,7 +1202,7 @@ afc_error_t afc_truncate(afc_client_t client, const char *path, uint64_t newsize afc_lock(client); - // Send command + /* Send command */ memcpy(send, &size_requested, 8); memcpy(send + 8, path, strlen(path) + 1); client->afc_packet->entire_length = client->afc_packet->this_length = 0; @@ -1188,7 +1213,7 @@ afc_error_t afc_truncate(afc_client_t client, const char *path, uint64_t newsize afc_unlock(client); return AFC_E_NOT_ENOUGH_DATA; } - // Receive response + /* Receive response */ ret = afc_receive_data(client, &response, &bytes); if (response) free(response); @@ -1198,10 +1223,11 @@ afc_error_t afc_truncate(afc_client_t client, const char *path, uint64_t newsize return ret; } -/** Creates a hard link or symbolic link on the device. +/** + * Creates a hard link or symbolic link on the device. * * @param client The client to use for making a link - * @param type 1 = hard link, 2 = symlink + * @param linktype 1 = hard link, 2 = symlink * @param target The file to be linked. * @param linkname The name of link. * @@ -1224,7 +1250,7 @@ afc_error_t afc_make_link(afc_client_t client, afc_link_type_t linktype, const c debug_info("target: %s, length:%d", target, strlen(target)); debug_info("linkname: %s, length:%d", linkname, strlen(linkname)); - // Send command + /* Send command */ memcpy(send, &type, 8); memcpy(send + 8, target, strlen(target) + 1); memcpy(send + 8 + strlen(target) + 1, linkname, strlen(linkname) + 1); @@ -1236,7 +1262,7 @@ afc_error_t afc_make_link(afc_client_t client, afc_link_type_t linktype, const c afc_unlock(client); return AFC_E_NOT_ENOUGH_DATA; } - // Receive response + /* Receive response */ ret = afc_receive_data(client, &response, &bytes); if (response) free(response); @@ -1246,7 +1272,8 @@ afc_error_t afc_make_link(afc_client_t client, afc_link_type_t linktype, const c return ret; } -/** Sets the modification time of a file on the phone. +/** + * Sets the modification time of a file on the phone. * * @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. @@ -1267,7 +1294,7 @@ afc_error_t afc_set_file_time(afc_client_t client, const char *path, uint64_t mt afc_lock(client); - // Send command + /* Send command */ memcpy(send, &mtime_loc, 8); memcpy(send + 8, path, strlen(path) + 1); client->afc_packet->entire_length = client->afc_packet->this_length = 0; @@ -1278,7 +1305,7 @@ afc_error_t afc_set_file_time(afc_client_t client, const char *path, uint64_t mt afc_unlock(client); return AFC_E_NOT_ENOUGH_DATA; } - // Receive response + /* Receive response */ ret = afc_receive_data(client, &response, &bytes); if (response) free(response); diff --git a/src/afc.h b/src/afc.h index abf38e3..cde85b4 100644 --- a/src/afc.h +++ b/src/afc.h @@ -62,34 +62,34 @@ struct afc_client_private { /* AFC Operations */ enum { - AFC_OP_STATUS = 0x00000001, // Status - AFC_OP_DATA = 0x00000002, // Data - AFC_OP_READ_DIR = 0x00000003, // ReadDir - AFC_OP_READ_FILE = 0x00000004, // ReadFile - AFC_OP_WRITE_FILE = 0x00000005, // WriteFile - AFC_OP_WRITE_PART = 0x00000006, // WritePart - AFC_OP_TRUNCATE = 0x00000007, // TruncateFile - AFC_OP_REMOVE_PATH = 0x00000008, // RemovePath - AFC_OP_MAKE_DIR = 0x00000009, // MakeDir - AFC_OP_GET_FILE_INFO = 0x0000000a, // GetFileInfo - AFC_OP_GET_DEVINFO = 0x0000000b, // GetDeviceInfo - AFC_OP_WRITE_FILE_ATOM = 0x0000000c, // WriteFileAtomic (tmp file+rename) - AFC_OP_FILE_OPEN = 0x0000000d, // FileRefOpen - AFC_OP_FILE_OPEN_RES = 0x0000000e, // FileRefOpenResult - AFC_OP_READ = 0x0000000f, // FileRefRead - AFC_OP_WRITE = 0x00000010, // FileRefWrite - AFC_OP_FILE_SEEK = 0x00000011, // FileRefSeek - AFC_OP_FILE_TELL = 0x00000012, // FileRefTell - AFC_OP_FILE_TELL_RES = 0x00000013, // FileRefTellResult - AFC_OP_FILE_CLOSE = 0x00000014, // FileRefClose - AFC_OP_FILE_SET_SIZE = 0x00000015, // FileRefSetFileSize (ftruncate) - AFC_OP_GET_CON_INFO = 0x00000016, // GetConnectionInfo - AFC_OP_SET_CON_OPTIONS = 0x00000017, // SetConnectionOptions - AFC_OP_RENAME_PATH = 0x00000018, // RenamePath - AFC_OP_SET_FS_BS = 0x00000019, // SetFSBlockSize (0x800000) - AFC_OP_SET_SOCKET_BS = 0x0000001A, // SetSocketBlockSize (0x800000) - AFC_OP_FILE_LOCK = 0x0000001B, // FileRefLock - AFC_OP_MAKE_LINK = 0x0000001C, // MakeLink - AFC_OP_SET_FILE_TIME = 0x0000001E // set st_mtime + AFC_OP_STATUS = 0x00000001, /* Status */ + AFC_OP_DATA = 0x00000002, /* Data */ + AFC_OP_READ_DIR = 0x00000003, /* ReadDir */ + AFC_OP_READ_FILE = 0x00000004, /* ReadFile */ + AFC_OP_WRITE_FILE = 0x00000005, /* WriteFile */ + AFC_OP_WRITE_PART = 0x00000006, /* WritePart */ + AFC_OP_TRUNCATE = 0x00000007, /* TruncateFile */ + AFC_OP_REMOVE_PATH = 0x00000008, /* RemovePath */ + AFC_OP_MAKE_DIR = 0x00000009, /* MakeDir */ + AFC_OP_GET_FILE_INFO = 0x0000000a, /* GetFileInfo */ + AFC_OP_GET_DEVINFO = 0x0000000b, /* GetDeviceInfo */ + AFC_OP_WRITE_FILE_ATOM = 0x0000000c, /* WriteFileAtomic (tmp file+rename) */ + AFC_OP_FILE_OPEN = 0x0000000d, /* FileRefOpen */ + AFC_OP_FILE_OPEN_RES = 0x0000000e, /* FileRefOpenResult */ + AFC_OP_READ = 0x0000000f, /* FileRefRead */ + AFC_OP_WRITE = 0x00000010, /* FileRefWrite */ + AFC_OP_FILE_SEEK = 0x00000011, /* FileRefSeek */ + AFC_OP_FILE_TELL = 0x00000012, /* FileRefTell */ + AFC_OP_FILE_TELL_RES = 0x00000013, /* FileRefTellResult */ + AFC_OP_FILE_CLOSE = 0x00000014, /* FileRefClose */ + AFC_OP_FILE_SET_SIZE = 0x00000015, /* FileRefSetFileSize (ftruncate) */ + AFC_OP_GET_CON_INFO = 0x00000016, /* GetConnectionInfo */ + AFC_OP_SET_CON_OPTIONS = 0x00000017, /* SetConnectionOptions */ + AFC_OP_RENAME_PATH = 0x00000018, /* RenamePath */ + AFC_OP_SET_FS_BS = 0x00000019, /* SetFSBlockSize (0x800000) */ + AFC_OP_SET_SOCKET_BS = 0x0000001A, /* SetSocketBlockSize (0x800000) */ + AFC_OP_FILE_LOCK = 0x0000001B, /* FileRefLock */ + AFC_OP_MAKE_LINK = 0x0000001C, /* MakeLink */ + AFC_OP_SET_FILE_TIME = 0x0000001E /* set st_mtime */ }; diff --git a/src/device_link_service.h b/src/device_link_service.h index c80686d..8b58ccf 100644 --- a/src/device_link_service.h +++ b/src/device_link_service.h @@ -32,12 +32,13 @@ #define DEVICE_LINK_SERVICE_E_UNKNOWN_ERROR -256 +/** Represents an error code. */ +typedef int16_t device_link_service_error_t; struct device_link_service_client_private { property_list_service_client_t parent; }; -typedef int16_t device_link_service_error_t; typedef struct device_link_service_client_private *device_link_service_client_t; device_link_service_error_t device_link_service_client_new(idevice_t device, uint16_t port, device_link_service_client_t *client); diff --git a/src/idevice.c b/src/idevice.c index 0bdf3f5..b72b623 100644 --- a/src/idevice.c +++ b/src/idevice.c @@ -172,7 +172,8 @@ idevice_error_t idevice_new(idevice_t * device, const char *uuid) return IDEVICE_E_NO_DEVICE; } -/** Cleans up an idevice structure, then frees the structure itself. +/** + * Cleans up an idevice structure, then frees the structure itself. * This is a library-level function; deals directly with the device to tear * down relations, but otherwise is mostly internal. * @@ -422,6 +423,9 @@ idevice_error_t idevice_connection_receive(idevice_connection_t connection, char return internal_connection_receive(connection, data, len, recv_bytes); } +/** + * Gets the handle of the device. Depends on the connection type. + */ idevice_error_t idevice_get_handle(idevice_t device, uint32_t *handle) { if (!device) @@ -436,6 +440,9 @@ idevice_error_t idevice_get_handle(idevice_t device, uint32_t *handle) return IDEVICE_E_UNKNOWN_ERROR; } +/** + * Gets the unique id for the device. + */ idevice_error_t idevice_get_uuid(idevice_t device, char **uuid) { if (!device) @@ -469,10 +476,10 @@ static ssize_t internal_ssl_read(gnutls_transport_ptr_t transport, char *buffer, } debug_info("post-read we got %i bytes", bytes); - // increase read count + /* increase read count */ tbytes += bytes; - // fill the buffer with what we got right now + /* fill the buffer with what we got right now */ memcpy(buffer + pos_start_fill, recv_buffer, bytes); pos_start_fill += bytes; @@ -538,7 +545,7 @@ idevice_error_t idevice_connection_enable_ssl(idevice_connection_t connection) ssl_data_t ssl_data_loc = (ssl_data_t)malloc(sizeof(struct ssl_data_private)); - // Set up GnuTLS... + /* Set up GnuTLS... */ debug_info("enabling SSL mode"); errno = 0; gnutls_global_init(); @@ -558,7 +565,7 @@ idevice_error_t idevice_connection_enable_ssl(idevice_connection_t connection) gnutls_protocol_set_priority(ssl_data_loc->session, protocol_priority); gnutls_mac_set_priority(ssl_data_loc->session, mac_priority); } - gnutls_credentials_set(ssl_data_loc->session, GNUTLS_CRD_CERTIFICATE, ssl_data_loc->certificate); // this part is killing me. + gnutls_credentials_set(ssl_data_loc->session, GNUTLS_CRD_CERTIFICATE, ssl_data_loc->certificate); /* this part is killing me. */ debug_info("GnuTLS step 1..."); gnutls_transport_set_ptr(ssl_data_loc->session, (gnutls_transport_ptr_t)connection); diff --git a/src/lockdown.c b/src/lockdown.c index 25a6c6a..515c58e 100644 --- a/src/lockdown.c +++ b/src/lockdown.c @@ -1,6 +1,6 @@ /* * lockdown.c - * libimobiledevice built-in lockdownd client + * com.apple.mobile.lockdownd service implementation. * * Copyright (c) 2008 Zach C. All Rights Reserved. * @@ -124,15 +124,14 @@ static void plist_dict_add_label(plist_t plist, const char *label) } /** - * Closes the lockdownd communication session, by sending the StopSession - * Request to the device. + * Closes the lockdownd session by sending the StopSession request. * * @see lockdownd_start_session * - * @param control The lockdown client + * @param client The lockdown client * @param session_id The id of a running session * - * @return an error code (LOCKDOWN_E_SUCCESS on success) + * @return LOCKDOWN_E_SUCCESS on success, NP_E_INVALID_ARG when client is NULL */ lockdownd_error_t lockdownd_stop_session(lockdownd_client_t client, const char *session_id) { @@ -178,11 +177,13 @@ lockdownd_error_t lockdownd_stop_session(lockdownd_client_t client, const char * return ret; } -/** Closes the lockdownd client and does the necessary housekeeping. +/** + * Closes the lockdownd client session if one is running and frees up the + * lockdownd_client struct. * * @param client The lockdown client * - * @return an error code (LOCKDOWN_E_SUCCESS on success) + * @return LOCKDOWN_E_SUCCESS on success, NP_E_INVALID_ARG when client is NULL */ lockdownd_error_t lockdownd_client_free(lockdownd_client_t client) { @@ -229,12 +230,14 @@ void lockdownd_client_set_label(lockdownd_client_t client, const char *label) } } -/** Polls the device for lockdownd data. +/** + * Receives a plist from lockdownd. * - * @param control The lockdownd client + * @param client The lockdownd client * @param plist The plist to store the received data * - * @return an error code (LOCKDOWN_E_SUCCESS on success) + * @return LOCKDOWN_E_SUCCESS on success, NP_E_INVALID_ARG when client or + * plist is NULL */ lockdownd_error_t lockdownd_receive(lockdownd_client_t client, plist_t *plist) { @@ -254,7 +257,8 @@ lockdownd_error_t lockdownd_receive(lockdownd_client_t client, plist_t *plist) return ret; } -/** Sends lockdownd data to the device +/** + * Sends a plist to lockdownd. * * @note This function is low-level and should only be used if you need to send * a new type of message. @@ -262,7 +266,8 @@ lockdownd_error_t lockdownd_receive(lockdownd_client_t client, plist_t *plist) * @param client The lockdownd client * @param plist The plist to send * - * @return an error code (LOCKDOWN_E_SUCCESS on success) + * @return LOCKDOWN_E_SUCCESS on success, NP_E_INVALID_ARG when client or + * plist is NULL */ lockdownd_error_t lockdownd_send(lockdownd_client_t client, plist_t plist) { @@ -279,13 +284,14 @@ lockdownd_error_t lockdownd_send(lockdownd_client_t client, plist_t plist) return ret; } -/** Query the type of the service daemon. Depending on whether the device is +/** + * 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 lockdownd client - * @param type The type returned by the service daemon. Can be NULL to ignore. + * @param type The type returned by the service daemon. Pass NULL to ignore. * - * @return an error code (LOCKDOWN_E_SUCCESS on success) + * @return LOCKDOWN_E_SUCCESS on success, NP_E_INVALID_ARG when client is NULL */ lockdownd_error_t lockdownd_query_type(lockdownd_client_t client, char **type) { @@ -325,14 +331,15 @@ lockdownd_error_t lockdownd_query_type(lockdownd_client_t client, char **type) return ret; } -/** Retrieves a preferences plist using an optional domain and/or key name. +/** + * Retrieves a preferences plist using an optional domain and/or key name. * - * @param client an initialized lockdownd client. - * @param domain the domain to query on or NULL for global domain - * @param key the key name to request or NULL to query for all keys - * @param value a plist node representing the result value node + * @param client An initialized lockdownd client. + * @param domain The domain to query on or NULL for global domain + * @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 an error code (LOCKDOWN_E_SUCCESS on success) + * @return LOCKDOWN_E_SUCCESS on success, NP_E_INVALID_ARG when client is NULL */ lockdownd_error_t lockdownd_get_value(lockdownd_client_t client, const char *domain, const char *key, plist_t *value) { @@ -387,14 +394,16 @@ lockdownd_error_t lockdownd_get_value(lockdownd_client_t client, const char *dom return ret; } -/** Sets a preferences value using a plist and optional domain and/or key name. +/** + * Sets a preferences value using a plist and optional by domain and/or key name. * * @param client an initialized lockdownd client. * @param domain the domain to query on or NULL for global domain * @param key the key name to set the value or NULL to set a value dict plist * @param value a plist node of any node type representing the value to set * - * @return an error code (LOCKDOWN_E_SUCCESS on success) + * @return LOCKDOWN_E_SUCCESS on success, NP_E_INVALID_ARG when client or + * value is NULL */ lockdownd_error_t lockdownd_set_value(lockdownd_client_t client, const char *domain, const char *key, plist_t value) { @@ -444,15 +453,16 @@ lockdownd_error_t lockdownd_set_value(lockdownd_client_t client, const char *dom return ret; } -/** Removes a preference node on the device by domain and/or key name +/** + * Removes a preference node by domain and/or key name. * * @note: Use with caution as this could remove vital information on the device * - * @param client an initialized lockdownd client. - * @param domain the domain to query on or NULL for global domain - * @param key the key name to remove or NULL remove all keys for the current domain + * @param client An initialized lockdownd client. + * @param domain The domain to query on or NULL for global domain + * @param key The key name to remove or NULL remove all keys for the current domain * - * @return an error code (LOCKDOWN_E_SUCCESS on success) + * @return LOCKDOWN_E_SUCCESS on success, NP_E_INVALID_ARG when client is NULL */ lockdownd_error_t lockdownd_remove_value(lockdownd_client_t client, const char *domain, const char *key) { @@ -501,9 +511,14 @@ lockdownd_error_t lockdownd_remove_value(lockdownd_client_t client, const char * return ret; } -/** Asks for the device's unique id. Part of the lockdownd handshake. +/** + * Returns the unique id of the device from lockdownd. * - * @return an error code (LOCKDOWN_E_SUCCESS on success) + * @param client An initialized lockdownd client. + * @param uuid Holds the unique id of the device. The caller is responsible + * for freeing the memory. + * + * @return LOCKDOWN_E_SUCCESS on success */ lockdownd_error_t lockdownd_get_device_uuid(lockdownd_client_t client, char **uuid) { @@ -521,9 +536,14 @@ lockdownd_error_t lockdownd_get_device_uuid(lockdownd_client_t client, char **uu return ret; } -/** Askes for the device's public key. Part of the lockdownd handshake. +/** + * Retrieves the public key of the device from lockdownd. * - * @return an error code (LOCKDOWN_E_SUCCESS on success) + * @param client An initialized lockdownd client. + * @param public_key Holds the public key of the device. The caller is + * responsible for freeing the memory. + * + * @return LOCKDOWN_E_SUCCESS on success */ lockdownd_error_t lockdownd_get_device_public_key(lockdownd_client_t client, gnutls_datum_t * public_key) { @@ -546,12 +566,14 @@ lockdownd_error_t lockdownd_get_device_public_key(lockdownd_client_t client, gnu return ret; } -/** Askes for the device's name. - * - * @param client The pointer to the location of the new lockdownd_client +/** + * Retrieves the name of the device from lockdownd set by the user. * + * @param client An initialized lockdownd client. + * @param device_name Holds the name of the device. The caller is + * responsible for freeing the memory. * - * @return an error code (LOCKDOWN_E_SUCCESS on success) + * @return LOCKDOWN_E_SUCCESS on success */ lockdownd_error_t lockdownd_get_device_name(lockdownd_client_t client, char **device_name) { @@ -570,13 +592,17 @@ lockdownd_error_t lockdownd_get_device_name(lockdownd_client_t client, char **de return ret; } -/** Creates a lockdownd client for the device. +/** + * Creates a new lockdownd client for the device. * - * @param phone The device to create a lockdownd client for + * @note This function does not pair with the device or start a session. This + * has to be done manually by the caller after the client is created. + * + * @param device The device to create a lockdownd client for * @param client The pointer to the location of the new lockdownd_client - * @param label The label to use for communication. Usually the program name + * @param label The label to use for communication. Usually the program name. * - * @return an error code (LOCKDOWN_E_SUCCESS on success) + * @return LOCKDOWN_E_SUCCESS on success, NP_E_INVALID_ARG when client is NULL */ lockdownd_error_t lockdownd_client_new(idevice_t device, lockdownd_client_t *client, const char *label) { @@ -609,15 +635,18 @@ lockdownd_error_t lockdownd_client_new(idevice_t device, lockdownd_client_t *cli return ret; } -/** Creates a lockdownd client for the device and starts initial handshake. - * The handshake consists of query_type, validate_pair, pair and - * start_session calls. +/** + * Creates a new lockdownd client for the device and starts initial handshake. + * The handshake consists out of query_type, validate_pair, pair and + * start_session calls. It uses the internal pairing record management. * - * @param phone The device to create a lockdownd client for + * @param device The device to create a lockdownd client for * @param client The pointer to the location of the new lockdownd_client - * @param label The label to use for communication. Usually the program name + * @param label The label to use for communication. Usually the program name. + * Pass NULL to disable sending the label in requests to lockdownd. * - * @return an error code (LOCKDOWN_E_SUCCESS on success) + * @return LOCKDOWN_E_SUCCESS on success, NP_E_INVALID_ARG when client is NULL, + * LOCKDOWN_E_INVALID_CONF if configuration data is wrong */ lockdownd_error_t lockdownd_client_new_with_handshake(idevice_t device, lockdownd_client_t *client, const char *label) { @@ -690,6 +719,14 @@ lockdownd_error_t lockdownd_client_new_with_handshake(idevice_t device, lockdown return ret; } +/** + * Returns a new plist from the supplied lockdownd pair record. The caller is + * responsible for freeing the plist. + * + * @param pair_record The pair record to create a plist from. + * + * @return A pair record plist from the device, NULL if pair_record is not set + */ static plist_t lockdownd_pair_record_to_plist(lockdownd_pair_record_t pair_record) { if (!pair_record) @@ -712,6 +749,17 @@ static plist_t lockdownd_pair_record_to_plist(lockdownd_pair_record_t pair_recor return dict; } +/** + * Generates a new pairing record plist and required certificates for the + * supplied public key of the device and the host_id of the caller's host + * computer. + * + * @param public_key The public key of the device. + * @param host_id The HostID to use for the pair record plist. + * @param pair_record_plist Holds the generated pair record. + * + * @return LOCKDOWN_E_SUCCESS on success + */ static lockdownd_error_t generate_pair_record_plist(gnutls_datum_t public_key, char *host_id, plist_t *pair_record_plist) { lockdownd_error_t ret = LOCKDOWN_E_UNKNOWN_ERROR; @@ -743,7 +791,8 @@ static lockdownd_error_t generate_pair_record_plist(gnutls_datum_t public_key, c return ret; } -/** Function used internally by lockdownd_pair() and lockdownd_validate_pair() +/** + * Function used internally by lockdownd_pair() and lockdownd_validate_pair() * * @param client The lockdown client to pair with. * @param pair_record The pair record to use for pairing. If NULL is passed, then @@ -751,10 +800,17 @@ static lockdownd_error_t generate_pair_record_plist(gnutls_datum_t public_key, c * generated automatically when pairing is done for the first time. * @param verb This is either "Pair", "ValidatePair" or "Unpair". * - * @return an error code (LOCKDOWN_E_SUCCESS on success) + * @return LOCKDOWN_E_SUCCESS on success, NP_E_INVALID_ARG when client is NULL, + * LOCKDOWN_E_PLIST_ERROR if the pair_record certificates are wrong, + * LOCKDOWN_E_PAIRING_FAILED if the pairing failed, + * LOCKDOWN_E_PASSWORD_PROTECTED if the device is password protected, + * LOCKDOWN_E_INVALID_HOST_ID if the device does not know the caller's host id */ static lockdownd_error_t lockdownd_do_pair(lockdownd_client_t client, lockdownd_pair_record_t pair_record, const char *verb) { + if (!client) + return LOCKDOWN_E_INVALID_ARG; + lockdownd_error_t ret = LOCKDOWN_E_UNKNOWN_ERROR; plist_t dict = NULL; plist_t dict_record = NULL; @@ -855,15 +911,18 @@ static lockdownd_error_t lockdownd_do_pair(lockdownd_client_t client, lockdownd_ } /** - * Pairs the device with the given HostID. - * It's part of the lockdownd handshake. + * Pairs the device using the supplied pair record. * * @param client The lockdown client to pair with. * @param pair_record The pair record to use for pairing. If NULL is passed, then * the pair records from the current machine are used. New records will be * generated automatically when pairing is done for the first time. * - * @return an error code (LOCKDOWN_E_SUCCESS on success) + * @return LOCKDOWN_E_SUCCESS on success, NP_E_INVALID_ARG when client is NULL, + * LOCKDOWN_E_PLIST_ERROR if the pair_record certificates are wrong, + * LOCKDOWN_E_PAIRING_FAILED if the pairing failed, + * LOCKDOWN_E_PASSWORD_PROTECTED if the device is password protected, + * LOCKDOWN_E_INVALID_HOST_ID if the device does not know the caller's host id */ lockdownd_error_t lockdownd_pair(lockdownd_client_t client, lockdownd_pair_record_t pair_record) { @@ -871,17 +930,21 @@ lockdownd_error_t lockdownd_pair(lockdownd_client_t client, lockdownd_pair_recor } /** - * Pairs the device with the given HostID. The difference to lockdownd_pair() - * is that the specified host will become trusted host of the device. - * It's part of the lockdownd handshake. + * Validates if the device is paired with the given HostID. If succeeded them + * specified host will become trusted host of the device indicated by the + * lockdownd preference named TrustedHostAttached. Otherwise the host must because + * paired using lockdownd_pair() first. * * @param client The lockdown client to pair with. * @param pair_record The pair record to validate pairing with. If NULL is - * passed, then the pair records from the current machine are used. - * New records will be generated automatically when pairing is done - * for the first time. + * passed, then the pair record is read from the internal pairing record + * management. * - * @return an error code (LOCKDOWN_E_SUCCESS on success) + * @return LOCKDOWN_E_SUCCESS on success, NP_E_INVALID_ARG when client is NULL, + * LOCKDOWN_E_PLIST_ERROR if the pair_record certificates are wrong, + * LOCKDOWN_E_PAIRING_FAILED if the pairing failed, + * LOCKDOWN_E_PASSWORD_PROTECTED if the device is password protected, + * LOCKDOWN_E_INVALID_HOST_ID if the device does not know the caller's host id */ lockdownd_error_t lockdownd_validate_pair(lockdownd_client_t client, lockdownd_pair_record_t pair_record) { @@ -890,13 +953,17 @@ lockdownd_error_t lockdownd_validate_pair(lockdownd_client_t client, lockdownd_p /** * Unpairs the device with the given HostID and removes the pairing records - * from the device and host. + * from the device and host if the internal pairing record management is used. * * @param client The lockdown client to pair with. * @param pair_record The pair record to use for unpair. If NULL is passed, then * the pair records from the current machine are used. * - * @return an error code (LOCKDOWN_E_SUCCESS on success) + * @return LOCKDOWN_E_SUCCESS on success, NP_E_INVALID_ARG when client is NULL, + * LOCKDOWN_E_PLIST_ERROR if the pair_record certificates are wrong, + * LOCKDOWN_E_PAIRING_FAILED if the pairing failed, + * LOCKDOWN_E_PASSWORD_PROTECTED if the device is password protected, + * LOCKDOWN_E_INVALID_HOST_ID if the device does not know the caller's host id */ lockdownd_error_t lockdownd_unpair(lockdownd_client_t client, lockdownd_pair_record_t pair_record) { @@ -908,7 +975,7 @@ lockdownd_error_t lockdownd_unpair(lockdownd_client_t client, lockdownd_pair_rec * * @param client The lockdown client * - * @return an error code (LOCKDOWN_E_SUCCESS on success) + * @return LOCKDOWN_E_SUCCESS on success, NP_E_INVALID_ARG when client is NULL */ lockdownd_error_t lockdownd_enter_recovery(lockdownd_client_t client) { @@ -939,12 +1006,12 @@ lockdownd_error_t lockdownd_enter_recovery(lockdownd_client_t client) } /** - * Performs the Goodbye Request to tell the device the communication - * session is now closed. + * Sends the Goodbye request to lockdownd signaling the end of communication. * * @param client The lockdown client * - * @return an error code (LOCKDOWN_E_SUCCESS on success) + * @return LOCKDOWN_E_SUCCESS on success, NP_E_INVALID_ARG when client is NULL, + * LOCKDOWN_E_PLIST_ERROR if the device did not acknowledge the request */ lockdownd_error_t lockdownd_goodbye(lockdownd_client_t client) { @@ -978,10 +1045,18 @@ lockdownd_error_t lockdownd_goodbye(lockdownd_client_t client) return ret; } -/** Generates the device certificate from the public key as well as the host - * and root certificates. +/** + * Generates the device certificate from the public key as well as the host + * and root certificates. * - * @return an error code (LOCKDOWN_E_SUCCESS on success) + * @param public_key The public key of the device to use for generation. + * @param odevice_cert Holds the generated device certificate. + * @param ohost_cert Holds the generated host certificate. + * @param oroot_cert Holds the generated root certificate. + * + * @return LOCKDOWN_E_SUCCESS on success, NP_E_INVALID_ARG when a parameter is NULL, + * LOCKDOWN_E_INVALID_CONF if the internal configuration system failed, + * LOCKDOWN_E_SSL_ERROR if the certificates could not be generated */ lockdownd_error_t lockdownd_gen_pair_cert(gnutls_datum_t public_key, gnutls_datum_t * odevice_cert, gnutls_datum_t * ohost_cert, gnutls_datum_t * oroot_cert) @@ -1116,15 +1191,18 @@ lockdownd_error_t lockdownd_gen_pair_cert(gnutls_datum_t public_key, gnutls_datu return ret; } -/** Starts communication with lockdownd after the device has been paired, - * and if the device requires it, switches to SSL mode. +/** + * Opens a session with lockdownd and switches to SSL mode if device wants it. * * @param client The lockdownd client * @param host_id The HostID of the computer - * @param session_id The session_id of the created session + * @param session_id The new session_id of the created session * @param ssl_enabled Whether SSL communication is used in the session * - * @return an error code (LOCKDOWN_E_SUCCESS on success) + * @return LOCKDOWN_E_SUCCESS on success, NP_E_INVALID_ARG when a client or + * host_id is NULL, LOCKDOWN_E_PLIST_ERROR if the response plist had errors, + * LOCKDOWN_E_INVALID_HOST_ID if the device does not know the supplied HostID, + * LOCKDOWN_E_SSL_ERROR if enabling SSL communication failed */ lockdownd_error_t lockdownd_start_session(lockdownd_client_t client, const char *host_id, char **session_id, int *ssl_enabled) { @@ -1212,13 +1290,17 @@ lockdownd_error_t lockdownd_start_session(lockdownd_client_t client, const char return ret; } -/** Command to start the desired service +/** + * Requests to start a service and retrieve it's port on success. * * @param client The lockdownd client * @param service The name of the service to start * @param port The port number the service was started on - * @return an error code (LOCKDOWN_E_SUCCESS on success) + * @return LOCKDOWN_E_SUCCESS on success, NP_E_INVALID_ARG if a parameter + * is NULL, LOCKDOWN_E_INVALID_SERVICE if the requested service is not known + * by the device, LOCKDOWN_E_START_SERVICE_FAILED if the service could not because + * started by the device */ lockdownd_error_t lockdownd_start_service(lockdownd_client_t client, const char *service, uint16_t *port) { @@ -1300,10 +1382,15 @@ lockdownd_error_t lockdownd_start_service(lockdownd_client_t client, const char * * @see http://iphone-docs.org/doku.php?id=docs:protocols:activation * - * @param control The lockdown client + * @param client The lockdown client * @param activation_record The activation record plist dictionary * - * @return an error code (LOCKDOWN_E_SUCCESS on success) + * @return LOCKDOWN_E_SUCCESS on success, NP_E_INVALID_ARG when client or + * activation_record is NULL, LOCKDOWN_E_NO_RUNNING_SESSION if no session is + * open, LOCKDOWN_E_PLIST_ERROR if the received plist is broken, + * LOCKDOWN_E_ACTIVATION_FAILED if the activation failed, + * LOCKDOWN_E_INVALID_ACTIVATION_RECORD if the device reports that the + * activation_record is invalid */ lockdownd_error_t lockdownd_activate(lockdownd_client_t client, plist_t activation_record) { @@ -1357,12 +1444,14 @@ lockdownd_error_t lockdownd_activate(lockdownd_client_t client, plist_t activati } /** - * Deactivates the device, returning it to the locked - * “Activate with iTunes” screen. + * Deactivates the device, returning it to the locked “Activate with iTunes” + * screen. * - * @param control The lockdown client + * @param client The lockdown client * - * @return an error code (LOCKDOWN_E_SUCCESS on success) + * @return LOCKDOWN_E_SUCCESS on success, NP_E_INVALID_ARG when client is NULL, + * LOCKDOWN_E_NO_RUNNING_SESSION if no session is open, + * LOCKDOWN_E_PLIST_ERROR if the received plist is broken */ lockdownd_error_t lockdownd_deactivate(lockdownd_client_t client) { diff --git a/src/mobilebackup.c b/src/mobilebackup.c index c5f0a84..15da0a1 100644 --- a/src/mobilebackup.c +++ b/src/mobilebackup.c @@ -59,6 +59,18 @@ static mobilebackup_error_t mobilebackup_error(device_link_service_error_t err) return MOBILEBACKUP_E_UNKNOWN_ERROR; } +/** + * Connects to the mobilebackup service on the specified device. + * + * @param device The device to connect to. + * @param port Destination port (usually given by lockdownd_start_service). + * @param client Pointer that will be set to a newly allocated + * mobilebackup_client_t upon successful return. + * + * @return MOBILEBACKUP_E_SUCCESS on success, MOBILEBACKUP_E_INVALID ARG if one + * or more parameters are invalid, or DEVICE_LINK_SERVICE_E_BAD_VERSION if + * the mobilebackup version on the device is newer. + */ mobilebackup_error_t mobilebackup_client_new(idevice_t device, uint16_t port, mobilebackup_client_t * client) { @@ -87,6 +99,15 @@ mobilebackup_error_t mobilebackup_client_new(idevice_t device, uint16_t port, return ret; } +/** + * Disconnects a mobilebackup client from the device and frees up the + * mobilebackup client data. + * + * @param client The mobilebackup client to disconnect and free. + * + * @return MOBILEBACKUP_E_SUCCESS on success, or MOBILEBACKUP_E_INVALID_ARG + * if client is NULL. + */ mobilebackup_error_t mobilebackup_client_free(mobilebackup_client_t client) { if (!client) @@ -97,9 +118,10 @@ mobilebackup_error_t mobilebackup_client_free(mobilebackup_client_t client) return err; } -/** Polls the device for MobileBackup data. +/** + * Polls the device for mobilebackup data. * - * @param client The MobileBackup client + * @param client The mobilebackup client * @param plist A pointer to the location where the plist should be stored * * @return an error code @@ -112,12 +134,13 @@ mobilebackup_error_t mobilebackup_receive(mobilebackup_client_t client, plist_t return ret; } -/** Sends MobileBackup data to the device +/** + * Sends mobilebackup data to the device * * @note This function is low-level and should only be used if you need to send * a new type of message. * - * @param client The MobileBackup client + * @param client The mobilebackup client * @param plist The location of the plist to send * * @return an error code diff --git a/src/mobilesync.c b/src/mobilesync.c index 88d8497..47fcfdf 100644 --- a/src/mobilesync.c +++ b/src/mobilesync.c @@ -59,6 +59,18 @@ static mobilesync_error_t mobilesync_error(device_link_service_error_t err) return MOBILESYNC_E_UNKNOWN_ERROR; } +/** + * Connects to the mobilesync service on the specified device. + * + * @param device The device to connect to. + * @param port Destination port (usually given by lockdownd_start_service). + * @param client Pointer that will be set to a newly allocated + * mobilesync_client_t upon successful return. + * + * @return MOBILESYNC_E_SUCCESS on success, MOBILESYNC_E_INVALID ARG if one + * or more parameters are invalid, or DEVICE_LINK_SERVICE_E_BAD_VERSION if + * the mobilesync version on the device is newer. + */ mobilesync_error_t mobilesync_client_new(idevice_t device, uint16_t port, mobilesync_client_t * client) { @@ -87,6 +99,15 @@ mobilesync_error_t mobilesync_client_new(idevice_t device, uint16_t port, return ret; } +/** + * Disconnects a mobilesync client from the device and frees up the + * mobilesync client data. + * + * @param client The mobilesync client to disconnect and free. + * + * @return MOBILESYNC_E_SUCCESS on success, or MOBILESYNC_E_INVALID_ARG + * if client is NULL. + */ mobilesync_error_t mobilesync_client_free(mobilesync_client_t client) { if (!client) @@ -97,9 +118,10 @@ mobilesync_error_t mobilesync_client_free(mobilesync_client_t client) return err; } -/** Polls the device for MobileSync data. +/** + * Polls the device for mobilesync data. * - * @param client The MobileSync client + * @param client The mobilesync client * @param plist A pointer to the location where the plist should be stored * * @return an error code @@ -112,12 +134,13 @@ mobilesync_error_t mobilesync_receive(mobilesync_client_t client, plist_t * plis return ret; } -/** Sends MobileSync data to the device +/** + * Sends mobilesync data to the device * * @note This function is low-level and should only be used if you need to send * a new type of message. * - * @param client The MobileSync client + * @param client The mobilesync client * @param plist The location of the plist to send * * @return an error code diff --git a/src/sbservices.c b/src/sbservices.c index 91f4b9c..076e25d 100644 --- a/src/sbservices.c +++ b/src/sbservices.c @@ -208,7 +208,7 @@ sbservices_error_t sbservices_set_icon_state(sbservices_client_t client, plist_t if (res != SBSERVICES_E_SUCCESS) { debug_info("could not send plist, error %d", res); } - // NO RESPONSE + /* NO RESPONSE */ if (dict) { plist_free(dict); diff --git a/src/screenshotr.h b/src/screenshotr.h index 5ba93b0..df6774a 100644 --- a/src/screenshotr.h +++ b/src/screenshotr.h @@ -1,4 +1,4 @@ -/* +/* * screenshotr.h * com.apple.mobile.screenshotr service header file. * diff --git a/src/userpref.c b/src/userpref.c index 3a8a9d6..59c61b6 100644 --- a/src/userpref.c +++ b/src/userpref.c @@ -42,7 +42,8 @@ #define LIBIMOBILEDEVICE_HOST_CERTIF "HostCertificate.pem" -/** Creates a freedesktop compatible configuration directory. +/** + * Creates a freedesktop compatible configuration directory. */ static void userpref_create_config_dir(void) { @@ -60,7 +61,8 @@ static int get_rand(int min, int max) return retval; } -/** Generates a valid HostID (which is actually a UUID). +/** + * Generates a valid HostID (which is actually a UUID). * * @return A null terminated string containing a valid HostID. */ @@ -85,7 +87,8 @@ static char *userpref_generate_host_id() return hostid; } -/** Store HostID in config file. +/** + * Store HostID in config file. * * @param host_id A null terminated string containing a valid HostID. */ @@ -123,7 +126,8 @@ static int userpref_set_host_id(const char *host_id) return 1; } -/** Reads the HostID from a previously generated configuration file. +/** + * Reads the HostID from a previously generated configuration file. * * @note It is the responsibility of the calling function to free the returned host_id * @@ -158,7 +162,8 @@ void userpref_get_host_id(char **host_id) debug_info("Using %s as HostID", *host_id); } -/** Determines whether this device has been connected to this system before. +/** + * Determines whether this device has been connected to this system before. * * @param uid The device uid as given by the device. * @@ -180,8 +185,9 @@ int userpref_has_device_public_key(const char *uuid) return ret; } -/** Mark the device (as represented by the key) as having connected to this - * configuration. +/** + * Mark the device (as represented by the key) as having connected to this + * configuration. * * @param public_key The public key given by the device * @@ -213,7 +219,8 @@ userpref_error_t userpref_set_device_public_key(const char *uuid, gnutls_datum_t return USERPREF_E_SUCCESS; } -/** Remove the public key stored for the device with uuid from this host. +/** + * Remove the public key stored for the device with uuid from this host. * * @param uuid The uuid of the device * @@ -237,7 +244,8 @@ userpref_error_t userpref_remove_device_public_key(const char *uuid) return USERPREF_E_SUCCESS; } -/** Private function which reads the given file into a gnutls structure. +/** + * Private function which reads the given file into a gnutls structure. * * @param file The filename of the file to read * @param data The pointer at which to store the data. @@ -266,7 +274,8 @@ static int userpref_get_file_contents(const char *file, gnutls_datum_t * data) return success; } -/** Private function which generate private keys and certificates. +/** + * Private function which generate private keys and certificates. * * @return 1 if keys were successfully generated, 0 otherwise */ @@ -365,7 +374,8 @@ static userpref_error_t userpref_gen_keys_and_cert(void) return ret; } -/** Private function which import the given key into a gnutls structure. +/** + * Private function which import the given key into a gnutls structure. * * @param key_name The filename of the private key to import. * @param key the gnutls key structure. @@ -387,7 +397,8 @@ static userpref_error_t userpref_import_key(const char* key_name, gnutls_x509_pr return ret; } -/** Private function which import the given certificate into a gnutls structure. +/** + * Private function which import the given certificate into a gnutls structure. * * @param crt_name The filename of the certificate to import. * @param cert the gnutls certificate structure. @@ -409,7 +420,8 @@ static userpref_error_t userpref_import_crt(const char* crt_name, gnutls_x509_cr return ret; } -/** Function to retrieve host keys and certificates. +/** + * Function to retrieve host keys and certificates. * This function trigger key generation if they do not exists yet or are invalid. * * @note This function can take few seconds to complete (typically 5 seconds) @@ -459,7 +471,8 @@ userpref_error_t userpref_get_keys_and_certs(gnutls_x509_privkey_t root_privkey, return ret; } -/** Function to retrieve certificates encoded in PEM format. +/** + * Function to retrieve certificates encoded in PEM format. * * @param pem_root_cert The root certificate. * @param pem_host_cert The host certificate. @@ -480,7 +493,8 @@ userpref_error_t userpref_get_certs_as_pem(gnutls_datum_t *pem_root_cert, gnutls return USERPREF_E_INVALID_CONF; } -/** Create and save a configuration file containing the given data. +/** + * Create and save a configuration file containing the given data. * * @note: All fields must specified and be non-null * -- cgit v1.1-32-gdbae