Massive AFC cleanup, started with Zach's documentation.

1 files changed, 511 insertions, 213 deletions

diff --git a/src/AFC.c b/src/AFC.c
index e3f0bba..0f454a3 100644
--- a/src/AFC.c
+++ b/src/AFC.c
@@ -19,122 +19,182 @@
  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA 
  */
 
+#include <stdio.h>
 #include "AFC.h"
 #include "plist.h"
+
 // This is the maximum size an AFC data packet can be
 const int MAXIMUM_PACKET_SIZE = (2 << 15) - 32;
 
 extern int debug;
 
-
-/* Locking, for thread-safety (well... kind of, hehe) */
+/** Locks an AFC client, done for thread safety stuff
+ * 
+ * @param client The AFC client connection to lock
+ */
 static void afc_lock(AFClient *client) {
-        if (debug) printf("In the midst of a lock...\n");
+        if (debug) fprintf(stderr, "Locked\n");
         while (client->lock) {
                 usleep(500); // they say it's obsolete, but whatever
         }
         client->lock = 1;
 }
 
+/** Unlocks an AFC client, done for thread safety stuff.
+ * 
+ * @param client The AFC 
+ */
 static void afc_unlock(AFClient *client) { // just to be pretty 
-        if (debug) printf("Unlock!\n");
+        if (debug) fprintf(stderr, "Unlocked\n");
         client->lock = 0; 
 }
 
-/* main AFC functions */
-
+/** Makes a connection to the AFC service on the phone. 
+ * 
+ * @param phone The iPhone to connect on.
+ * @param s_port The source port. 
+ * @param d_port The destination port. 
+ * 
+ * @return A handle to the newly-connected client or NULL upon error.
+ */
 AFClient *afc_connect(iPhone *phone, int s_port, int d_port) {
-        if (!phone) return NULL;
         AFClient *client = (AFClient*)malloc(sizeof(AFClient));
+        
+        if (!phone) return NULL;
+        
+        // Attempt connection
         client->connection = mux_connect(phone, s_port, d_port);
-        if (!client->connection) { free(client); return NULL; }
-        else {
-                client->afc_packet = (AFCPacket*)malloc(sizeof(AFCPacket));
-                if (client->afc_packet) {
-                        client->afc_packet->packet_num = 0;
-                        client->afc_packet->unknown1 = client->afc_packet->unknown2 = client->afc_packet->unknown3 = client->afc_packet->unknown4 = client->afc_packet->entire_length = client->afc_packet->this_length = 0;
-                        client->afc_packet->header1 = 0x36414643;
-                        client->afc_packet->header2 = 0x4141504C;
-                        client->file_handle = 0;
-                        client->lock = 0;
-                        return client;
-                } else {
-                        mux_close_connection(client->connection);
-                        free(client);
-                        return NULL;
-                }
+        if (!client->connection) {
+                free(client);
+                return NULL;
         }
-        
-        return NULL; // should never get to this point
+
+        // Allocate a packet
+        client->afc_packet = (AFCPacket*)malloc(sizeof(AFCPacket));
+        if (!client->afc_packet) {
+                mux_close_connection(client->connection);
+                free(client);
+                return NULL;
+        }
+
+        client->afc_packet->packet_num = 0;
+        client->afc_packet->unknown1 = 0;
+        client->afc_packet->unknown2 = 0;
+        client->afc_packet->unknown3 = 0;
+        client->afc_packet->unknown4 = 0;
+        client->afc_packet->entire_length = 0;
+        client->afc_packet->this_length = 0;
+        client->afc_packet->header1 = 0x36414643;
+        client->afc_packet->header2 = 0x4141504C;
+        client->file_handle = 0;
+        client->lock = 0;
+
+        return client;
 }
 
+/** Disconnects an AFC client from the phone.
+ * 
+ * @param client The client to disconnect.
+ */
+
 void afc_disconnect(AFClient *client) {
-        // client and its members should never be NULL is assumed here.
         if (!client || !client->connection || !client->afc_packet) return;
+        
         mux_close_connection(client->connection);
         free(client->afc_packet);
         free(client);
 }
 
-static int count_nullspaces(char *string, int number) {
-        int i = 0, nulls = 0;
-        for (i = 0; i < number; i++) {
-                if (string[i] == '\0') nulls++;
-        }
-        return nulls;
-}
 
+/** 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.
+ * 
+ * @return The number of bytes actually sent, or -1 on error. 
+ * 
+ * @warning set client->afc_packet->this_length and
+ *          client->afc_packet->entire_length to 0 before calling this.  The
+ *          reason is that if you set them to different values, it indicates
+ *          you want to send the data as two packets.
+ */
 static int dispatch_AFC_packet(AFClient *client, const char *data, int length) {
         int bytes = 0, offset = 0;
+        char *buffer;   
+
         if (!client || !client->connection || !client->afc_packet) return 0;
         if (!data || !length) length = 0;
         
         client->afc_packet->packet_num++;
-        if (!client->afc_packet->entire_length) client->afc_packet->entire_length = client->afc_packet->this_length = (length) ? sizeof(AFCPacket) + length + 1 : sizeof(AFCPacket);
-        if (!client->afc_packet->this_length) client->afc_packet->this_length = sizeof(AFCPacket);
-                
+        if (!client->afc_packet->entire_length) {
+                client->afc_packet->entire_length = (length) ? sizeof(AFCPacket) + length + 1 : sizeof(AFCPacket);
+                client->afc_packet->this_length = client->afc_packet->entire_length;
+        }
+        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)
         if (client->afc_packet->this_length != client->afc_packet->entire_length) {
-                // 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)
-                char *buffer = (char*)malloc(client->afc_packet->this_length);
+                buffer = (char*)malloc(client->afc_packet->this_length);
                 memcpy(buffer, (char*)client->afc_packet, sizeof(AFCPacket));
                 offset = client->afc_packet->this_length - sizeof(AFCPacket);
-                if (debug) printf("dispatch_AFC_packet: Offset: %i\n", offset);
+                
+                if (debug) fprintf(stderr, "dispatch_AFC_packet: Offset: %i\n", offset);
                 if ((length) < (client->afc_packet->entire_length - client->afc_packet->this_length)) {
-                        if (debug) printf("dispatch_AFC_packet: Length did not resemble what it was supposed to based on the packet.\nlength minus offset: %i\nrest of packet: %i\n", length-offset, client->afc_packet->entire_length - client->afc_packet->this_length);
+                        if (debug){
+                                fprintf(stderr, "dispatch_AFC_packet: Length did not resemble what it was supposed");
+                                fprintf(stderr, "to based on the packet.\n");
+                                fprintf(stderr, "length minus offset: %i\n", length-offset);
+                                fprintf(stderr, "rest of packet: %i\n", client->afc_packet->entire_length - client->afc_packet->this_length);
+                        }
                         free(buffer);
                         return -1;
                 }
-                if (debug) printf("dispatch_AFC_packet: fucked-up packet method (probably a write)\n");
                 memcpy(buffer+sizeof(AFCPacket), data, offset);
                 bytes = mux_send(client->connection, buffer, client->afc_packet->this_length);
                 free(buffer);
-                if (bytes <= 0) { return bytes; }
+                if (bytes <= 0) {
+                        return bytes;
+                }
+                
                 if (debug) {
-                        printf("dispatch_AFC_packet: sent the first now go with the second\n");
-                        printf("Length: %i\n", length-offset);
-                        printf("Buffer: \n");
+                        fprintf(stderr, "dispatch_AFC_packet: sent the first now go with the second\n");
+                        fprintf(stderr, "Length: %i\n", length-offset);
+                        fprintf(stderr, "Buffer: \n");
                         fwrite(data+offset, 1, length-offset, stdout);
                 }
                 
-                
                 bytes = mux_send(client->connection, data+offset, length-offset);
                 return bytes;
         } else {
-                if (debug) printf("dispatch_AFC_packet doin things the old way\n");
+                if (debug) fprintf(stderr, "dispatch_AFC_packet doin things the old way\n");
                 char *buffer = (char*)malloc(sizeof(char) * client->afc_packet->this_length);
-                if (debug) printf("dispatch_AFC_packet packet length = %i\n", client->afc_packet->this_length);
+                if (debug) fprintf(stderr, "dispatch_AFC_packet packet length = %i\n", client->afc_packet->this_length);
                 memcpy(buffer, (char*)client->afc_packet, sizeof(AFCPacket));
-                if (debug) printf("dispatch_AFC_packet packet data follows\n");
+                if (debug) fprintf(stderr, "dispatch_AFC_packet packet data follows\n");
                 if (length > 0) { memcpy(buffer+sizeof(AFCPacket), data, length); buffer[sizeof(AFCPacket)+length] = '\0'; }
                 if (debug) fwrite(buffer, 1, client->afc_packet->this_length, stdout);
-                if (debug) printf("\n");
+                if (debug) fprintf(stderr, "\n");
                 bytes = mux_send(client->connection, buffer, client->afc_packet->this_length);
                 return bytes;
         }
         return -1;
 }
 
+/** 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.
+ * 
+ * @return How much data was received, 0 on successful receive with no errors,
+ *         -1 if there was an error involved with receiving or if the packet
+ *         received raised a non-trivial error condition (i.e. non-zero with
+ *         AFC_ERROR operation)
+ */
+
 static int receive_AFC_data(AFClient *client, char **dump_here) {
         AFCPacket *r_packet;
         char *buffer = (char*)malloc(sizeof(AFCPacket) * 4);
@@ -145,7 +205,7 @@ static int receive_AFC_data(AFClient *client, char **dump_here) {
         bytes = mux_recv(client->connection, buffer, sizeof(AFCPacket) * 4);
         if (bytes <= 0) {
                 free(buffer);
-                printf("Just didn't get enough.\n");
+                fprintf(stderr, "Just didn't get enough.\n");
                 *dump_here = NULL;
                 return -1;
         }
@@ -165,25 +225,22 @@ static int receive_AFC_data(AFClient *client, char **dump_here) {
         uint32 param1 = buffer[sizeof(AFCPacket)];
         free(buffer);
 
-        if (r_packet->operation == AFC_ERROR
-                        && !(client->afc_packet->operation == AFC_DELETE && param1 == 7)
-           )
-        {
-                if (debug) printf("Oops? Bad operation code received: 0x%X, operation=0x%X, param1=%d\n",
+        if (r_packet->operation == AFC_ERROR && !(client->afc_packet->operation == AFC_DELETE && param1 == 7)) {
+                if (debug) fprintf(stderr, "Oops? Bad operation code received: 0x%X, operation=0x%X, param1=%d\n",
                                 r_packet->operation, client->afc_packet->operation, param1);
                 recv_len = r_packet->entire_length - r_packet->this_length;
-                if (debug) printf("recv_len=%d\n", recv_len);
+                if (debug) fprintf(stderr, "recv_len=%d\n", recv_len);
                 if(param1 == 0) {
-                        if (debug) printf("... false alarm, but still\n");
+                        if (debug) fprintf(stderr, "... false alarm, but still\n");
                         *dump_here = NULL;
                         return 0;
                 }
-                else { if (debug) printf("Errno %i\n", param1); }
+                else { if (debug) fprintf(stderr, "Errno %i\n", param1); }
                 free(r_packet);
                 *dump_here = NULL;
                 return -1;
         } else {
-                if (debug) printf("Operation code %x\nFull length %i and this length %i\n", r_packet->operation, r_packet->entire_length, r_packet->this_length);
+                if (debug) fprintf(stderr, "Operation code %x\nFull length %i and this length %i\n", r_packet->operation, r_packet->entire_length, r_packet->this_length);
         }
 
         recv_len = r_packet->entire_length - r_packet->this_length;
@@ -199,21 +256,20 @@ static int receive_AFC_data(AFClient *client, char **dump_here) {
         final_buffer = (char*)malloc(sizeof(char) * recv_len);
         while(current_count < recv_len){
                 bytes = mux_recv(client->connection, buffer, recv_len-current_count);
-                if (debug) printf("receive_AFC_data: still collecting packets\n");
+                if (debug) fprintf(stderr, "receive_AFC_data: still collecting packets\n");
                 if (bytes < 0)
                 {
-                        if(debug) printf("receive_AFC_data: mux_recv failed: %d\n", bytes);
+                        if(debug) fprintf(stderr, "receive_AFC_data: mux_recv failed: %d\n", bytes);
                         break;
                 }
                 if (bytes > recv_len-current_count)
                 {
-                        if(debug) printf("receive_AFC_data: mux_recv delivered too much data\n");
+                        if(debug) fprintf(stderr, "receive_AFC_data: mux_recv delivered too much data\n");
                         break;
                 }
                 if (strstr(buffer, "CFA6LPAA")) {
-                        if (debug) printf("receive_AFC_data: WARNING: there is AFC data in this packet at %ti\n", strstr(buffer, "CFA6LPAA") - buffer);
-                        if (debug) printf("receive_AFC_data: the total packet length is %i\n", bytes);
-                        //continue; // but we do need to continue because packets/headers != data
+                        if (debug) fprintf(stderr, "receive_AFC_data: WARNING: there is AFC data in this packet at %ti\n", strstr(buffer, "CFA6LPAA") - buffer);
+                        if (debug) fprintf(stderr, "receive_AFC_data: the total packet length is %i\n", bytes);
                 }
                         
                 memcpy(final_buffer+current_count, buffer, bytes);
@@ -221,22 +277,26 @@ static int receive_AFC_data(AFClient *client, char **dump_here) {
         }
         free(buffer);
         
-        /*if (bytes <= 0) {
-                free(final_buffer);
-                printf("Didn't get it at the second pass.\n");
-                *dump_here = NULL;
-                return 0;
-        }*/
-        
-        *dump_here = final_buffer; // what they do beyond this point = not my problem
+        *dump_here = final_buffer;
         return current_count;
 }
 
+static int count_nullspaces(char *string, int number) {
+        int i = 0, nulls = 0;
+        
+        for (i = 0; i < number; i++) {
+                if (string[i] == '\0') nulls++;
+        }
+        
+        return nulls;
+}
+
 static char **make_strings_list(char *tokens, int true_length) {
-        if (!tokens || !true_length) return NULL;
         int nulls = 0, i = 0, j = 0;
         char **list = NULL;
         
+        if (!tokens || !true_length) return NULL;
+        
         nulls = count_nullspaces(tokens, true_length);
         list = (char**)malloc(sizeof(char*) * (nulls + 1));
         for (i = 0; i < nulls; i++) {
@@ -244,118 +304,242 @@ static char **make_strings_list(char *tokens, int true_length) {
                 j += strlen(list[i]) + 1;
         }
         list[i] = strdup("");
+        
         return list;
 }
 
+/** 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)
+ * 
+ * @return A char ** list of files in that directory, terminated by an empty
+ *         string for now or NULL if there was an error.
+ */
 char **afc_get_dir_list(AFClient *client, const char *dir) {
+        int bytes = 0;
+        char *data = NULL, **list = NULL;
+        
+        if (!client || !dir) return NULL;
+
         afc_lock(client);
+        
+        // Send the command
         client->afc_packet->operation = AFC_LIST_DIR;
-        int bytes = 0;
-        char *blah = NULL, **list = NULL;
-        client->afc_packet->entire_length = client->afc_packet->this_length = 0;
+        client->afc_packet->entire_length = 0;
+        client->afc_packet->this_length = 0;
         bytes = dispatch_AFC_packet(client, dir, strlen(dir));
-        if (bytes <= 0) { afc_unlock(client); return NULL; }
+        if (bytes <= 0) {
+                afc_unlock(client);
+                return NULL;
+        }
         
-        bytes = receive_AFC_data(client, &blah);
-        if (bytes < 0 && !blah) { afc_unlock(client); return NULL; }
+        // Receive the data
+        bytes = receive_AFC_data(client, &data);
+        if (bytes < 0 && !data) {
+                afc_unlock(client);
+                return NULL;
+        }
         
-        list = make_strings_list(blah, bytes);
-        free(blah);
+        // Parse the data
+        list = make_strings_list(data, bytes);
+        if (data) free(data);
+
         afc_unlock(client);
+        
         return list;
 }
 
+/** Get device info for a client connection to phone. (free space on disk, etc.)
+ * 
+ * @param client The client to get device info for.
+ * 
+ * @return A char ** list of parameters as given by AFC or NULL if there was an
+ *         error.
+ */
 char **afc_get_devinfo(AFClient *client) {
+        int bytes = 0;
+        char *data = NULL, **list = NULL;
+        
+        if (!client) return NULL;
+
         afc_lock(client);
+        
+        // Send the command
         client->afc_packet->operation = AFC_GET_DEVINFO;
-        int bytes = 0;
-        char *blah = NULL, **list = NULL;
         client->afc_packet->entire_length = client->afc_packet->this_length = 0;
         bytes = dispatch_AFC_packet(client, NULL, 0);
-        if (bytes < 0) { afc_unlock(client); return NULL; }
+        if (bytes < 0) {
+                afc_unlock(client);
+                return NULL;
+        }
         
-        bytes = receive_AFC_data(client, &blah);
-        if (bytes < 0 && !blah) { afc_unlock(client); return NULL; } 
+        // Receive the data
+        bytes = receive_AFC_data(client, &data);
+        if (bytes < 0 && !data) {
+                afc_unlock(client);
+                return NULL;
+        } 
+        
+        // Parse the data
+        list = make_strings_list(data, bytes);
+        if (data) free(data);
         
-        list = make_strings_list(blah, bytes);
-        free(blah);
         afc_unlock(client);
+
         return list;
 }
 
-        
+/** Deletes a file.
+ * 
+ * @param client The client to have delete the file.
+ * @param path The file to delete. (must be a fully-qualified path)
+ * 
+ * @return 1 on success, 0 on failure.
+ */
 int afc_delete_file(AFClient *client, const char *path) {
+        char *response = NULL;
+        int bytes;
+        
         if (!client || !path || !client->afc_packet || !client->connection) return 0;
+        
         afc_lock(client);
-        char *receive = NULL;
+        
+        // Send command
         client->afc_packet->this_length = client->afc_packet->entire_length = 0;
         client->afc_packet->operation = AFC_DELETE;
-        int bytes;
         bytes = dispatch_AFC_packet(client, path, strlen(path));
-        if (bytes <= 0) { afc_unlock(client); return 0; }
+        if (bytes <= 0) {
+                afc_unlock(client);
+                return 0;
+        }
+
+        // Receive response
+        bytes = receive_AFC_data(client, &response);
+        if (response) free(response);
         
-        bytes = receive_AFC_data(client, &receive);
-        free(receive);
         afc_unlock(client);
-        if (bytes < 0) { return 0; }
-        else return 1;
+        
+        if (bytes < 0) {
+                return 0;
+        } else {
+                return 1;
+        }
 }
 
+/** Renames a file on the phone. 
+ * 
+ * @param client The client to have rename the file.
+ * @param from The file to rename. (must be a fully-qualified path)
+ * @param to The new name of the file. (must also be a fully-qualified path)
+ * 
+ * @return 1 on success, 0 on failure.
+ */
 int afc_rename_file(AFClient *client, const char *from, const char *to) {
-        if (!client || !from || !to || !client->afc_packet || !client->connection) return 0;
-        afc_lock(client);
-        char *receive = NULL;
+        char *response = NULL;
         char *send = (char*)malloc(sizeof(char) * (strlen(from) + strlen(to) + 1 + sizeof(uint32)));
         int bytes = 0;
         
+        if (!client || !from || !to || !client->afc_packet || !client->connection) return 0;
+        
+        afc_lock(client);
+        
+        // Send command
         memcpy(send, from, strlen(from)+1);
         memcpy(send+strlen(from)+1, to, strlen(to));
-        fwrite(send, 1, strlen(from)+1+strlen(to), stdout);
-        printf("\n");
         client->afc_packet->entire_length = client->afc_packet->this_length = 0;
         client->afc_packet->operation = AFC_RENAME;
         bytes = dispatch_AFC_packet(client, send, strlen(to) + strlen(from) + 2);
-        if (bytes <= 0) { afc_unlock(client); return 0; }
+        if (bytes <= 0) {
+                afc_unlock(client);
+                return 0;
+        }
         
-        bytes = receive_AFC_data(client, &receive);
-        free(receive);
+        // Receive response
+        bytes = receive_AFC_data(client, &response);
+        if (response) free(response);
+
         afc_unlock(client);
-        if (bytes < 0) return 0;
-        else return 1;
+        
+        if (bytes < 0) {
+                return 0;
+        } else {
+                return 1;
+        }
 }
 
+/** 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
+ *        all other mkdir restrictions apply as well)
+ * 
+ * @return 1 on success, 0 on failure.
+ */
+
 int afc_mkdir(AFClient *client, const char *dir) {
+        int bytes = 0;
+        char *response = NULL;
+        
         if (!client) return 0;
+        
         afc_lock(client);
-        int bytes = 0;
-        char *recvd = NULL;
         
+        // Send command
         client->afc_packet->operation = AFC_MAKE_DIR;
         client->afc_packet->this_length = client->afc_packet->entire_length = 0;
         bytes = dispatch_AFC_packet(client, dir, strlen(dir));
-        if (bytes <= 0) { afc_unlock(client); return 0; }
+        if (bytes <= 0) {
+                afc_unlock(client);
+                return 0;
+        }
         
-        bytes = receive_AFC_data(client, &recvd);
+        // Receive response
+        bytes = receive_AFC_data(client, &response);
+        if (response) free(response);
+
         afc_unlock(client);
-        if (recvd) { free(recvd); recvd = NULL; }
-        if (bytes == 0) return 1;
-        else return 0;
+        
+        if (bytes == 0) {
+                return 1;
+        } else {
+                return 0;
+        }
 }
 
+/** 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. 
+ * 
+ * @return A pointer to an AFCFile struct containing the information received,
+ *         or NULL on failure.
+ */
 AFCFile *afc_get_file_info(AFClient *client, const char *path) {
-        client->afc_packet->operation = AFC_GET_INFO;
-        client->afc_packet->entire_length = client->afc_packet->this_length = 0;
-        afc_lock(client);
-        dispatch_AFC_packet(client, path, strlen(path));
-        
         char *received, **list;
         AFCFile *my_file;
         int length, i = 0;
         
+        afc_lock(client);
+        
+        // Send command
+        client->afc_packet->operation = AFC_GET_INFO;
+        client->afc_packet->entire_length = client->afc_packet->this_length = 0;
+        dispatch_AFC_packet(client, path, strlen(path));
+        
+        // Receive data
         length = receive_AFC_data(client, &received);
-        list = make_strings_list(received, length);
-        free(received);
-        afc_unlock(client); // the rest is just interpretation anyway
+        if (received) {
+                list = make_strings_list(received, length);
+                free(received);
+        } else {
+                afc_unlock(client);
+                return NULL;
+        }
+
+        afc_unlock(client);
+        
+        // Parse the data
         if (list) {
                 my_file = (AFCFile *)malloc(sizeof(AFCFile));
                 for (i = 0; strcmp(list[i], ""); i++) {
@@ -383,42 +567,62 @@ AFCFile *afc_get_file_info(AFClient *client, const char *path) {
         }
 }
 
+/** 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)
+ * @param file_mode The mode to use to open the file. Can be AFC_FILE_READ or
+ *                  AFC_FILE_WRITE; the former lets you read and write,
+ *                  however, and the second one will *create* the file,
+ *                  destroying anything previously there.
+ * 
+ * @return A pointer to an AFCFile struct containing the file information (as
+ *         received by afc_get_file_info) as well as the handle to the file or
+ *         NULL in the case of failure.
+ */
 AFCFile *afc_open_file(AFClient *client, const char *filename, uint32 file_mode) {
-        //if (file_mode != AFC_FILE_READ && file_mode != AFC_FILE_WRITE) return NULL;
-        if (!client ||!client->connection || !client->afc_packet) return NULL;
-        afc_lock(client);
-        char *further_data = (char*)malloc(sizeof(char) * (8 + strlen(filename) + 1));
         AFCFile *file_infos = NULL;
-        memcpy(further_data, &file_mode, 4);
         uint32 ag = 0;
-        memcpy(further_data+4, &ag, 4);
-        memcpy(further_data+8, filename, strlen(filename));
-        further_data[8+strlen(filename)] = '\0';
-        int bytes = 0, length_thing = 0;
-        client->afc_packet->operation = AFC_FILE_OPEN;
+        int bytes = 0, length = 0;
+        char *data = (char*)malloc(sizeof(char) * (8 + strlen(filename) + 1));
+        
+        if (!client ||!client->connection || !client->afc_packet) return NULL;
+        
+        afc_lock(client);
         
+        // Send command
+        memcpy(data, &file_mode, 4);
+        memcpy(data+4, &ag, 4);
+        memcpy(data+8, filename, strlen(filename));
+        data[8+strlen(filename)] = '\0';
+        client->afc_packet->operation = AFC_FILE_OPEN;
         client->afc_packet->entire_length = client->afc_packet->this_length = 0;
-        bytes = dispatch_AFC_packet(client, further_data, 8+strlen(filename));
-        free(further_data);
+        bytes = dispatch_AFC_packet(client, data, 8+strlen(filename));
+        free(data);
+        
         if (bytes <= 0) {
-                if (debug) printf("didn't read enough\n");
+                if (debug) fprintf(stderr, "afc_open_file: Didn't receive a response to the command\n");
                 afc_unlock(client);
                 return NULL;
+        }
+        
+        // Receive the data
+        length = receive_AFC_data(client, &data);
+        if (length > 0 && data) {
+                afc_unlock(client);
+
+                // Get the file info and return it
+                file_infos = afc_get_file_info(client, filename);
+                memcpy(&file_infos->filehandle, data, 4);
+                return file_infos;
         } else {
-                length_thing = receive_AFC_data(client, &further_data);
-                if (length_thing > 0 && further_data) {
-                        afc_unlock(client); // don't want to hang on the next call... and besides, it'll re-lock, do its thing, and unlock again anyway.
-                        file_infos = afc_get_file_info(client, filename);
-                        memcpy(&file_infos->filehandle, further_data, 4);
-                        return file_infos;
-                } else {
-                        if (debug) printf("didn't get further data or something\n");
-                        afc_unlock(client);
-                        return NULL;
-                }
+                if (debug) fprintf(stderr, "afc_open_file: Didn't get any further data\n");
+                afc_unlock(client);
+                return NULL;
         }
-        if (debug) printf("what the fuck\n");
+
         afc_unlock(client);
+        
         return NULL;
 }
 
@@ -429,22 +633,21 @@ AFCFile *afc_open_file(AFClient *client, const char *filename, uint32 file_mode)
  * @param data The pointer to the memory region to store the read data
  * @param length The number of bytes to read
  *
- * @return The number of bytes read if successful. If there was an error
+ * @return The number of bytes read if successful. If there was an error -1.
  */
 int afc_read_file(AFClient *client, AFCFile *file, char *data, int length) {
-        if (!client || !client->afc_packet || !client->connection || !file) return -1;
-        if (debug) printf("afc_read_file called for length %i\n", length);
-
         char *input = NULL;
         int current_count = 0, bytes = 0;
         const int MAXIMUM_READ_SIZE = 1 << 16;
 
-        afc_lock(client);
+        if (!client || !client->afc_packet || !client->connection || !file) return -1;
+        if (debug) fprintf(stderr, "afc_read_file called for length %i\n", length);
 
+        afc_lock(client);
 
         // Looping here to get around the maximum amount of data that recieve_AFC_data can handle
         while (current_count < length){
-                if (debug) printf("afc_read_file: current count is %i but length is %i\n", current_count, length);
+                if (debug) fprintf(stderr, "afc_read_file: current count is %i but length is %i\n", current_count, length);
                 
                 // Send the read command
                 AFCFilePacket *packet = (AFCFilePacket*)malloc(sizeof(AFCFilePacket));
@@ -455,120 +658,182 @@ int afc_read_file(AFClient *client, AFCFile *file, char *data, int length) {
                 client->afc_packet->entire_length = client->afc_packet->this_length = 0;
                 bytes = dispatch_AFC_packet(client, (char*)packet, sizeof(AFCFilePacket));
                 
-                // If we get a positive reponse to the command gather the data
-                if (bytes > 0) {
-                        bytes = receive_AFC_data(client, &input);
-                        if (debug) printf("afc_read_file: bytes returned: %i\n", bytes);
-                        if (bytes < 0) {
-                                if (input) free(input);
-                                afc_unlock(client);
-                                return -1;
-                        } else if (bytes == 0) {
-                                if (input) free(input);
-                                afc_unlock(client);
-                                return current_count;
-                        } else {
-                                if (input) {
-                                        if (debug) printf("afc_read_file: %d\n", bytes);
-                                        memcpy(data+current_count, input, (bytes > length) ? length : bytes);
-                                        free(input);
-                                        input = NULL;
-                                        current_count += (bytes > length) ? length : bytes;
-                                }
-                        }
-                } else {
+                if (bytes <= 0) {
                         afc_unlock(client);
                         return -1;
                 }
+
+                // Receive the data
+                bytes = receive_AFC_data(client, &input);
+                if (debug) fprintf(stderr, "afc_read_file: bytes returned: %i\n", bytes);
+                if (bytes < 0) {
+                        if (input) free(input);
+                        afc_unlock(client);
+                        return -1;
+                } else if (bytes == 0) {
+                        if (input) free(input);
+                        afc_unlock(client);
+                        return current_count;
+                } else {
+                        if (input) {
+                                if (debug) fprintf(stderr, "afc_read_file: %d\n", bytes);
+                                memcpy(data+current_count, input, (bytes > length) ? length : bytes);
+                                free(input);
+                                input = NULL;
+                                current_count += (bytes > length) ? length : bytes;
+                        }
+                }
         }
+        if (debug) fprintf(stderr, "afc_read_file: returning current_count as %i\n", current_count);
+        
         afc_unlock(client);
-        if (debug) printf("afc_read_file: returning current_count as %i\n", current_count);
+        
         return current_count;
 }
 
+/** Writes a given number of bytes to a file.
+ * 
+ * @param client The client to use to write to the file.
+ * @param file A pointer to an AFCFile struct; serves as the file handle. 
+ * @param data The data to write to the file.
+ * @param length How much data to write.
+ * 
+ * @return The number of bytes written to the file, or a value less than 0 if
+ *         none were written...
+ */
+
 int afc_write_file(AFClient *client, AFCFile *file, const char *data, int length) {
         char *acknowledgement = NULL;
-        if (!client ||!client->afc_packet || !client->connection || !file) return -1;
-        afc_lock(client);
-        if (debug) printf("afc_write_file: Write length: %i\n", length);
         const int MAXIMUM_WRITE_SIZE = 1 << 16;
         uint32 zero = 0, bytes = 0, segments = (length / MAXIMUM_WRITE_SIZE), current_count = 0, i = 0;
         char *out_buffer = NULL;
+
+        if (!client ||!client->afc_packet || !client->connection || !file) return -1;
+        
+        afc_lock(client);
+        
+        if (debug) fprintf(stderr, "afc_write_file: Write length: %i\n", length);
         
-        for (i = 0; i < segments; i++) { // Essentially, yeah, divide it into segments.
+        // Divide the file into segments.
+        for (i = 0; i < segments; i++) {
+                // Send the segment
                 client->afc_packet->this_length = sizeof(AFCPacket) + 8;
-                //client->afc_packet->entire_length = client->afc_packet->this_length + length;
                 client->afc_packet->entire_length = client->afc_packet->this_length + MAXIMUM_WRITE_SIZE;
                 client->afc_packet->operation = AFC_WRITE;
                 out_buffer = (char*)malloc(sizeof(char) * client->afc_packet->entire_length - sizeof(AFCPacket));
                 memcpy(out_buffer, (char*)&file->filehandle, sizeof(uint32));
                 memcpy(out_buffer+4, (char*)&zero, sizeof(uint32));
                 memcpy(out_buffer+8, data+current_count, MAXIMUM_WRITE_SIZE);
-        
                 bytes = dispatch_AFC_packet(client, out_buffer, MAXIMUM_WRITE_SIZE + 8);
-                if (bytes < 0) { afc_unlock(client); return bytes; }
-                free(out_buffer); out_buffer = NULL; // cleanup and hope it works
+                if (bytes < 0) {
+                        afc_unlock(client);
+                        return bytes;
+                }
+                free(out_buffer);
+                out_buffer = NULL;
+                
                 current_count += bytes;
                 bytes = receive_AFC_data(client, &acknowledgement); 
-                if (bytes < 0) { afc_unlock(client); return current_count; }
+                if (bytes < 0) {
+                        afc_unlock(client);
+                        return current_count;
+                }
         }
         
         // 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); return current_count; }
+        if (current_count == length) {
+                afc_unlock(client);
+                return current_count;
+        }
+        
         client->afc_packet->this_length = sizeof(AFCPacket) + 8;
         client->afc_packet->entire_length = client->afc_packet->this_length + (length - current_count);
-        // operation is already AFC_WRITE, but set again to be sure
         client->afc_packet->operation = AFC_WRITE;
         out_buffer = (char*)malloc(sizeof(char) * client->afc_packet->entire_length - sizeof(AFCPacket));
         memcpy(out_buffer, (char*)&file->filehandle, sizeof(uint32));
         memcpy(out_buffer+4, (char*)&zero, sizeof(uint32));
         memcpy(out_buffer+8, data+current_count, (length - current_count));
         bytes = dispatch_AFC_packet(client, out_buffer, (length - current_count) + 8);
-        free(out_buffer); out_buffer = NULL;
+        free(out_buffer);
+        out_buffer = NULL;
+        
         current_count += bytes;
-        if (bytes <= 0) { afc_unlock(client); return current_count; }
+        
+        if (bytes <= 0) {
+                afc_unlock(client);
+                return current_count;
+        }
         
         zero = bytes;
         bytes = receive_AFC_data(client, &acknowledgement);
         afc_unlock(client);
         if (bytes < 0) {
-                if (debug) printf("afc_write_file: uh oh?\n");
+                if (debug) fprintf(stderr, "afc_write_file: uh oh?\n");
         }
         
         return current_count;
 }
 
+/** Closes a file on the phone. 
+ * 
+ * @param client The client to close the file with.
+ * @param file A pointer to an AFCFile struct containing the file handle of the
+ *        file to close.
+ */
 void afc_close_file(AFClient *client, AFCFile *file) {
         char *buffer = malloc(sizeof(char) * 8);
         uint32 zero = 0;
-        if (debug) printf("File handle %i\n", file->filehandle);
+        int bytes = 0;
+        
         afc_lock(client);
+        
+        if (debug) fprintf(stderr, "afc_close_file: File handle %i\n", file->filehandle);
+        
+        // Send command
         memcpy(buffer, &file->filehandle, sizeof(uint32));
         memcpy(buffer+sizeof(uint32), &zero, sizeof(zero));
         client->afc_packet->operation = AFC_FILE_CLOSE;
-        int bytes = 0;
         client->afc_packet->entire_length = client->afc_packet->this_length = 0;
         bytes = dispatch_AFC_packet(client, buffer, sizeof(char) * 8);
-
         free(buffer);
-        client->afc_packet->entire_length = client->afc_packet->this_length = 0;
-        if (bytes <= 0) { afc_unlock(client); return; }
+        buffer = NULL;
+
+        // FIXME: Is this necesary?
+        //client->afc_packet->entire_length = client->afc_packet->this_length = 0;
         
+        if (bytes <= 0) { 
+                afc_unlock(client); 
+                return;
+        }
+        
+        // Receive the response
         bytes = receive_AFC_data(client, &buffer);
+        if (buffer) free(buffer);
+        
         afc_unlock(client);
-        if (buffer) { free(buffer); }
-        return;
 }
 
+/** 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 file The file to seek to a position on.
+ * @param seekpos Where to seek to. If passed a negative value, this will seek
+ *        from the end of the file. 
+ * 
+ * @return 0 on success, -1 on failure.
+ */
+
 int afc_seek_file(AFClient *client, AFCFile *file, int seekpos) {
-        afc_lock(client);
-        
         char *buffer = (char*)malloc(sizeof(char) * 24);
         uint32 seekto = 0, bytes = 0, zero = 0;
+        
         if (seekpos < 0) seekpos = file->size - abs(seekpos);
-        seekto = seekpos;
+
+        afc_lock(client);
         
+        // Send the command
+        seekto = seekpos;
         memcpy(buffer, &file->filehandle, sizeof(uint32)); // handle
         memcpy(buffer+4, &zero, sizeof(uint32)); // pad
         memcpy(buffer+8, &zero, sizeof(uint32)); // fromwhere
@@ -578,22 +843,45 @@ int afc_seek_file(AFClient *client, AFCFile *file, int seekpos) {
         client->afc_packet->operation = AFC_FILE_SEEK;
         client->afc_packet->this_length = client->afc_packet->entire_length = 0;
         bytes = dispatch_AFC_packet(client, buffer, 23);
-        free(buffer); buffer = NULL;
-        if (bytes <= 0) { afc_unlock(client); return -1; }
+        free(buffer);
+        buffer = NULL;
+        
+        if (bytes <= 0) { 
+                afc_unlock(client);
+                return -1;
+        }
         
+        // Receive response
         bytes = receive_AFC_data(client, &buffer);
         if (buffer) free(buffer);
+        
         afc_unlock(client);
-        if (bytes >= 0) return 0;
-        else return -1;
+        
+        if (bytes >= 0) {
+                return 0;
+        } else {
+                return -1;
+        }
 }
 
+/** Sets the size of a file on the phone.
+ * 
+ * @param client The client to use to set the file size.
+ * @param file The (pre-opened) file to set the size on.
+ * @param newsize The size to set the file to. 
+ * 
+ * @return 0 on success, -1 on failure. 
+ * 
+ * @note This function is more akin to ftruncate than truncate, and truncate
+ *       calls would have to open the file before calling this, sadly.
+ */
 int afc_truncate_file(AFClient *client, AFCFile *file, uint32 newsize) {
-        afc_lock(client);
-        
         char *buffer = (char*)malloc(sizeof(char) * 16);
         uint32 bytes = 0, zero = 0;
         
+        afc_lock(client);
+        
+        // Send command
         memcpy(buffer, &file->filehandle, sizeof(uint32)); // handle
         memcpy(buffer+4, &zero, sizeof(uint32)); // pad
         memcpy(buffer+8, &newsize, sizeof(uint32)); // newsize
@@ -601,13 +889,23 @@ int afc_truncate_file(AFClient *client, AFCFile *file, uint32 newsize) {
         client->afc_packet->operation = AFC_FILE_TRUNCATE;
         client->afc_packet->this_length = client->afc_packet->entire_length = 0;
         bytes = dispatch_AFC_packet(client, buffer, 15);
-        free(buffer); buffer = NULL;
-        if (bytes <= 0) { afc_unlock(client); return -1; }
+        free(buffer);
+        buffer = NULL;
+
+        if (bytes <= 0) {
+                afc_unlock(client);
+                return -1;
+        }
         
+        // Receive response
         bytes = receive_AFC_data(client, &buffer);
         if (buffer) free(buffer);
+        
         afc_unlock(client);
-        if (bytes >= 0) return 0;
-        else return -1;
+        
+        if (bytes >= 0) {
+                return 0;
+        } else {
+                return -1;
+        }
 }
-