[PATCH] usbmuxd/libusbmuxd.h: separate logic from implementation

tweak public parameter and struct names for clarity
fix usbmuxd_scan() to return number of devices per documentation
expand public documentation in libusbmux.h

Signed-off-by: Nikias Bassen <nikias@gmx.li>

4 files changed, 59 insertions, 33 deletions

diff --git a/iproxy.c b/iproxy.c
index 896dbff..199c51e 100644
--- a/iproxy.c
+++ b/iproxy.c
@@ -31,7 +31,6 @@
 #include <errno.h>
 #include <arpa/inet.h>
 #include <pthread.h>
-#include <usbmuxd.h>
 #include "sock_stuff.h"
 #include "libusbmuxd.h"
 
@@ -142,7 +141,7 @@ void *run_ctos_loop(void *arg)
 void *acceptor_thread(void *arg)
 {
     struct client_data *cdata;
-    usbmuxd_device_t *dev_list = NULL;
+    usbmuxd_scan_result *dev_list = NULL;
     pthread_t ctos;
 
     if (!arg) {
@@ -152,21 +151,21 @@ void *acceptor_thread(void *arg)
 
     cdata = (struct client_data*)arg;
 
-    if (usbmuxd_scan(&dev_list) != 0) {
+    if (usbmuxd_scan(&dev_list) < 0) {
 	printf("Connecting to usbmuxd failed, terminating.\n");
 	free(dev_list);
 	return NULL;
     }
 
-    if (!dev_list || dev_list[0].device_id == 0) {
+    if (dev_list == NULL || dev_list[0].handle == 0) {
 	printf("No connected device found, terminating.\n");
 	free(dev_list);
 	return NULL;
     }
 
-    fprintf(stdout, "Requesting connecion to device %d port %d\n", dev_list[0].device_id, device_port);
+    fprintf(stdout, "Requesting connecion to device handle == %d, port %d\n", dev_list[0].handle, device_port);
 
-    cdata->sfd = usbmuxd_connect(dev_list[0].device_id, device_port);
+    cdata->sfd = usbmuxd_connect(dev_list[0].handle, device_port);
     free(dev_list);
     if (cdata->sfd < 0) {
     	fprintf(stderr, "Error connecting to device!\n");
@@ -191,7 +190,7 @@ int main(int argc, char **argv)
     int mysock = -1;
 
     if (argc != 3) {
-	printf("usage: %s LOCAL_PORT DEVICE_PORT\n", argv[0]);
+	printf("usage: %s LOCAL_TCP_PORT DEVICE_TCP_PORT\n", argv[0]);
 	return 0;
     }
 
diff --git a/libusbmuxd.c b/libusbmuxd.c
index 4e4ec10..ed331aa 100644
--- a/libusbmuxd.c
+++ b/libusbmuxd.c
@@ -7,7 +7,11 @@
 #include <arpa/inet.h>
 #include <unistd.h>
 
+// usbmuxd public interface
+#include <libusbmuxd.h>
+// usbmuxd protocol 
 #include <usbmuxd.h>
+// socket utility functions
 #include "sock_stuff.h"
 
 static int usbmuxd_get_result(int sfd, uint32_t tag, uint32_t *result)
@@ -40,7 +44,7 @@ static int usbmuxd_get_result(int sfd, uint32_t tag, uint32_t *result)
     return -1;
 }
 
-int usbmuxd_scan(usbmuxd_device_t **devices)
+int usbmuxd_scan(usbmuxd_scan_result **available_devices)
 {
 	struct usbmuxd_scan_request s_req;
 	int sfd;
@@ -48,7 +52,7 @@ int usbmuxd_scan(usbmuxd_device_t **devices)
 	uint32_t res;
 	uint32_t pktlen;
 	int recv_len;
-	usbmuxd_device_t *newlist = NULL;
+	usbmuxd_scan_result *newlist = NULL;
 	struct usbmuxd_device_info_record dev_info_pkt;
 	int dev_cnt = 0;
 
@@ -81,7 +85,7 @@ int usbmuxd_scan(usbmuxd_device_t **devices)
 		return -1;
 	}
 
-	*devices = NULL;
+	*available_devices = NULL;
 	// receive device list
 	while (1) {
 		if (recv_buf_timeout(sfd, &pktlen, 4, MSG_PEEK, 500) == 4) {
@@ -99,10 +103,14 @@ int usbmuxd_scan(usbmuxd_device_t **devices)
 				fprintf(stderr, "%s: received less data than specified in header!\n", __func__);
 			} else {
 				//fprintf(stderr, "%s: got device record with id %d, UUID=%s\n", __func__, dev_info_pkt.device_info.device_id, dev_info_pkt.device_info.serial_number);
-				newlist = (usbmuxd_device_t*)realloc(*devices, sizeof(usbmuxd_device_t) * (dev_cnt+1));
+				newlist = (usbmuxd_scan_result *)realloc(*available_devices, sizeof(usbmuxd_scan_result) * (dev_cnt+1));
 				if (newlist) {
-					memcpy(newlist+dev_cnt, &dev_info_pkt.device, sizeof(usbmuxd_device_t));
-					*devices = newlist;
+					newlist[dev_cnt].handle = (int)dev_info_pkt.device.device_id;
+					newlist[dev_cnt].product_id = dev_info_pkt.device.product_id;
+					memset(newlist[dev_cnt].serial_number, '\0', sizeof(newlist[dev_cnt].serial_number));
+					memcpy(newlist[dev_cnt].serial_number, dev_info_pkt.device.serial_number,
+					       sizeof(dev_info_pkt.device.serial_number));
+					*available_devices = newlist;
 					dev_cnt++;
 				} else {
 					fprintf(stderr, "%s: ERROR: out of memory when trying to realloc!\n", __func__);
@@ -117,14 +125,14 @@ int usbmuxd_scan(usbmuxd_device_t **devices)
 	}
 
 	// terminating zero record
-	newlist = (usbmuxd_device_t*)realloc(*devices, sizeof(usbmuxd_device_t) * (dev_cnt+1));
-	memset(newlist+dev_cnt, 0, sizeof(usbmuxd_device_t));
-	*devices = newlist;
+	newlist = (usbmuxd_scan_result *)realloc(*available_devices, sizeof(usbmuxd_scan_result) * (dev_cnt+1));
+	memset(newlist+dev_cnt, 0, sizeof(usbmuxd_scan_result));
+	*available_devices = newlist;
 
-	return 0;
+	return dev_cnt;
 }
 
-int usbmuxd_connect(uint32_t device_id, uint16_t port)
+int usbmuxd_connect(const int handle, const unsigned short tcp_port)
 {
 	int sfd;
 	struct usbmuxd_connect_request c_req;
@@ -141,8 +149,8 @@ int usbmuxd_connect(uint32_t device_id, uint16_t port)
 	c_req.header.reserved = 0;
 	c_req.header.type = USBMUXD_CONNECT;
 	c_req.header.tag = 3;
-	c_req.device_id = device_id;
-	c_req.tcp_dport = htons(port);
+	c_req.device_id = (uint32_t)handle;
+	c_req.tcp_dport = htons(tcp_port);
 	c_req.reserved = 0;
 
 	if (send_buf(sfd, &c_req, sizeof(c_req)) < 0) {
diff --git a/libusbmuxd.h b/libusbmuxd.h
index 82f9a47..da99f1f 100644
--- a/libusbmuxd.h
+++ b/libusbmuxd.h
@@ -1,27 +1,45 @@
 #ifndef __LIBUSBMUXD_H
 #define __LIBUSBMUXD_H
 
-#include <usbmuxd.h>
+/**
+ * Array entry returned by 'usbmuxd_scan()' scanning.
+ *
+ * If more than one device is available, 'product_id' and
+ * 'serial_number' and be analysed to help make a selection.
+ * The relevant 'handle' should be passed to 'usbmuxd_connect()', to
+ * start a proxy connection.  The value 'handle' should be considered
+ * opaque and no presumption made about the meaning of its value.
+ */
+typedef struct {
+	int handle;
+	int product_id;
+	char serial_number[41];
+} usbmuxd_scan_result;
 
 /**
- * Contacts usbmuxd via it's unix domain socket and performs a scan for
- *  connected devices.
+ * Contacts usbmuxd and performs a scan for connected devices.
  *
- * @param devices Pointer to an array of usbmuxd_device_t.
- * 	 Assumed initially NULL, will be allocated by this function.
+ * @param available_devices pointer to array of usbmuxd_scan_result.
+ * 	Array of available devices.  The required 'handle'
+ *	should be passed to 'usbmuxd_connect()'.  The returned array
+ *	is zero-terminated for convenience; the final (unused)
+ *	entry containing handle == 0.  The returned array pointer
+ *	should be freed by passing to 'free()' after use.
  *
- * @return number of devices found, negative on error
+ * @return number of available devices, zero on no devices, or negative on error
  */
-int usbmuxd_scan(usbmuxd_device_t **devices);
+int usbmuxd_scan(usbmuxd_scan_result **available_devices);
 
 /**
- * Performs the connect procedure via usbmuxd.
+ * Request proxy connect to 
+ *
+ * @param handle returned by 'usbmuxd_scan()'
  *
- * @param device_id USB device number of the device to connect to
- * @param port Port number to connect to
+ * @param tcp_port TCP port number on device, in range 0-65535.
+ *	common values are 62078 for lockdown, and 22 for SSH.
  *
- * @return socket of the connection, negative on error
+ * @return file descriptor socket of the connection, or -1 on error
  */
-int usbmuxd_connect(uint32_t device_id, uint16_t port);
+int usbmuxd_connect(const int handle, const unsigned short tcp_port);
 
 #endif /* __LIBUSBMUXD_H */
diff --git a/usbmuxd.h b/usbmuxd.h
index 0749c87..cc9b9d7 100644
--- a/usbmuxd.h
+++ b/usbmuxd.h
@@ -1,3 +1,5 @@
+/* Protocol defintion for usbmuxd proxy protocol */
+
 #ifndef __USBMUXD_H
 #define __USBMUXD_H
 
@@ -29,7 +31,6 @@ struct usbmuxd_device {
 	uint16_t product_id;
 	char serial_number[40];
 } __attribute__((__packed__));
-typedef struct usbmuxd_device usbmuxd_device_t;
 
 struct usbmuxd_device_info_record {
 	struct usbmuxd_header header;