summaryrefslogtreecommitdiffstats
path: root/src
diff options
context:
space:
mode:
authorGravatar Martin Szulecki2010-03-16 03:13:38 +0100
committerGravatar Martin Szulecki2010-03-16 03:13:38 +0100
commit08d2af5d611319748afba2aaba5e6c8a99f1b396 (patch)
tree8bf4a3533f2acf11368dc37a9c653689ace99b77 /src
parent3e0c5021100c879ff7d0776d4c7bb4f0ec88e0d7 (diff)
downloadlibimobiledevice-08d2af5d611319748afba2aaba5e6c8a99f1b396.tar.gz
libimobiledevice-08d2af5d611319748afba2aaba5e6c8a99f1b396.tar.bz2
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.
Diffstat (limited to 'src')
-rw-r--r--src/afc.c213
-rw-r--r--src/afc.h58
-rw-r--r--src/device_link_service.h3
-rw-r--r--src/idevice.c17
-rw-r--r--src/lockdown.c247
-rw-r--r--src/mobilebackup.c31
-rw-r--r--src/mobilesync.c31
-rw-r--r--src/sbservices.c2
-rw-r--r--src/screenshotr.h2
-rw-r--r--src/userpref.c44
10 files changed, 416 insertions, 232 deletions
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
*